はじめに

Google Cloud を利用する上で gcloud CLI は欠かせないツールです。複数のプロジェクトやアカウントを扱う場合、Configuration を活用することで切り替えを効率化できます。

このブログでは gcloud CLI のプロジェクトセットアップと認証関連の Tips をまとめたいと思います。

Configuration の管理

gcloud CLI には Configuration という仕組みがあり、プロジェクト ID やアカウント等の設定をプリセットとして保存できます。 Configuration は ~/.config/gcloud/configurations/ 配下にファイルとして保存されます。

Configuration の一覧確認

現在登録されている Configuration の一覧は以下のコマンドで確認できます。

IS_ACTIVE が True になっている Configuration が、現在アクティブなプロファイルです。

Configuration の追加

新しい Configuration を追加するには gcloud init を実行します。

対話形式で、以下の項目を順に設定します。

既存 Configuration の再初期化 or 新規作成の選択
Configuration 名の入力
認証アカウントの選択
プロジェクトの選択
デフォルトリージョン・ゾーンの設定（任意）

Configuration 名は小文字・数字・ハイフンのみ使用可能です。自分の場合は基本的にプロジェクト名に揃えていますが、分かりずらい場合は、環境やステージを含めた命名（例：my-project-dev、my-project-prd）にしておくと、切り替え時に判別しやすくなります。

Configuration の切り替え

このコマンドを実行すると、以降の gcloud コマンドは指定した Configuration の設定（アカウント、プロジェクト等）で動作します。

環境変数による一時的な切り替え

CLOUDSDK_ACTIVE_CONFIG_NAME 環境変数を使うと、activate せずに一時的に別の Configuration を使用できます。

この方法はスクリプトやワンライナーで別プロジェクトのリソースを参照したいときに便利です。同様に、CLOUDSDK_CORE_PROJECT を指定すれば、Configuration を切り替えずにプロジェクトだけを一時的に上書きできます。

Configuration の削除

不要になった Configuration は以下で削除できます。

認証

gcloud CLI の認証には大きく分けて ユーザ認証 と サービスアカウント認証 の 2 種類があります。

ユーザ認証

gcloud CLI でユーザ認証を行うには gcloud auth login を使用します。

ブラウザが立ち上がり、Google アカウントでのログインが求められます。認証が完了すると、以降の gcloud コマンドはそのアカウントの権限で実行されます。

リモートサーバ等、ブラウザが利用できない環境では --no-browser フラグを使用します。

表示される URL をローカルマシンのブラウザで開いて認証を完了させた後、発行されたコードをターミナルに貼り付けます。

サービスアカウント認証

CI/CD パイプラインやバッチ処理等、対話操作ができない環境ではサービスアカウントのキーファイルで認証することができます。

ただし、サービスアカウントキーはセキュリティリスクがあるため、可能であれば Workload Identity Federation 等のキーレス認証を利用すると良いでしょう。

認証アカウントの確認と切り替え

現在認証済みのアカウント一覧を確認するには以下を実行します。

アクティブなアカウントを切り替えたい場合は gcloud config set account を使用します。

認証の取り消し

特定のアカウントの認証を取り消すには gcloud auth revoke を使用します。

全アカウントの認証を一括で取り消す場合は --all フラグを付けます。

Application Default Credentials

アプリケーションからローカルで Google Cloud API を呼び出す場合は ADC（Application Default Credentials）を設定します。

ADC は gcloud auth login とは別の認証情報であり、gcloud CLI ではなく SDK やクライアントライブラリが使用するものです。ローカル開発で Cloud Storage や BigQuery 等の API を呼び出す際（例：Terraform の実行）に必要になります。

ADC の認証情報は ~/.config/gcloud/application_default_credentials.json に保存されます。不要になった場合は以下で削除できます。

サービスアカウントの権限借用

Google Cloud には、自分のアカウントからサービスアカウントの権限を借用（Impersonate）して操作する方法があります。キーファイルをダウンロードせずに、サービスアカウントの権限で gcloud コマンドを実行できます。

この方法を利用するには、自分のアカウントに対象サービスアカウントの roles/iam.serviceAccountTokenCreator ロールが付与されている必要があります。

プロパティの設定

gcloud config set を使うと、Configuration に個別のプロパティを設定できます。

よく使うプロパティ

リージョンやゾーンを設定しておくと、gcloud compute 系のコマンドで毎回 --region や --zone を指定する必要がなくなります。

プロパティの解除

設定済みのプロパティを解除するには gcloud config unset を使用します。

コンポーネントの管理

gcloud CLI は機能毎にコンポーネントとして分離されています。必要なコンポーネントを追加インストールすることで、追加の機能を利用できます。

よく使うコンポーネントとしては以下のようなものがあります。

コンポーネント	用途
`kubectl`	Kubernetes クラスタの操作
`gke-gcloud-auth-plugin`	GKE 認証プラグイン
`cloud-sql-proxy`	Cloud SQL への接続
`beta` / `alpha`	ベータ / アルファ版のコマンドの利用

よく使う確認コマンド

現在の設定内容やプロジェクト情報を確認するコマンドをまとめておきます。

出力フォーマットの指定

gcloud コマンドの出力はデフォルトでは表形式ですが、これは --format フラグで変更できます。

--filter フラグと組み合わせると、条件に一致するリソースだけを絞り込めます。

GKE クラスタへの接続

GKE クラスタに kubectl でアクセスするには、事前に認証プラグインのインストールと Credential の取得が必要です。

これにより、kubeconfig にクラスタの接続情報が追加され、kubectl コマンドで対象クラスタを操作できるようになります。

複数クラスタの Credential を取得している場合、kubectl config get-contexts で接続先の一覧を確認し、kubectl config use-context で切り替えることができます。

Shell Script による効率化

ここまで紹介したコマンドは日常的に繰り返し実行するものが多いため、Shell Script やエイリアスで自動化しておくと便利です。

エイリアスの活用

.zshrc や .bashrc に以下のようなエイリアスを定義しておくと、入力の手間を削減できます。

gcp：単純なエイリアス
gcpp：後述するインタラクティブな Configuration 切り替え関数を呼び出す

peco / fzf を使ったインタラクティブな Configuration 切り替え

複数の Configuration を登録している場合、gcloud config configurations activate で名前を毎回入力するのは面倒です。 peco や fzf 等のインタラクティブフィルタを組み合わせると、一覧から選択するだけで切り替えられます。

以下は peco を使った例です。

functions.zsh

このような Shell Function は ~/.zshrc に直接書くか、dotfiles 等で管理している Shell 設定ファイル（例：functions.zsh）に定義して source で読み込みます。

gcp_profile_update は以下の流れで動作します。

gcloud config configurations list で登録済みの Configuration 名を一覧取得する
peco の絞り込み UI で対象の Configuration を選択する
選択した Configuration をアクティベートする
アクティブな Configuration にプロジェクトが設定されていれば、ADC の Quota Project も併せて更新する

ADC の Quota Project とは、Application Default Credentials を使用した API 呼び出しで課金先となるプロジェクトのことです。

Configuration を切り替えた際に ADC の Quota Project が古いプロジェクトのままだと、意図しないプロジェクトに課金されたり、権限不足のエラーが発生する可能性があります。この関数では Configuration の切り替えと連動して自動更新するため、切り替え忘れを防止できます。

fzf を使う場合は peco の部分を fzf に置き換えるだけで動作します。

コンポーネントの一括セットアップスクリプト

新しいマシンの初期構築時に必要なコンポーネントをまとめてインストールするスクリプトを用意しておくと、環境構築を CaC（Configuration as Code）できます。

--quiet フラグを付けることで確認プロンプトをスキップし、非対話的に実行できます。

セットアップ手順のまとめ

新しいマシンや環境で gcloud CLI をセットアップする際の一連の流れをまとめておきます。

Configuration をあらかじめ用意しておけば、gcloud config configurations activate の一発で環境を切り替えられます。複数プロジェクトを扱う場合は、プロジェクト毎に Configuration を作成しておくことを推奨します。

まとめ

今回のブログでは、gcloud CLI の Configuration 管理、認証、プロパティ設定、コンポーネント管理、出力フォーマット、GKE クラスタへの接続、Shell Script による効率化についてまとめました。

複数プロジェクトを扱う場合は Configuration を活用し、peco や fzf と組み合わせた Shell Function で切り替えを自動化しておくと、日常の運用が格段に楽になると思います！

gcloud CLI の設定・認証 Tips