今回は Google Cloud を使ってアプリケーションを開発する際の認証情報に関する記事です。
ローカルで gcloud auth application-default login コマンドを実行した際、以下のような警告メッセージが表示されることがあります。
WARNING: Cannot add the project "dazzling-pillar-4369" to ADC as the quota project because the account in ADC does not have the "serviceusage.services.use" permission on this project. You might receive a "quota_exceeded" or "API not enabled" error. Run $ gcloud auth application-default set-quota-project to add a quota project.
この記事では、この警告の意味と原因、対処方法、プラクティスなどを解説します。
Application Default Credentials (ADC) とは？
Application Default Credentials (ADC) とは、アプリケーションが Google Cloud のサービスや API にアクセスするためのデフォルト認証情報を取得する仕組みです (How Application Default Credentials works)。
ADC を利用すると、アプリケーションは環境に応じて自動的に認証情報を検出し、必要な資格情報を取得できます。
- 環境変数
GOOGLE_APPLICATION_CREDENTIALSが設定されていれば、そのパスにあるサービスアカウントキーや構成ファイルを使用 - 次に、
gcloud auth application-default loginコマンドで保存されたユーザ認証情報（ローカルに保存される ADC ファイル）を使用 - それも無ければ、現在の環境（例: GCE や GKE）に紐づいたデフォルトのサービスアカウント認証情報をメタデータサーバから取得して使用
ADC により、開発者は明示的に認証情報をコードに記述することなく Google Cloud のリソースにアクセスできます。
ローカル環境で gcloud auth application-default login を実行すると、ユーザの資格情報を使用して ADC 用の認証情報ファイル（通常 ~/.config/gcloud/application_default_credentials.json）が作成され、以後クライアントライブラリ等から利用されるようになります。
ちなみに、上記 2. で説明のとおり、gcloud auth application-default login コマンドはユーザアカウントの権限を使用してアプリケーションを実行します。
対象のアプリケーション用に用意されたサービスアカウントがあり、サービスアカウントの権限を使用してアプリケーションを実行したい場合は gcloud auth application-default login --impersonate-service-account コマンドを利用します。
クォータプロジェクトについての警告メッセージの概要
記事冒頭の警告メッセージは、ADC を使用する際の Quota Project（クォータプロジェクト） に関する問題を示しています。
"dazzling-pillar-4369"というプロジェクト ID を、ADC の Quota Project（課金・クォータ用のプロジェクト）として設定しようとしたが、現在の ADC に紐づくアカウント（認証情報）にはそのプロジェクトに対する"serviceusage.services.use"権限が無いため設定できない- その結果、quota_exceeded（クォータ超過）や API not enabled（API が有効でない）といったエラーが発生する可能性がある
- 対処策として、
gcloud auth application-default set-quota-projectコマンドでクォータプロジェクトを設定するよう推奨している
まず、「クォータプロジェクト (quota project)」とは何かを説明します。
Google Cloud の API には リソースベースのAPI と クライアントベースのAPI の2種類があります (Troubleshoot your ADC setup)。
前者のリソースベースの API は、対象のリソースを包含しているプロジェクトの設定に従ってクォータ制御や課金が行われます。
後者のクライアントベース API では、（クライアント自体は特定のプロジェクトに包含されるものではないため）どのプロジェクトのクォータ・課金枠を消費するかを指定する必要があります。
クォータプロジェクトとは、この課金・クォータ計測のために使用されるプロジェクトのことです（請求先プロジェクトとも呼ばれます）。
通常、Google Cloud のクライアントライブラリでユーザ認証情報（人間のユーザアカウントの資格情報）を使う場合、どのプロジェクトをクォータ課金対象とするかを明示的に指定しなければなりません。
gcloud auth application-default login を実行した際、Google Cloud SDK は内部的に現在のプロジェクトをクォータプロジェクトとして ADC に関連付けようとします。
しかし、このとき利用している認証情報（例えば Viewer 権限しか持たないユーザアカウントなど）に、そのプロジェクトに対する必要な権限（serviceusage.services.use）が無い場合、対象のプロジェクトをクォータプロジェクトとして利用することはできないため、今回のような警告が表示されます (ADC 設定のトラブルシューティング)。
serviceusage.services.use とは
serviceusage.services.use は任意のプロジェクトのサービスを利用（課金を発生）するための権限です。
この権限は Service Usage ユーザー ロール（roles/serviceusage.serviceUsageConsumer）に含まれています。
例えば、プロジェクト閲覧のみを許可する Viewer ロールには含まれていないため、閲覧権限のみが付与されているユーザがそのプロジェクトをクォータプロジェクトにしようとすると権限不足になります。
余談ですが、今回のようにクォータプロジェクトが設定されていない場合に生じうるエラーとして、警告メッセージでは以下の 2 種類が挙げられていました。
quota_exceededエラーAPI not enabledエラー
なぜプロジェクトが設定されていないにもかかわらず quota_exceeded が表示されるのかと思い少し調べてみたところ、クライアントベースの API 呼び出しで適切なクォータプロジェクトが指定されない場合、デフォルトで使用される Google 提供の共有プロジェクトのクォータを消費するようです（Stackoverflow, Google Cloud の Medium）。
同様に、クォータプロジェクトが正しく設定されず、呼び出しが Google 所有の共有プロジェクトにフォールバックされた場合、そのプロジェクトで目的の API が有効になっていないと、API not enabled のエラーが発生するようです。
公式ドキュメントでも それらしい記述 があり、恐らくこのプロジェクトがフォールバック先の共有プロジェクトと思われます。
ADC にクォータプロジェクトを設定する
まずはクォータプロジェクトとして利用するプロジェクトに対し、ADC に使用しているアカウントに serviceusage.services.use 権限を持たせます。
具体的には、そのアカウントに対して Service Usage Consumer ロールを付与します。
CLI でのロール付与例:
# プロジェクト <PROJECT_ID> に、自分のユーザーアカウントに Service Usage Consumer ロールを付与
gcloud projects add-iam-policy-binding <PROJECT_ID> \
--member="user:<自分のメールアドレス>" \
--role="roles/serviceusage.serviceUsageConsumer"
これにより、該当プロジェクトに対するサービスの使用権限が付与され、クォータプロジェクトとして利用可能になります。
権限の準備ができたら、ADC に対してクォータプロジェクトを設定します。
gcloud auth application-default set-quota-project <PROJECT_ID>
<PROJECT_ID> には課金対象とするプロジェクトのプロジェクト ID を指定します。
このコマンドにより、ローカルに保存されている ADC ファイルに quota_project_id の項目が追加または更新されます。
結果として、今後 ADC を用いた API 呼び出しではこの設定したプロジェクトが課金・クォータ計測に使われるようになります。
プロジェクトの設定に関するプラクティス
最後に、この種のエラーを今後防ぐためのいくつかのプラクティスを紹介します。
gcloud コマンドのデフォルト構成にクォータプロジェクトを設定する
毎回必要なときにローカルで gcloud auth application-default set-quota-project <PROJECT_ID> を実行する、というのも一つの手ですが、毎回手動で設定するのが煩わしい場合、gcloud CLI の設定にクォータプロジェクトを登録しておくこともできます。
gcloud config set billing/quota_project <PROJECT_ID>
こうすることで、今後 ADC を新たに取得する際にもこのプロジェクトが自動的に使用されます。
サービスアカウントの利用を検討する
例えば CI/CD パイプラインなど自動化された仕組みの中で長期的に認証を行う必要がある場合は、ユーザの ADC ではなくサービスアカウントを使用するほうが適切です。
サービスアカウントを使用すれば、必要最小限の IAM ロールだけを与えた専用のアカウントで認証でき、かつクォータプロジェクトも明確になります。
警告やエラーを無視しない
最後は技術的な対策というより心構えですが、今回のような警告が出た場合は安易に無視せず、意味を理解しようとすることが大事かなと思います。
放置すると「なんとなく動いているが裏で Google の共有プロジェクトを使ってしまっている」「ある日突然 API 呼び出しが失敗し始めた」などのトラブルに繋がりかねません。
警告は問題発生のサインなので、公式ドキュメントやエラーメッセージを頼りに根本解決に取り組むことで理解が深まる、本番障害を未然に防げる、チームの技術力が高まるといった側面もあるのではないでしょうか。
おわりに
ADC 使用時のクォータプロジェクトの指定に関するエラーメッセージを起点に、クォータプロジェクトの意味や設定方法、安定的に開発を継続していくためのいくつかのプラクティスをご紹介しました。
クォータプロジェクトを指定しないままだと、Google 所有の共有プロジェクトが API コールの課金先として使われる可能性があり、API の有効化に関するエラーや思わぬクォータ制限に引っかかる可能性がありますので、適切なクォータプロジェクトを設定しておきましょう。
そうすることで、自分のプロジェクトで自分の利用分の API 呼び出しを正しく課金・計測できるようになります。
