Cloud SDK (gcloud CLI)

解決する課題

GCP のリソースをコンソールの手作業ではなく、コマンドやスクリプトとして再現可能な形で操作・自動化できます。

• コンソールでのクリック作業をコマンド化して自動化・再利用したい
• 開発・ステージング・本番など複数のプロジェクトや環境を素早く切り替えたい
• リソースの作成・更新・削除を CI/CD パイプラインや運用スクリプトに組み込みたい
• 手元の端末から GKE や Cloud SQL などに安全に認証して接続したい
• 操作手順をドキュメント化・レビュー可能なテキストとして残したい

主要概念と用語

• gcloud: GCP のリソースを操作する中心的な CLI。コマンドは「gcloud グループ サブコマンド」の階層構造を持つ
• コンポーネント（component）: Cloud SDK に追加インストールできる機能単位。kubectl・gcloud アルファ／ベータコマンドなどを必要に応じて足せる
• gsutil / gcloud storage: Cloud Storage を操作するコマンド。新しい gcloud storage への移行が進んでいる
• bq: BigQuery を操作する専用コマンド。クエリ実行やテーブル管理に使う
• 構成（configuration）: アカウント・プロジェクト・リージョン／ゾーンなどの設定一式に名前を付けて保持し、切り替えられる仕組み
• プロパティ（property）: 構成内の個々の設定値（例: core/project、compute/region）
• 認証情報（credentials）: ユーザーアカウントやサービスアカウントのログイン状態。アクティブなアカウントの権限でコマンドが実行される
• ADC（Application Default Credentials）: アプリやライブラリが自動で参照する既定の認証情報

仕様・制限・クォータ

• コマンドは冪等になるよう設計されているものが多く、同じ作成系コマンドを繰り返しても安全に扱える場合が多い（ただし挙動はコマンド依存なので確認は必要）
• アルファ／ベータコマンドは安定版と分離されており、gcloud alpha / gcloud beta のグループとして提供される
• 実体は GCP の各サービス API を呼び出すラッパーであり、操作上の上限やクォータは各 API 側のものに従う
• 出力形式は --format で JSON・YAML・表・値などに切り替えられ、--filter で結果を絞り込める
• バージョンは継続的に更新され、gcloud components update で更新する（古いバージョンには非推奨警告が出ることがある）
• 認証情報や構成はローカルの設定ディレクトリに保存され、端末ごとに管理される

内部の仕組み

Cloud SDK は、ローカル環境にインストールされた CLI 群が、認証情報と構成（アクティブなアカウント・プロジェクト・リージョンなど）を読み取りつつ、背後で各 GCP サービスの REST/gRPC API を呼び出す仕組みです。コマンドはユーザーが指定した操作を対応する API リクエストへ変換し、結果を整形して返します。

• どのアカウント・どのプロジェクトで操作するかはアクティブな構成で決まる。gcloud config configurations で複数の構成を切り替えられる
• 認証はユーザーアカウントの OAuth ログイン、またはサービスアカウントの認証情報で行う。発行されたトークンはローカルに保持され、コマンド実行時に使われる
• アプリ／ライブラリ向けには ADC が用意され、明示的にキーを渡さなくても既定の認証情報を解決できる
• kubectl など一部のツールはコンポーネントとして追加され、Cloud SDK 経由でバージョン管理される

AWS でいえば、各サービスを単一のコマンド体系から操作する点で AWS CLI に相当します。gcloud がアカウント・プロジェクト・リージョンを構成として束ねる発想は、AWS CLI の名前付きプロファイルやリージョン設定に近い位置づけです。

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

• 環境ごとに名前付き構成（configuration）を分け、誤って本番に対して操作しないようにする
• スクリプトや CI/CD ではサービスアカウントで認証し、対話的なユーザーログインに依存しない
• 出力を後続処理で使うときは --format=json などで機械可読な形式に固定し、表形式の見た目に依存しない
• 破壊的なコマンドは --quiet の使いどころを見極め、意図しない自動承認を避ける（CI では明示、対話では確認を残す）
• 長いコマンドは置換変数やシェル変数で環境差分を吸収し、同じスクリプトを複数環境で再利用する
• アルファ／ベータコマンドは仕様変更の可能性を理解したうえで使い、本番運用は安定版を基本にする

運用・監視

• gcloud から実行したリソース操作は、各サービス側の Cloud Audit Logs に記録され、誰がいつ何を操作したかを追える
• 不具合調査時は --verbosity=debug や --log-http で詳細なログや HTTP リクエストを出力できる
• バージョン差異による挙動の違いを避けるため、CI 環境ではSDK のバージョンを固定して再現性を担保する
• よくあるつまずきはアクティブな構成の取り違えと認証情報の期限切れ／権限不足で、gcloud auth list と gcloud config list での確認が起点になる

コスト

Cloud SDK 自体は無償で利用できます。料金が発生するのは、gcloud などを通じて作成・利用したGCP リソース側であり、CLI を使うこと自体に追加課金はありません。コスト面で意識すべきは、スクリプトで意図せず高額なリソースを大量作成しないようにすることです。

セキュリティ

• 操作はアクティブなアカウントの IAM 権限で実行される。日常利用するアカウントには最小権限だけを付与する
• サービスアカウントを使う場合は、可能ならキーファイルを発行せず、ワークロード ID 連携や環境付与の認証情報を優先する
• キーファイルを使う場合は漏洩対策（リポジトリへ含めない、ローテーション）を徹底する
• 共有端末では作業後に gcloud auth revoke で認証情報を消去し、ログイン状態を残さない
• シークレットをコマンド履歴やスクリプトに直書きせず、Secret Manager から取得する方式を使う

関連サービス・比較

Cloud SDK（gcloud CLI）はローカル環境にインストールして使う手元のツールですが、ブラウザ上ですぐ使える Cloud Shell にもプリインストールされています。両者は同じ gcloud を使えるため、用途に応じて使い分けます。

ハンズオン / CLI例

# 認証してアクティブなアカウントを確認
gcloud auth login
gcloud auth list

# 既定のプロジェクトとリージョンを設定
gcloud config set project PROJECT_ID
gcloud config set compute/region asia-northeast1

# 環境ごとの構成を作って切り替える
gcloud config configurations create staging
gcloud config configurations activate staging
gcloud config list

# リソース一覧を JSON 形式で取得し、フィルタで絞り込む
gcloud compute instances list \
  --format=json \
  --filter="status=RUNNING"

# CI 向け: サービスアカウントで認証し、対話確認を省略
gcloud auth activate-service-account --key-file="$KEY_FILE"
gcloud compute instances delete my-vm --zone=asia-northeast1-a --quiet