OCI CLI and SDK

解決する課題

OCI のリソース操作をコンソール(Web UI)だけで行うと、繰り返し作業の自動化や再現性の確保が難しくなります。OCI CLI と SDK は、テナンシのほぼ全 API をコマンドおよびプログラムコードから呼び出すための公式ツール群で、運用の自動化と Infrastructure as Code 化の土台になります。

• 同じ手順を何度も手作業で繰り返したくない → CLI コマンドをスクリプト化して再実行する
• リソース操作をアプリやパイプラインに組み込みたい → 言語別 SDK から API を呼ぶ
• 開発・本番など複数テナンシ／リージョンを切り替えたい → 構成プロファイルで使い分ける
• 認証情報を安全に扱いたい → API 署名鍵やインスタンスプリンシパルで認証する
• コンソールにない細かなパラメータや一括処理を行いたい → CLI のオプションやページネーションで制御する

CLI と SDK はどちらも同じ OCI REST API をリクエスト署名して呼び出す薄い層であり、AWS でいえば AWS CLI と AWS SDK の関係に対応します。

主要概念と用語

• OCI CLI: Python ベースの公式コマンドラインツール。oci <サービス> <リソース> <アクション> という体系でほぼ全サービスを操作する
• OCI SDK: 各言語(Python / Java / Go / TypeScript / .NET / Ruby など)向けの公式ライブラリ。アプリから OCI API を型付きで呼べる
• 構成ファイル (config): 既定で ~/.oci/config に置く設定。テナンシ OCID、ユーザー OCID、リージョン、API 鍵のパス、鍵のフィンガープリントなどを保持する
• プロファイル (profile): 構成ファイル内の名前付き設定ブロック。DEFAULT のほか複数定義し、--profile で切り替える
• API 署名鍵 (API Signing Key): ユーザーに紐づく RSA 鍵ペア。秘密鍵で各リクエストに署名し、公開鍵を OCI 側に登録して本人性を証明する
• インスタンスプリンシパル (Instance Principal): コンピュート上のワークロードが、鍵を埋め込まずに動的グループ経由で認証する仕組み
• リソースプリンシパル (Resource Principal): Functions などのリソース自身がプリンシパルとして認証する仕組み
• リクエスト署名 (Request Signing): 各 API 呼び出しを秘密鍵で署名する OCI 標準の認証方式。CLI / SDK が内部で行う
• ページネーション (Pagination): 一覧 API が返す opc-next-page トークンで続きを取得する仕組み。CLI の --all でまとめて取得できる

仕様・制限・クォータ

• CLI は Python ランタイム上で動作し、Oracle Linux ではプリインストール環境(Cloud Shell)からすぐ利用できる。ローカルにはインストーラやパッケージで導入する
• 既定の構成ファイルは ~/.oci/config、API 秘密鍵も既定で ~/.oci 配下に置く。場所は OCI_CLI_CONFIG_FILE などの環境変数や --config-file で変更できる
• ほぼ全 OCI サービスの API を CLI / SDK から呼べる。新サービスの API も順次追加される
• 一覧系の API はページ単位で結果を返すため、大量取得時はページネーションを扱う(CLI は --all や --limit を用意)
• API 呼び出しにはサービス側のレート制限があり、超過時は HTTP 429 が返る。SDK は指数バックオフでのリトライを構成できる
• CLI / SDK ツール自体に追加料金はない。課金は呼び出した先のサービス(作成したリソース)に対して発生する
• 出力形式は JSON が既定で、--output table などの整形や --query(JMESPath)による抽出に対応する

内部の仕組み

OCI CLI と SDK は、いずれも OCI の REST API を呼び出すクライアントです。中心となるのがリクエスト署名で、各 HTTP リクエストに対し、ユーザーの API 秘密鍵で署名を作成してヘッダに付与します。OCI 側は登録済みの公開鍵で署名を検証し、呼び出し元の本人性と改ざんの有無を確認します。

認証情報の供給方法は複数あります。

• API 鍵認証: 構成ファイル(~/.oci/config)のプロファイルに、テナンシ／ユーザー OCID・リージョン・秘密鍵パス・フィンガープリントを記述する。ローカル開発や CI で広く使われる
• インスタンスプリンシパル: コンピュートインスタンス上で動かす場合、鍵を置かずに動的グループ + ポリシーでインスタンス自身に権限を与える。CLI なら --auth instance_principal、SDK なら専用のプロバイダを使う
• リソースプリンシパル: Functions など、リソース自身に権限を付与して認証する
• セキュリティトークン認証: ブラウザログインで一時トークンを取得する方式(oci session authenticate)。MFA を伴う対話的利用に向く

呼び出し対象のリージョンはプロファイルや --region で指定し、CLI / SDK はそのリージョンのエンドポイントに対して署名付きリクエストを送ります。すべての操作は OCI Audit に記録され、誰がいつどの API を呼んだかを追跡できます。

設計パターン / ベストプラクティス

• ワークロードからの呼び出しはインスタンス／リソースプリンシパルを使い、サーバーに秘密鍵を置かない
• プロファイルで環境を分離し、開発・本番のテナンシやリージョンを取り違えないようにする
• 自動化スクリプトは冪等に作り、作成前に存在確認するなど再実行しても壊れないようにする
• 一覧取得は**ページネーション(--all など)**を前提にし、件数増加でも取りこぼさないようにする
• 出力は --query(JMESPath)と --output table で必要項目だけ抽出し、後続処理を簡潔にする
• 大量リソースの作成・削除は並列度とレート制限を意識し、429 時はバックオフでリトライする
• 認可は最小権限の IAM ポリシーで与え、CLI / SDK の利用ユーザーやグループの権限を絞る

運用・監視

• CLI / SDK からの API 操作はすべて OCI Audit に記録され、呼び出し元・時刻・対象リソースを追跡できる
• 認証に失敗する → 構成ファイルのテナンシ／ユーザー OCID・フィンガープリント・秘密鍵パス、OCI 側に公開鍵が登録されているかを確認する
• 認可エラー(NotAuthorizedOrNotFound)→ 対象コンパートメントへの IAM ポリシー、プリンシパル(ユーザー／動的グループ)の権限、リージョンの一致を確認する
• レート超過(HTTP 429)→ 呼び出し間隔を空け、SDK のリトライ設定で指数バックオフを有効にする
• CLI のバージョンや構成は oci --version と oci setup config 周辺で確認・再設定する
• スクリプトの失敗検知は終了コードと JSON 出力の解析で行い、CI/CD のステップ成否に反映する

コスト

OCI CLI と SDK はツール自体が無償で、ダウンロード・利用に追加料金はかかりません。課金は CLI / SDK 経由で作成・利用したサービス側のリソース(コンピュート、ストレージ、データベースなど)に対して発生します。

• ツールの利用そのものは無料。コストは呼び出した先のリソースに依存する
• 自動化スクリプトの作りっぱなしのリソースがコスト要因になりやすい。作成と削除をセットで管理する
• 一括処理で意図せず大量リソースを作る事故を防ぐため、ドライランや件数確認を挟む

セキュリティ

• 可能な限りインスタンスプリンシパル／リソースプリンシパルを使い、長命な API 秘密鍵の配布・埋め込みを避ける
• API 秘密鍵を使う場合はファイル権限を厳格化(本人のみ読み取り)し、リポジトリにコミットしない
• 鍵は定期的にローテーションし、不要になったユーザーの公開鍵は OCI 側から削除する
• 認可は最小権限の IAM ポリシーで与え、CLI / SDK 利用者の操作範囲をコンパートメント単位で絞る
• 対話的な利用には**セキュリティトークン認証(MFA 連携)**を使い、トークンの有効期限で露出を抑える
• すべての操作は Audit に残るため、不審な API 呼び出しの監査・検知に活用する

関連サービス・比較

OCI を操作する手段として、宣言的にインフラを管理する OCI Resource Manager(Terraform ベース) とよく比較されます。手続き的に都度コマンドで操作する CLI / SDK と、望ましい状態を宣言してその差分を適用する IaC の違いを押さえると使い分けやすくなります。

ハンズオン / CLI例

# 1) 構成を対話的にセットアップ(API 鍵生成・config 作成)
oci setup config

# 2) 設定が正しいか疎通確認(リージョン一覧の取得)
oci iam region list --output table

# 3) コンパートメント内のコンピュートインスタンスを一覧(整形・抽出)
oci compute instance list \
  --compartment-id "ocid1.compartment.oc1..xxxx" \
  --query "data[].{Name:\"display-name\", State:\"lifecycle-state\"}" \
  --output table

# 4) 別プロファイル(本番)とリージョンを指定して実行
oci os ns get --profile PROD --region ap-tokyo-1

# 5) コンピュート上のワークロードからインスタンスプリンシパルで認証
oci os bucket list \
  --compartment-id "ocid1.compartment.oc1..xxxx" \
  --auth instance_principal

# 6) ページネーションをまとめて取得(大量一覧)
oci iam user list \
  --compartment-id "ocid1.tenancy.oc1..xxxx" \
  --all --output table

# 7) MFA を伴う対話的なセキュリティトークン認証
oci session authenticate --region ap-tokyo-1