IBM Cloud CLI ことはじめ（Federated ID使用）

はじめに

IBM Cloud CLIを使い始めるまでに必要なステップを記載しています。環境はMacです。

公式ドキュメント

正確な情報源ということでとりあえず公式ドキュメントです。インストール方法や使用方法なども記載されています。通読する必要はないと思いますが、困ったときに立ち戻るところです。日本語版は最新の内容が反映されていないことがあるので英語版を参照するのが確実です。

• IBM Cloud CLI docs（公式ドキュメント）

リファレンスも公式ドキュメント内にあります。

• 汎用IBM Cloud CLI コマンドリファレンス

プラグインとして提供されているコマンドのリファレンスもあります。（以下はvpc-infrastructureの例です）

• VPC CLI コマンドリファレンス

インストール

インストールは下記のコマンドを実行するだけです。

% curl -fsSL https://clis.cloud.ibm.com/install/osx | sh

正常にインストールできるとibmcloudコマンドが使用できるようになります。

% ibmcloud -v
ibmcloud version 2.7.0+04dfeac-2022-04-28T17:19:42+00:00

（参考）
インストール手順 (公式ドキュメント)

Federated ID の場合の利用方法

IBM Cloudへのログイン認証を所属企業のSSO(Single Sign-On)アカウントで実施する場合、「federated IDを使用する」ということになります。federated IDを使用してログインするためには「API Key」か「ワンタイム・パスコード」が必要となります。（API Keyの取得方法とログイン手順については後述します）
ログインに成功すると１時間有効なIAMトークンが発行され、トークンが有効な間は各種サービスが利用できるようになります。IAMトークンはIBMCLOUD_HOME環境変数で指定されるconfiguration directory（デフォルトでは~/.bluemix)内にあるconfig.jsonというファイルに保管されるようです。ibmcloudコマンドはこのファイルの内容を読んで自動的に取得したIAMトークンを使用してくれるようですが、curlコマンド等で直接REST APIのエンドポイントにHTTPのリクエストを投げる場合は自分でHTTPヘッダーに明示的にIAMトークンを設定する必要があります。

API Keyの作成

API KeyはIBM Cloudのコンソールにブラウザからログインして作成します。Manageタブから「Access (IAM)」を選択して左のペインにある「API Keys」を選択します。

青い「Create an IBM Cloud API key」ボタンを押してAPI Keyを作成します。API Keyの値は作成したタイミングでしか確認することができないため、このタイミングで生成されたAPI Keyを忘れずに控えておきます。

ログインとIAMトークンの取得

API Keyが作成できたらibmcloudコマンドを使用してIBM Cloudにログインすることができるようになります。ログイン時にはREGIONやRESOURCE GROUPを合わせて指定します。（指定しなかった場合は対話的に聞かれます）以下はログインを実行するシェルの例です。API Keyは--apikey引数で渡します。API Keyを直接記載することもAPI Keyを格納するファイルを（@マークで）指定することも可能です。

login.sh

#!/bin/sh
REGION=jp-tok
RESOURCE_GROUP=default

# login
ibmcloud login --apikey @../etc/apikey.txt -a cloud.ibm.com -r ${REGION} -g ${RESOURCE_GROUP}

ログインに成功すると~/.bluemix/config.jsonにIAMトークンが設定されていることが確認できます。（一番下です）

% cat ~/.bluemix/config.json 
{
  "APIEndpoint": "https://cloud.ibm.com",
  "IsPrivate": false,
  "IsAccessFromVPC": false,
  "ConsoleEndpoint": "https://cloud.ibm.com",
  "ConsolePrivateEndpoint": "",
  "ConsolePrivateVPCEndpoint": "",
  "CloudType": "public",
  "CloudName": "bluemix",
  "CRIType": "",
  "Region": "jp-tok",
  "RegionID": "ibm:yp:jp-tok",
  "IAMEndpoint": "https://iam.cloud.ibm.com",
  "IAMPrivateEndpoint": "",
  "IAMPrivateVPCEndpoint": "",
  "IAMToken": "Bearer eyJraWQiOiIyMDIyMDQxNjA4MjQiLCJhbGciOiJSUzI1NiJ9.eyJpYW1faWQiOiJJQk1pZC0xMjAwMDBRNlE5IiwiaWQiOiJJQk1pZC0xMjAwMDB
・・・（以下略）

プラグインについて

IBM Cloud CLIはプラグインを追加することで機能を拡張することができます。
プラグインなしの汎用コマンドとしてはログイン、ログアウトやリージョン、リソースグループの指定などの基本的な操作だけが提供されています。VPCの操作やCOS(Cloud Object Storage)の操作などはプラグインです。
プラグインをインストールするにはibmcloud pluginコマンドを使用します。

ibmcloud plugin install <plugin-name>

現在導入しているプラグインはibmcloud plugin listコマンドで確認できます。

% ibmcloud plugin list
インストール済みプラグインをリストしています...

プラグイン名                                 バージョン   状況   サポートされるプライベート・エンドポイント   
cloud-object-storage                         1.4.0               false   
vpc-infrastructure[infrastructure-service]   4.0.3               true   

（参考）
Extending IBM Cloud CLI with plug-ins（プラグイン拡張についての公式ドキュメント）
ibmcloud pluginコマンドのリファレンス

IBM Cloud CLI 使用例

• VPC内のサブネットの一覧を表示

% ibmcloud is subnets
ユーザー xxxxxxx としてアカウント xxxxxxx の下でリソース・グループ default とリージョン jp-tok 内の サブネット をリストしています...
ID                                          名前             状況        サブネット CIDR   アドレス   ACL                            Public Gateway                             VPC       ゾーン     リソース・グループ   
02e7-eb8a77da-967b-444a-b2e3-xxxxxxxxxxxx   sn-20220501-01   available   10.X.0.0/24     251/256    matrix-dismay-treble-chapter   pgw-4d015e70-c8f9-11ec-965a-xxxxxxxxxxxx   ocp-vpc   jp-tok-1   default   
02f7-f2164287-a072-4201-a8c0-xxxxxxxxxxxx   sn-20220501-02   available   10.X.64.0/24    251/256    matrix-dismay-treble-chapter   pgw-6575beb0-c8f9-11ec-874f-yyyyyyyyyyyy   ocp-vpc   jp-tok-2   default   
02g7-7b9d7eff-2fd7-48c9-b710-xxxxxxxxxxxx   sn-20220501-03   available   10.X.128.0/24   251/256    matrix-dismay-treble-chapter   pgw-8611fb20-c8f9-11ec-965a-zzzzzzzzzzzz   ocp-vpc   jp-tok-3   default   

Misc

調べている際に少し引っかかった点について記載しておきます。

• IBM CloudのCLIは昔はbxまたはbluemixだったような気がしていたのですが、気づくとibmcloudになっていました。別物というわけではなく単に名称変更（リブランディング）されただけのようです。2018年5月15日付けのRelease Notesに書いてありました。
• ログインする際に気になりましたがOrganizationやSpaceはCloud Foundryのリソースを扱うときに使用するもののようです。Cloud Foundryのリソースを使用しない場合は特に気にしなくてもよさそうです。
• IaaSには旧いものと新しいものがあるようです。旧いものはClassic Infrastructureと呼ばれており、かつてSoftlayerとして知られていたものを指すようです。その名残でコマンド名にslなどとついているものがあったりします。新しいものはVPCと呼ばれ、Gen1とGen2があるようです。記事執筆時点の2022/5/4ではGen2を使用するのが一般的なようです。

※もし間違っているようでしたら指摘いただけるとうれしいです。