IBM Cloud VPCのAPIを使って、仮想サーバーインスタンスを作成する

# はじめに
IBM Cloud Virtual Private Cloud(VPC)のAPIを使用して仮想サーバーインスタンス(VSI)を構築する方法をご紹介します。API経由でVSIを作成するメリットとして、環境構築の自動化ができたり、UI上で選択できないバージョンのOSイメージからVSIを作成することができたりします。
また、1度はUIでIBM Cloud VPCでのVSI作成を実施したことがある方を読者として想定しています。まだ作成した経験がない方は、以下の記事を参照してVSIを1台作ってみてください。

参考
- [IBM Cloud Virtual Private Cloud (VPC) 構築実践チュートリアル](https://qiita.com/6onoda/items/06f9a4b1090d05ea0813 "https://qiita.com/6onoda/items/06f9a4b1090d05ea0813")
- [【IBM Cloud】Virtual server for VPCを作成する流れ](https://qiita.com/Sungyun_Moon/items/82e4fbe5056c7918bc54 "https://qiita.com/Sungyun_Moon/items/82e4fbe5056c7918bc54")

# 1. IAMトークンの取得
IBM CloudのサービスをAPIで呼び出す際には、IAMトークンが必要です。

まずはibmcloudコマンドでログインします。
```
$ ibmcloud login
```
今回はibmcloudコマンドを使って、自分のアカウントのトークンを取得します。
```
$ iam_token=`ibmcloud iam oauth-tokens | awk '{printf $4}'`
$ echo ${iam_token}
```
参考
- [IBM CloudにおけるIAMトークンの取得方法](https://qiita.com/testnin2/items/3a4ca8a1a2b79b713c48 "https://qiita.com/testnin2/items/3a4ca8a1a2b79b713c48")

# 2. VSIの作成
次のコマンドを実行すると、`ibm-redhat-9-2-minimal-amd64-3`のイメージを使用した仮想サーバーインスタンスが作成されます。

```
curl -X POST "https://jp-tok.iaas.cloud.ibm.com/v1/instances?version=2023-12-13&generation=2" -H "Authorization: Bearer $iam_token" -d '{
  "name": "my-instance",
  "vpc": {
    "id": "r022-8badf872-f8fc-475a-98dd-c39d6afc7d72"
  },
  "zone": {
    "name": "jp-tok-3"
  },
  "profile": {
    "name": "bx2-2x8"
  },
  "image": {
    "id": "r022-05349234-0a12-4065-8710-4c5f6a3dda4a"
  },
  "keys": [
    {
      "id": "r022-d6363b4d-d1ff-4480-b431-ad68be54f15b"
    }
  ],
  "primary_network_interface": {
    "name": "eth0",
    "subnet": {
      "id": "02g7-0ff6aaa9-4f55-4059-9897-cf84c7973a43"
    }
  }
}'
```
上記の例のパラメータは以下です。VPCやSSH鍵、サブネットは事前に作成しています。また、これらのパラメータは環境に応じて変更してください。
| Parameter | 設定内容 |
|:-:|:--|
| name | 作成する仮想サーバーインスタンスの名前 |
| vpc.id | 仮想サーバーインスタンスが作成されるVPCのID。VPCの詳細画面から確認できます。|
| zone.name | 仮想サーバーインスタンスが作成されるゾーン名。東京3は`jp-tok-3`です。|
| profile | 仮想サーバーインスタンスが使用するプロファイル。サーバーのサイズと機能を定義します。|
| image.id | 仮想サーバーインスタンスが使用するイメージのID。イメージのIDはイメージの詳細画面から確認できます。今回はストックイメージを使用しています。|
| keys.id | SSH鍵のID。SSH鍵のIDはSSH鍵の詳細画面から確認できます。| 
| primary_network_interface.name | プライマリネットワークインタフェースの名前。 |
| primary_network_interface.subnet.id | プライマリネットワークインタフェースのサブネットのID。サブネットのIDはサブネットの詳細画面から確認できます。 |

参考
[Create an instance - Virtual Private Cloud API | IBM Cloud API Docs](https://cloud.ibm.com/apidocs/vpc/latest#create-instance "https://cloud.ibm.com/apidocs/vpc/latest#create-instance")

# 3. VSIの情報の取得
作成されたVSIの情報はUI上でも確認できますが、API経由でVSIの情報を取得して確認することができます。

```
curl -X GET "https://jp-tok.iaas.cloud.ibm.com/v1/instances?version=2023-12-13&generation=2" -H "Authorization: Bearer $iam_token"
```

参考
- [List all instances - Virtual Private Cloud API | IBM Cloud API Docs](https://cloud.ibm.com/apidocs/vpc/latest#list-instances "https://cloud.ibm.com/apidocs/vpc/latest#list-instances")

# (おまけ) 古いイメージの情報の取得
先ほどの例では、`image.id`の値として、(執筆時に)UI上でストックイメージの中から選択できるイメージのIDを使用しましたが、該当のOSの新しいバージョンがリリースされていくといつかはこのidはUI上で確認できなくなります。そのような場合でも、古くなり、UI上では確認できなくなったイメージ(ステータスが`deprecated`なイメージ)のIDは以下のAPIで調べることができます。

```
curl -X GET "https://jp-tok.iaas.cloud.ibm.com/v1/images?version=2023-12-13&generation=2&status=deprecated" -H "Authorization: Bearer $iam_token" > deprecated-images.json
```

参考
- [List all images - Virtual Private Cloud API | IBM Cloud API Docs](https://cloud.ibm.com/apidocs/vpc/latest#list-images "https://cloud.ibm.com/apidocs/vpc/latest#list-images")
- [ゲスト・オペレーティング・システムのライフサイクル | IBM Cloud 資料](https://cloud.ibm.com/docs/vpc?topic=vpc-guest-os-lifecycle&interface=ui "https://cloud.ibm.com/docs/vpc?topic=vpc-guest-os-lifecycle&interface=ui")