Google Cloud CLI（gcloud CLI）

解決する課題

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

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

主要概念と用語

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

仕様・制限・クォータ

• 作成・更新・再試行時の挙動はサービス API とコマンドごとに異なる。自動再試行する前に --help を確認し、明示的なリソース名と実行後の状態確認を組み合わせる
• アルファ／ベータコマンドは安定版と分離されており、gcloud alpha / gcloud beta のグループとして提供される
• 実体は GCP の各サービス API を呼び出すラッパーであり、操作上の上限やクォータは各 API 側のものに従う
• 出力形式は --format で JSON・YAML・表・値などに切り替えられ、--filter で結果を絞り込める
• バージョンは継続的に更新される。コンポーネント管理で導入した場合は gcloud components update、apt・yum などで導入した場合は同じ OS パッケージマネージャーで更新する
• 認証情報や構成はローカルの設定ディレクトリに保存され、端末ごとに管理される

内部の仕組み

横にスクロール

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

• どのアカウント・どのプロジェクトで操作するかはアクティブな構成で決まる。gcloud config configurations で複数の構成を切り替えられる
• gcloud auth login が使う CLI の資格情報と、アプリ／ライブラリ向けの ADC は別管理。ADC が必要なローカル開発では gcloud auth application-default login を明示的に実行する
• kubectl など一部のツールは、対応するインストール方式ではコンポーネントとして追加できる。OS パッケージで導入した場合は、そのパッケージ側で更新する

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 での確認が起点になる

コスト

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

セキュリティ

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

関連サービス・比較

Google Cloud 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"

# 自動処理では長命鍵を置かず、短期資格情報でサービスアカウントを借用する
gcloud compute instances list \
  --project=PROJECT_ID \
  --impersonate-service-account=automation@PROJECT_ID.iam.gserviceaccount.com \
  --format='value(name,zone,status)'