gcloud CLI は Google Cloud のリソースを管理するための CLI ツールだが、これを使ってリソースにアクセスするためには当然、アカウントの認証を行わなければならない。そして gcloud CLI では様々な操作を行えるが、その挙動を自分の意図した通りに制御するためには「プロパティ」や「構成」といった概念を理解する必要がある。
この記事では、 gcloud CLI を使いこなすために理解すべき、認証、プロパティ、構成、の初歩について述べていく。
この記事の内容は、以下の環境で動作確認を行った。
- Google Cloud SDK 503.0.0
- bq 2.1.10
- Python 3.11.6
認証
$ gcloud auth listで、既に認証が行われているアカウントを確認できる。
認証が行われているアカウントが存在しない状態で$ gcloud auth listを実行すると以下の結果になる。
$ gcloud auth list No credentialed accounts.
この状態だと当然、 Google Cloud のリソースにアクセスすることはできない。
例えばプロジェクト一覧を取得する$ gcloud projects listを実行するとエラーになる。
$ gcloud projects list
ERROR: (gcloud.projects.list) You do not currently have an active account selected.
アカウントの認証は$ gcloud auth loginで行う。
このコマンドを実行するとウェブブラウザでページが開くので、その内容に沿って操作を行うと、選択したアカウントでの認証が完了する。
そうするとローカルに認証情報が保存され、その認証情報を使って gcloud CLI が Google Cloud のリソースにアクセスできるようになる。
$ gcloud auth listを実行すると、認証が行われたアカウントが表示される。
$ gcloud auth list Credentialed Accounts ACTIVE ACCOUNT * numb@example.com
このアカウントの認証情報を使って Google Cloud のリソースを管理するのだから、 gcloud CLI が可能な動作は当然、このアカウントに付与されている権限の範囲内のものとなる。
例えば先程の$ gcloud projects listの場合、numb@example.comがアクセスできるプロジェクトのみが表示される。
$ gcloud projects list PROJECT_ID NAME PROJECT_NUMBER project-x-123456 project-x ************ project-y-123456 project-y ************ project-z-123456 project-z ************
先程はユーザーアカウントで認証を行ったが、サービスアカウントで行うこともできる。
project-x-123456のサービスアカウントsa-for-xを用意してサービスアカウントキーを発行したので、それを使って認証を行ってみる。
$ gcloud auth login --cred-file=project-x-sa-key.json
$ gcloud auth list
Credentialed Accounts
ACTIVE ACCOUNT
numb@example.com
* sa-for-x@project-x-123456.iam.gserviceaccount.com
ACTIVEがsa-for-x@project-x-123456.iam.gserviceaccount.comになっている。
この状態ではsa-for-x@project-x-123456.iam.gserviceaccount.comの認証情報を使って gcloud CLI が実行される。
そのため例えば$ gcloud projects listを実行すると、sa-for-x@project-x-123456.iam.gserviceaccount.comがアクセスできるproject-x-123456のみが表示される。
$ gcloud projects list PROJECT_ID NAME PROJECT_NUMBER project-x-123456 project-x ************
使用するアカウントを切り替えるには$ gcloud config set account <ACCOUNT>を実行する。
$ gcloud config set account numb@example.comを実行すると、ACTIVEなアカウントがnumb@example.comに変わる。
$ gcloud config set account numb@example.com
Updated property [core/account].
$ gcloud auth list
Credentialed Accounts
ACTIVE ACCOUNT
* numb@example.com
sa-for-x@project-x-123456.iam.gserviceaccount.com
認証情報を取り消すには$ gcloud auth revoke <ACCOUNT>を実行する。
$ gcloud auth revoke sa-for-x@project-x-123456.iam.gserviceaccount.com $ gcloud auth list Credentialed Accounts ACTIVE ACCOUNT * numb@example.com
プロパティ
先ほど確認したようにnumb@example.comは 3 つのプロジェクトにアクセスできるわけだが、この状態で「任意のプロジェクトに対して実行するコマンド」を実行するとどうなるのだろうか。
例えば$ gcloud storage lsはプロジェクトにある Cloud Storage バケットの一覧を取得するコマンドだが、その「プロジェクト」とは具体的にどのプロジェクトなのか。
各プロジェクトに以下のバケットを作成し試してみる。
- project-x-123456
- bucket-a
- project-y-123456
- bucket-b
- project-z-123456
- bucket-c
$ gcloud storage lsを実行するとproject-x-123456のbucket-aが表示された。
$ gcloud storage ls gs://bucket-a/
これは、projectプロパティがproject-x-123456になっていたためである。
プロパティは、 gcloud CLI の動作を制御する設定のことであり、どのようなプロパティを設定するかで、 gcloud CLI の動作が変わる。
例えばどのプロジェクトを対象に動作するのかは、projectプロパティによって決まる。
$ gcloud config listでプロパティの設定内容を確認できる。
$ gcloud config list [core] account = numb@example.com disable_usage_reporting = True project = project-x-123456 Your active configuration is: [default]
--formatフラグを使って任意のプロパティだけ表示することもできる。
$ gcloud config list --format="value(core.project)"
project-x-123456
認証の説明で出てきた「使用するアカウント」という概念も、プロパティによって決まっている。
具体的にはaccountプロパティによって決まっている。
プロパティの設定は$ gcloud config set <SECTION_NAME>/<PROPERTY_NAME> <PROPERTY_VALUE>で行う。
設定したいプロパティのセクションが何であるかは、先程紹介した$ gcloud config listで確認できる。
以下の例の場合coreがセクションに該当する。該当するプロパティが存在しないのでこの例では表示されていないが、他にもcomputeやmetricsといったセクションが存在する。
$ gcloud config list [core] account = numb@example.com disable_usage_reporting = True project = project-x-123456 Your active configuration is: [default]
projectプロパティを設定したい場合、coreに属しているので、$ gcloud config set core/project <PROJECT_ID>とする。
セクションがcoreの場合は省略可能なので$ gcloud config set project <PROJECT_ID>と書くことも可能。
「アカウントの切り替え」として先ほど紹介した$ gcloud config set account <ACCOUNT>も、何か特別なことをしているわけではなく、accountプロパティを設定しているだけである。
実際にprojectプロパティを変えてみる。
$ gcloud config set core/project project-z-123456 Updated property [core/project]. $ gcloud config list --format="value(core.project)" project-z-123456
この状態でバケットを取得するとbucket-cが表示されるため、project-z-123456に対してコマンドが実行されていることを確認できる。
$ gcloud storage ls gs://bucket-c/
setではなくunsetを使うとプロパティの設定を解除できる。
例えば$ gcloud config unset core/projectを実行するとprojectプロパティの設定が解除される。
$ gcloud config unset core/project
Unset property [core/project].
$ gcloud config list
[core]
account = numb@example.com
disable_usage_reporting = True
Your active configuration is: [default]
ちなみにこの状態で$ gcloud storage lsを実行するとエラーになる。
$ gcloud storage ls
ERROR: (gcloud.storage.ls) The required property [project] is not currently set.
構成
プロパティと密接に関連する概念として構成（configuration）がある。
構成とは、設定しているプロパティのリストに名前を付けたものであり、 gcloud CLI を使う際は必ずいずれか一つの構成を有効にすることになる。
例えば gcloud CLI をインストールした時点では、defaultという構成が作られており、それが有効になっている。
「プロパティの設定内容を確認できる」と紹介した$ gcloud config listは、正確には「現在有効になっている構成のプロパティの設定内容を確認できる」コマンドである。
$ gcloud config listの結果をもう一度見てみると、一番下にYour active configuration is: [default]と表示されており、defaultという構成が有効になっていることが分かる。
$ gcloud config list [core] account = numb@example.com disable_usage_reporting = True Your active configuration is: [default]
つまり上記の表示内容は、「default構成においてaccountプロパティとdisable_usage_reportingプロパティが設定されている」ということを意味している。
そして$ gcloud config setや$ gcloud config unsetも、有効になっている構成に対してプロパティの設定や解除を行うコマンドであり、有効になっていない構成のプロパティに対しては影響を与えない。
構成は$ gcloud config configurations create <NAME>で自由に作れる。
例えば$ gcloud config configurations create testを実行するとtestという構成が使われ、それが有効になる。
$ gcloud config configurations create test Created [test]. Activated [test].
構成の一覧は$ gcloud config configurations listで確認できる。
$ gcloud config configurations list
NAME IS_ACTIVE ACCOUNT PROJECT COMPUTE_DEFAULT_ZONE COMPUTE_DEFAULT_REGION
default False numb@example.com
test True
test構成が有効になっているこの状態で$ gcloud config listすると、testに設定されているプロパティが表示される。
$ gcloud config list
[core]
disable_usage_reporting = True
Your active configuration is: [test]
今はtest構成が有効になっているので、 gcloud CLI はtest構成に設定されているプロパティに基づいて動作する。
例えば$ gcloud projects listを実行するとエラーになる。
$ gcloud projects list
ERROR: (gcloud.projects.list) You do not currently have an active account selected.
これはtest構成ではaccountプロパティが設定されていないからである。
accountプロパティを設定すれば動くようになる。
$ gcloud config set core/account numb@example.com
Updated property [core/account].
$ gcloud projects list
PROJECT_ID NAME PROJECT_NUMBER
project-x-123456 project-x ************
project-y-123456 project-y ************
project-z-123456 project-z ************
$ gcloud config configurations activate <NAME>で使用する構成を切り替えられる。
$ gcloud config configurations list NAME IS_ACTIVE ACCOUNT PROJECT COMPUTE_DEFAULT_ZONE COMPUTE_DEFAULT_REGION default False numb@example.com test True numb@example.com $ gcloud config configurations activate default Activated [default]. $ gcloud config configurations list NAME IS_ACTIVE ACCOUNT PROJECT COMPUTE_DEFAULT_ZONE COMPUTE_DEFAULT_REGION default True numb@example.com test False numb@example.com
構成を削除するには$ gcloud config configurations delete <NAME>を実行する。
但し、有効になっている構成を削除することはできない。
$ gcloud config configurations delete test The following configurations will be deleted: - test Do you want to continue (Y/n)? Y Deleted [test]. $ gcloud config configurations list NAME IS_ACTIVE ACCOUNT PROJECT COMPUTE_DEFAULT_ZONE COMPUTE_DEFAULT_REGION default True numb@example.com
使用する構成をフラグや環境変数で指定する
ここまで、「有効になっている構成のプロパティが使用される」と書いてきたが、その挙動をオーバーライドすることもできる。
具体的には、環境変数によって、使用する構成を指定することができる。
それを確認するために、default以外にxとyという構成を用意した。
$ gcloud config configurations list NAME IS_ACTIVE ACCOUNT PROJECT COMPUTE_DEFAULT_ZONE COMPUTE_DEFAULT_REGION default True numb@example.com x False sa-for-x@project-x-123456.iam.gserviceaccount.com y False sa-for-y@project-y-123456.iam.gserviceaccount.com
sa-for-xはproject-x-123456の、sa-for-yはproject-y-123456のサービスアカウント。
default構成が有効になっているので、この状態で$ gcloud projects listすると、以下の結果になる。
これは今まで見てきた通りである。
$ gcloud projects list PROJECT_ID NAME PROJECT_NUMBER project-x-123456 project-x ************ project-y-123456 project-y ************ project-z-123456 project-z ************
次に、環境変数CLOUDSDK_ACTIVE_CONFIG_NAMEにxを設定する。そうするとx構成が使われるようになる。
$ export CLOUDSDK_ACTIVE_CONFIG_NAME=x
x構成のaccountプロパティに設定しているsa-for-x@project-x-123456.iam.gserviceaccount.comはproject-x-123456プロジェクトのみにアクセスできるので、以下の結果になる。
$ gcloud projects list PROJECT_ID NAME PROJECT_NUMBER project-x-123456 project-x ************
さらに、gcloudコマンドを実行する際に--configurationフラグを付与することで、使用する構成を指定することもできる。
y構成のaccountプロパティに設定しているsa-for-y@project-y-123456.iam.gserviceaccount.comはproject-y-123456プロジェクトのみにアクセスできるので、以下の結果になる。
$ gcloud projects list --configuration=y PROJECT_ID NAME PROJECT_NUMBER project-y-123456 project-y ************
ここまでの結果から、使用する構成は以下のように決まることが分かる。
--configurationフラグで構成が指定された場合はそれが使われる--configurationフラグが付与されておらずCLOUDSDK_ACTIVE_CONFIG_NAMEが設定されている場合はCLOUDSDK_ACTIVE_CONFIG_NAMEで設定されている構成が使われる--configurationフラグが付与されておらずCLOUDSDK_ACTIVE_CONFIG_NAMEも設定されていない場合は「有効」になっている構成が使われる
プロパティの優先順位
構成と同様にプロパティも、フラグや環境変数で指定することができる。
優先順位も、構成と同様に以下の順序になる。
gcloudコマンド実行時に付与するフラグ- 環境変数
- 使用される構成の設定内容
- どの構成が使用されるのかは上述した通り
フラグや環境変数はプロパティ毎に異なるので、少し説明する。
フラグは、プロパティ名がそのままフラグの名前になる。
例えばprojectプロパティの場合は--projectフラグで指定する。
$ gcloud storage ls --project=project-y-123456
環境変数はCLOUDSDK_SECTION_NAME_PROPERTY_NAMEというパターンになっている。
例えばprojectプロパティはcoreセクションなのでCLOUDSDK_CORE_PROJECTになる。
$ export CLOUDSDK_CORE_PROJECT=project-z-123456
bq コマンド
BigQuery を操作するbqコマンドにおいても、ここまで説明してきた構成やプロパティが使われる。
例えば、フラグをつけずにコマンドを実行する場合、環境変数CLOUDSDK_CORE_PROJECTに設定されたプロジェクトに対して実行されるし、それが設定されていない場合は有効になっている構成のprojectプロパティが使われる。
但し使えるフラグはgcloudとは異なるので注意が必要。
例えば--accountフラグは存在しないし、対象のプロジェクトは--projectではなく--project_idで指定する。
