GCP

この記事にはアフィリエイト広告が含まれています。 冒頭まとめ Google Cloudのエラーを検索して1件ずつ直しているのに、翌日は別のサービスで同じような壁に当たる。この繰り返しから抜けるには、覚える順序を変える必要があります。 Google Cloudのエラーの多くは、4つの境界のどこかで起きています。誰として呼んでいるかという境界、そのAPIがプロジェクトで有効になっているかという境界、何を許されているかという境界、そしてネットワークの到達性の境界です。エラー文はこの境界のどれで止まったかを示していますが、境界の存在を知らないと文言が読めません。 他のクラウドと比べたときの最大の違いは、2つ目です。Google Cloudでは、権限があってもAPIが有効でなければ呼べません。公式ドキュメントは、ほとんどのGoogle APIを使う前にGoogle Cloudプロジェクトで有効化する必要があると明記しています（Service Usage overview）。この段階を知らないと、権限の設定を延々と見直すことになります。 学ぶ順序は、認証情報とプロジェクト、APIの有効化、IAMの評価順序、サービスアカウント、ネットワークの到達性、トラブルシューティングの6段階です。各段階には「次へ進む目安」を置きました。飛ばした段階は、後の段階のエラーとして別の顔で現れます。 個別に直すだけでは理解しにくい理由 検索で見つかる対処は、多くの場合その環境で有効だった手順です。なぜ有効だったかは書かれていないことがあります。 たとえば、アクセスが拒否されたときに編集者や所有者の役割を付けたら通った、という手順があります。確かにエラーは消えます。しかし何が足りなかったのかは分からないままです。次に同じ構成を作るとき、同じ広い役割を付けることになります。 同じことがAPIの有効化でも起きます。gcloud services enable を実行したら動いた、という手順は、それが権限の問題ではなく有効化の問題だったことを教えてくれません。区別できないままだと、次は逆の場面で有効化を試して時間を使います。 エラー文も同じです。Google Cloudの拒否は、認証に失敗したのか、APIが無効なのか、権限が無いのかを示しています。この区別は、次に説明する全体像を知っていれば読み取れます。 最初に理解するべきGoogle Cloudの全体像 先に、すべての操作が通る道筋を押さえます。ここを飛ばすと、後のすべての段階で判断がぶれます。 どのサービスへの操作も、同じ関門を順に通ります。第一に、どの認証情報を使うかが決まります。第二に、対象のプロジェクトが決まります。第三に、そのプロジェクトでそのAPIが有効かどうかが確認されます。第四に、その主体にその操作が許されているかが判定されます。 この4つは独立しています。認証情報が正しくてもAPIが無効なら止まります。APIが有効でも権限が無ければ止まります。順番に確認しないと、直したはずのものが直っていない状態が続きます。 もう1つ、資源の階層が重要です。組織、フォルダ、プロジェクト、そして個々の資源という階層があり、上位に設定した内容は下位へ引き継がれます。したがって、プロジェクトの設定だけを見ても答えが出ないことがあります。 まずは手元の環境が誰として、どのプロジェクトに対して動いているかを確認してください。 gcloud auth list gcloud config list gcloud auth list は有効なアカウントを、gcloud config list は対象プロジェクトとリージョンを示します。ここが想定と違えば、この先の調査はすべて無駄になります。 学習ステップ1：認証情報とプロジェクト 何を理解する段階か：認証情報がどこから読まれるか、そして gcloud と自分のコードで使われる認証情報が別であることです。 なぜエラー解決に必要か：gcloud では通るのにコードでは拒否される、という症状の大半はここです。 最低限覚える概念：アプリケーションのデフォルト認証情報（ADC）は、認証ライブラリが実行環境に応じて自動的に認証情報を探す仕組みです。公式ドキュメントによれば、ADCは次の場所を順に探します。GOOGLE_APPLICATION_CREDENTIALS 環境変数、gcloud auth application-default login コマンドで作られた認証情報ファイル、そしてメタデータサーバーが返す接続済みのサービスアカウントです（How Application Default Credentials works）。 ここに重要な注意があります。公式ドキュメントは、gcloud CLI自体はGoogle Cloudの資源へアクセスするためにADCを使わないと明記しています（Set up Application Default Credentials）。つまり gcloud auth login で入れた認証情報と、ライブラリが使う認証情報は別管理です。 この2つを混同すると、手元では gcloud が動くのにコードだけ認証エラーになる、という状況が生まれます。コードを動かすなら gcloud auth application-default login が必要です。 ...

冒頭まとめ GCP の 409 Conflict は、2つの異なる区分に対応します。エラー区分の定義ファイルを見ると、1つは作ろうとしたものが既に存在する場合、もう1つは同時実行の衝突で処理が中断された場合です。 この2つは、対処が正反対です。 前者は、状態が既に望みどおりになっている可能性があります。作成の操作を繰り返す自動化では、2回目以降は必ずこのエラーになります。異常として止めるのではなく、既にあるものを使う分岐を持つのが正しい作りです。 後者は、他の処理と衝突しました。定義には、この区分をどう扱うべきかが明示されています。実装する側への指針として、失敗した呼び出しだけを再試行してよいのが 503 の区分、上位の処理からやり直すべきなのがこの区分、系の状態が明示的に直されるまで再試行すべきでないのが 400 の区分、と3つが並べて説明されています。例として挙げられているのは、値を確認してから書き換える処理が失敗した場合で、読み取りから書き込みまでの一連の流れをやり直すべきだ、とされています。 つまり、同じ要求をそのまま送り直すのは、この区分に対しては誤った対処です。読み取りからやり直す必要があります。 したがって、409 を見たときに最初に読むべきは status の値です。ここで、待つのか、既存を使うのか、処理全体をやり直すのかが決まります。 エラーの概要 応答の形は他のエラーと共通です。既に存在する場合は次のようになります。 { "error": { "code": 409, "message": "The resource 'projects/my-project/zones/asia-northeast1-a/instances/my-vm' already exists", "status": "ALREADY_EXISTS" } } message に、既に存在する対象の完全な名前が入ります。自分が作ろうとした名前と同じであることを確認できます。 同時実行の衝突の場合は、区分名が変わります。 { "error": { "code": 409, "message": "Aborted due to cross-transaction contention.", "status": "ABORTED" } } こちらは対象の名前ではなく、衝突の理由が書かれます。同時に走っている処理があった、という趣旨の文言です。 コマンド行の道具からは、簡潔な形で表示されます。作成の操作を繰り返した場合、既に存在する旨がそのまま出ます。 まず最初に：status で3方向に振り分ける 第一に、status の値を読みます。ALREADY_EXISTS なら既に存在します。ABORTED なら同時実行の衝突です。 第二に、ALREADY_EXISTS であれば、既存のものが自分の望む状態かを確認します。同じ設定であれば、そのまま使えます。違えば、更新の操作に切り替えます。 第三に、ABORTED であれば、読み取りからやり直します。同じ要求の送り直しではありません。 第四に、FAILED_PRECONDITION が返っている場合は 409 ではなく 400 です。状態が整うまで待つ必要があります（GCP の 400 の記事）。混同しやすい3つですが、区分名で確実に分かれます。 ...

冒頭まとめ 先に結論を述べます。GCP の窓口は、検証に落ちた要求に対して 422 を返しません。Google が公開しているエラー区分の定義ファイルには17の区分があり、それぞれに対応する HTTP の状態コードが併記されていますが、422 は1か所も出てきません。 代わりに使われるのは 400 です。しかも、400 に対応する区分は1つではなく3つあります。引数が不正な場合、対象の現在の状態がその操作を許さない場合、そして値が許容範囲の外にある場合です。他のサービスが 400 と 422 で表現し分けている区別を、GCP は状態コードではなく区分名で表現している、と考えると分かりやすくなります。 したがって、GCP で入力の誤りを追うときに見るべきは、状態コードではなく応答に含まれる区分名です。ここを読まないと、400 が返ってきたという事実だけでは原因を1つに絞れません。 そして、実際に GCP の宛先から 422 を受け取った場合、それを作ったのは GCP の窓口ではありません。前段のプロキシか、GCP 上で動いている自作あるいは第三者のアプリケーションです。この場合、GCP の設定を調べても答えは出ません。 エラーの概要 区分と状態コードの対応は、定義ファイルにそのまま書かれています。検証に関わる3つを抜き出すと、次のようになります。 引数が不正な場合の区分は、対応する状態コードが 400 です。定義の説明では、系の状態に関係なく問題のある引数、たとえば形式の壊れた名前などを指す、とされています。 対象の状態が操作を許さない場合の区分も、対応は 400 です。空でないディレクトリを削除しようとした場合が例として挙げられており、系の状態が変われば成功しうる、という性質を持ちます。 値が許容範囲の外にある場合の区分も、対応は 400 です。読み取りの開始位置が終端を越えている場合などが該当します。 つまり、応答だけを見ると次の形になり、code の値は3つとも同じです。 { "error": { "code": 400, "message": "Request contains an invalid argument.", "status": "INVALID_ARGUMENT" } } 区別できるのは status の値だけです。ここが INVALID_ARGUMENT なのか FAILED_PRECONDITION なのか OUT_OF_RANGE なのかで、次にやることが変わります。 まず最初に：statusの値を読む 第一に、状態コードが 400 であることを確認します。GCP で入力の誤りを疑う場面では、まずここに落ちてきます。 第二に、status の値を読みます。INVALID_ARGUMENT なら送った値そのものが不正で、何度送っても同じです。FAILED_PRECONDITION なら値は正しく、対象の現在の状態が問題です。状態を整えれば同じ要求が通ります。OUT_OF_RANGE なら、値の形式は正しいが範囲の外です。 ...

冒頭まとめ GCP で 502 Bad Gateway を受け取ったとき、最初に押さえるべき事実が1つあります。Google が公開しているエラー区分の定義ファイルには、502 が存在しません。各区分には対応する HTTP の状態コードが併記されており、200・400・401・403・404・409・429・499・500・501・503・504 が並びますが、502 はどこにも出てきません。 これは、各サービスの窓口が自分のエラーとして 502 を返す仕組みになっていない、ということです。つまり GCP で 502 を見たら、応答を作ったのは窓口そのものではなく、その手前にいる仕組みです。多くの場合は Cloud Load Balancing、あるいは経路上のプロキシです。504 が窓口自身からも返りうるのとは、この点で性質が違います。 ロードバランサが返す 502 については、原因を絞り込む手段が用意されています。ログの statusDetails という項目です。公式のトラブルシューティング文書には、この値が response_sent_by_backend であればロードバランサは背後の応答をそのまま渡しただけで、それ以外の値であればロードバランサ自身が作った応答だ、と明記されています。値ごとの意味も一覧になっています。 もう1つ、種類による違いがあります。同じ文書によれば、グローバルおよびリージョンの外部アプリケーション ロードバランサは 503 や 504 といった意味のある状態コードを生成しますが、従来型のアプリケーション ロードバランサは常に 502 を使います。従来型の環境では、待ち時間の超過も接続の失敗も、まとめて 502 として現れます。数字だけでは区別できません。 エラーの概要 利用者側に届くのは簡素な応答で、そこに手がかりはほとんどありません。判断の材料はログ側にあります。 { "httpRequest": { "status": 502 }, "jsonPayload": { "@type": "type.googleapis.com/google.cloud.loadbalancing.type.LoadBalancerLogEntry", "statusDetails": "failed_to_connect_to_backend" }, "resource": { "type": "http_load_balancer" } } 公式文書に説明がある値のうち、502 に結び付きやすいものは次の3つです。 failed_to_connect_to_backend は、ロードバランサが背後との接続を確立できなかったことを示します。文書では、背後で動いている処理が、バックエンド サービスに定義された番号で待ち受けていない可能性がある、と説明されています。 failed_to_pick_backend は、送り先を選べなかったことを示します。すべての背後が正常でない状態が考えられ、正常性の確認に必要な通信が許可されているかを確かめるよう案内されています。なお同じ文書には、グローバルの構成を変更した直後に、設定が行き渡るまでの短い間だけこの値とともに 502 が出ることがある、とも書かれています。 backend_connection_closed_before_data_sent_to_client は、応答が利用者へ渡される前に、背後が予期せず接続を閉じたことを示します。文書では、間に別の装置が挟まっていて、そちらの待ち時間のほうが短い場合に起きうる、と説明されています。 まず最初に：statusDetails を読む 第一に、ログから 502 の件を取り出し、statusDetails の値を確認します。ここが response_sent_by_backend であれば、502 を作ったのは背後のアプリケーションです。調べる先はそちらになり、ロードバランサの設定を触っても変わりません。 ...

冒頭まとめ GCP で 504 Gateway Timeout を受け取ったとき、出どころは大きく2つに分かれます。1つは各サービスの窓口（API）が返すもので、内部的には DEADLINE_EXCEEDED という区分に対応します。もう1つは Cloud Load Balancing が返すもので、こちらは背後の処理が時間内に応答しなかった場合に発生します。両者は調べる場所も直し方も違うため、最初に切り分ける必要があります。 窓口が返す 504 については、公式の定義そのものに重要な記述があります。GCP のエラー区分を定めた定義ファイルには、DEADLINE_EXCEEDED の説明として「状態を変更する操作の場合、操作が正常に完了していてもこのエラーが返ることがある」と書かれています。理由も添えられており、成功の応答が遅れて届いた結果、締め切りのほうが先に過ぎた場合がある、とされています。対応する HTTP の状態コードが 504 であることも同じ場所に記載されています。 つまり、作成や更新の操作で 504 を受け取ったとき、それは「失敗した」という通知ではありません。「結果が分からない」という通知です。そのまま再実行すると、二重に作ってしまう恐れがあります。 Cloud Load Balancing が返す 504 については、判別の手がかりがログにあります。statusDetails という項目が response_sent_by_backend であれば、ロードバランサは背後の応答をそのまま渡しただけです。それ以外の値であれば、ロードバランサ自身が作った応答です。公式のトラブルシューティング文書に、この見分け方が明記されています。 なお、種類によって挙動が違う点にも注意が要ります。公式文書によれば、グローバルおよびリージョンの外部アプリケーション ロードバランサは 503 や 504 といった意味のある状態コードを生成しますが、従来型のアプリケーション ロードバランサは常に 502 を使います。従来型を使っている環境では、待ち時間の超過も 502 として現れます。 エラーの概要 窓口が返す場合、応答には区分の名前が含まれます。 { "error": { "code": 504, "message": "Deadline exceeded", "status": "DEADLINE_EXCEEDED" } } 各社の道具やソフトウェアから呼んでいる場合、この区分名がそのままエラー文に現れることが多く、DEADLINE_EXCEEDED の文字列が手がかりになります。 ロードバランサが返す場合、応答は簡素なもので、詳細はログ側にあります。 { "httpRequest": { "status": 504 }, "jsonPayload": { "@type": "type.googleapis.com/google.cloud.loadbalancing.type.LoadBalancerLogEntry", "statusDetails": "backend_timeout" }, "resource": { "type": "http_load_balancer" } } backend_timeout は、公式文書に「背後の応答に時間がかかりすぎた」と説明されており、対処としてバックエンド サービスの待ち時間の設定を見直すか、なぜ応答に時間がかかっているかを調べることが挙げられています。 ...

冒頭まとめ GCP の 404 Not Found は、指定した対象が見つからないことを示します。素直な意味に見えますが、このエラーには「権限が無い場合に、存在を隠すため 404 が返される」という広く知られた説明があり、どこまで本当なのかが調べ方を左右します。 Google が公開しているエラー区分の定義ファイルには、実装する側への注意書きが添えられています。段階的な機能の公開や、公開されていない許可名簿のように、利用者の層ごと拒否する場合には 404 の区分を使ってよい。しかし、利用者単位のアクセス制御のように、層の中の一部の利用者だけを拒否する場合には、403 の区分を使わなければならない。こう書かれています。原則としては、権限の設定による拒否は 403 です。 一方で、運用上の公式文書には別の記述もあります。権限の無い利用者に対象の存在を明かさないために、403 の代わりに 404 が返ることがある、と明記されています。つまり「404 は必ず存在の問題」とまでは言えません。 それでも、調べる順序は変わりません。同じ公式文書が勧めているのは、まず識別子と経路を確認し、対象が実在するかを確かめ、それでも解決しなければ裏に認可の問題がないかを考える、という順序です。名前、プロジェクト、場所の3つを先に確かめれば、たいていの 404 はそこで原因に行き着きます。権限の側を調べるのは、その後です。 なお、403 の側の文言には「あるいは対象が存在しない可能性があります」という但し書きが付きます（GCP の 403 の記事）。403 と 404 は、存在と権限の両面で互いに染み出し得る隣どうしの区分だ、と押さえておくのが正確です。 エラーの概要 応答は他のエラーと共通の形で、status に区分名が入ります。 { "error": { "code": 404, "message": "The resource 'projects/my-project/zones/asia-northeast1-a/instances/my-vm' was not found", "status": "NOT_FOUND" } } 読むべきは message に含まれる対象の名前です。上の例では、どのプロジェクトの、どの場所の、どの対象を探したかが完全な形で書かれています。自分が指定したつもりの内容と、ここに出ている内容を並べれば、食い違いはすぐ見つかります。 特に見落としやすいのが場所の部分です。指定を省略した場合、道具の設定に入っている既定値が使われます。その既定値が意図と違っていると、正しい名前を指定しているのに見つからない、という状態になります。 コマンド行の道具からは、同じ内容が簡潔な形で出ます。 ERROR: (gcloud.compute.instances.describe) Could not fetch resource: - The resource 'projects/my-project/zones/asia-northeast1-a/instances/my-vm' was not found まず最初に：応答に出ている完全な名前と、自分の指定を並べる 第一に、message に出ている対象の完全な名前を読みます。ここには、実際に探しに行った先がそのまま書かれています。 ...

冒頭まとめ GCP の 429 Too Many Requests は、何かの上限を使い切ったことを示します。エラー区分の定義ファイルでは、利用者ごとの割り当てかもしれないし、ファイル置き場の空き容量かもしれない、という書き方になっています。つまり「要求の回数が多すぎる」とは限りません。量や個数の上限も同じ区分に入ります。 このエラーの扱いやすさは、応答に付く details にあります。上限に関する情報が、機械が読める形で定義されています。何に対する上限か（対象）、どの指標か、上限の識別子、上限の値、上限が適用される条件、そして違反の説明です。さらに、待つべき時間を示す構造も別に定義されています。 したがって、どの上限に当たったかを推測する必要はありません。応答に書かれています。旧来の対処のように、待ち時間を適当に入れて様子を見る、という進め方は不要です。 もう1つ、見落としやすい重要な点があります。上限の出どころが、呼び出したサービスとは限りません。定義には具体例が添えられていて、ある管理サービスを呼び出したときに、その内部で別の計算資源のサービスを使い、そちらの上限に当たる場合がある、と説明されています。この場合、応答にはその依存先のサービス名が入ります。呼び出した先の上限だけを調べても見つからないのは、このためです。 エラーの概要 応答の形は次のようになります。上限に関する詳細と、待ち時間の指示が別々に入ります。 { "error": { "code": 429, "message": "Quota exceeded for quota metric 'Requests' and limit 'Requests per minute'", "status": "RESOURCE_EXHAUSTED", "details": [ { "@type": "type.googleapis.com/google.rpc.QuotaFailure", "violations": [ { "subject": "project:my-project", "description": "Quota 'CPUS' exhausted. Limit: 24 in region asia-northeast1.", "apiService": "compute.googleapis.com", "quotaMetric": "compute.googleapis.com/cpus", "quotaId": "CPUS-per-project-region", "quotaDimensions": { "region": "asia-northeast1" }, "quotaValue": "24" } ] }, { "@type": "type.googleapis.com/google.rpc.RetryInfo", "retryDelay": "30s" } ] } } 読むべき項目を順に挙げます。 ...

冒頭まとめ GCP の 500 Internal Server Error は、1つの意味を持つエラーではありません。エラー区分の定義ファイルを見ると、500 に対応する区分は3つあります。 1つ目は内部のエラーです。定義には、下層の系が前提としていた不変の条件が破られたことを意味し、この区分は深刻なエラーのために予約されている、と書かれています。 2つ目は不明なエラーです。定義では、別の空間から受け取った状態がこちらでは未知のエラーに属する場合や、十分なエラー情報を返さない窓口からのエラーが、この区分に変換されることがある、と説明されています。つまり「原因が分からない」ではなく「原因を伝える経路で情報が落ちた」という意味です。 3つ目は回復不能なデータの損失または破損です。説明はこの一文だけですが、意味は重大です。 この3つで、次にやることが変わります。3つ目が返っているなら、再試行してはいけません。同じ操作を繰り返すより、何が失われたかを確認するのが先です。 残る2つについては、再試行が公式に認められています。運用側の公式文書は、指数的に間隔を伸ばしランダム性を加える再試行を勧めており、500 や 503 のサーバー側のエラーでは最初の間隔を最短1秒としています。503 との違いは、定義の側にあります。503 の定義には、一時的な状態である可能性が高く再試行で解消できると書かれているのに対し、500 の定義にはそうした見込みが書かれていません。直る保証の有無が違うだけで、再試行が禁じられているわけではない、と押さえてください（GCP の 503 の記事）。 エラーの概要 応答の形は他のエラーと共通で、status に区分名が入ります。 { "error": { "code": 500, "message": "Internal error encountered.", "status": "INTERNAL" } } status の値が INTERNAL、UNKNOWN、DATA_LOSS のいずれかで、意味が変わります。message は多くの場合、内部でエラーが起きたという趣旨の短い文言だけで、それ以上の手がかりはありません。 details に識別子が入っていれば、そこから判断できる場合があります。設計の指針では、すべてのエラー応答が機械が読める識別子を含むべきとされています。ただし 500 の場合、内部の事情を外に出さない方針から、詳細が乏しいことが実際には多くあります。 そのため、このエラーは他と違って、応答だけで原因に辿り着けないのが普通です。調査は記録の側に移ります。 まず最初に：status を読み、再現するかを見る 第一に、status の値を読みます。DATA_LOSS であれば、再試行の前にデータの状態を確認します。他の2つであれば、次に進みます。 第二に、同じ操作が再現するかを確かめます。1回だけであれば一時的なものです。繰り返し同じ場所で起きるなら、要求の内容に何か引き金があります。 第三に、他の操作でも起きているかを見ます。特定の操作だけなら要求側、幅広い操作で起きているなら提供側の問題である可能性が高くなります。 第四に、稼働状況の表示を確認します。ただし、表示が正常でも特定の機能だけが不調なことはあるので、表示だけを根拠に自分側の問題と決めつけないでください。 よくある原因と解決手順 原因1：一時的なもので、再試行で通る 最も多い形です。同じ要求が2回目には通ります。公式の指針では、間隔を指数的に伸ばしてランダム性を加え、最初の間隔は最短1秒です（429 の最短30秒とは扱いが違います。GCP の 429 の記事）。 ただし、再試行してよいかどうかは操作の種類によります。区分の定義には、503 について、同じ結果になるとは限らない操作の再試行が常に安全とは限らない、という注意が添えられています。同じ注意が 500 にも当てはまります。 Before（結果が変わりうる操作を無条件で再送する）： for i in range(3): r = create_resource() # 作成の操作 if r.ok: break time.sleep(2 ** i) # → 1回目が内部で成功していた場合、二重に作られる After（作成の操作は、実物を確認してから判断する）： ...

冒頭まとめ GCP の 400 Bad Request は、1つの意味を持つエラーではありません。Google が公開しているエラー区分の定義ファイルを見ると、400 に対応する区分は3つあります。引数が不正な場合、対象の状態がその操作を許さない場合、そして値が有効な範囲の外にある場合です。 この3つは、対処が根本的に違います。定義の説明文が、その違いをはっきり述べています。1つ目は「系の状態に関係なく問題のある引数」を指し、例として形式の壊れたファイル名が挙げられています。何度送っても結果は変わりません。2つ目は「系がその操作に必要な状態にない」ことを指し、例として空でないディレクトリの削除が挙げられています。状態を直せば同じ要求が通ります。3つ目は「有効な範囲を越えた操作」で、ファイルの終端を越えて読もうとした場合が例です。 したがって、GCP で 400 を受け取ったときに最初に読むべきは、状態コードではなく応答の status の値です。ここを読まずに要求の書式を疑うと、2つ目や3つ目の場合に見当違いの調査を続けることになります。 さらに、応答には details という配列が付きます。設計の指針には、すべてのエラー応答は機械が読める識別子を含まなければならない、と定められています。どの項目が悪いかを名指しする構造もこの中に入るため、原因の特定はここでほぼ完了します。 エラーの概要 実際の応答は、基本の4項目と details 配列で構成されます。 { "error": { "code": 400, "message": "There was a problem with the request.", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "INVALID_ARGUMENT", "domain": "example.googleapis.com", "metadata": { "requestId": "t-a8896317-069f-4198-afed-182a3872a660" } }, { "@type": "type.googleapis.com/google.rpc.BadRequest", "fieldViolations": [ { "field": "destinations[0].login_account.account_id", "description": "String is not a valid number.", "reason": "INVALID_NUMBER_FORMAT" } ] } ] } } details の中身は @type で種類が分かれます。ErrorInfo は機械が読める識別子で、reason に大文字と下線だけの短い語が入ります。設計の指針では、この語は63文字以内で、大文字・数字・下線の形式に従うと定められています。domain には、どのサービスが出したエラーかが入ります。 ...

冒頭まとめ GCP の 401 Unauthorized は、「あなたが誰なのか分からない」という意味です。「あなたにその操作をする資格がない」ではありません。この2つは似て見えますが、GCP では明確に区別されています。 Google が公開しているエラー区分の定義ファイルを読むと、その区別が仕様として書かれています。401 に対応する区分の説明は「その操作に対する有効な認証情報を持っていない」という一文だけです。一方、403 に対応する区分の説明には、呼び出し元を特定できない場合にこれを使ってはならず、代わりに 401 の区分を使うこと、と明記されています。 つまり、認証情報が届いていない、あるいは読めない段階が 401 です。誰であるかは分かったが、その人にはその操作が許されていない段階が 403 です。この境界は、対処の方向を決めます。401 に対して権限の役割を追加しても、何も変わりません。 もう1つ、実務で誤解されやすい点があります。サービスアカウントの鍵は、既定では期限切れになりません。公式文書に、利用者が作成した鍵は既定では期限が無い、と明記されています。組織の方針で期限を設定した場合にのみ期限が発生します。したがって「鍵の期限切れ」を最初に疑うのは、多くの環境で見当違いです。 期限があるのは、短命の認証情報のほうです。こちらは既定で1時間、組織の設定を変えれば最大12時間まで延ばせます。長時間動く処理で 401 に当たるなら、疑うべきはこちらです。 エラーの概要 応答の形は他のエラーと共通で、status に区分名が入ります。 { "error": { "code": 401, "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.", "status": "UNAUTHENTICATED" } } status が UNAUTHENTICATED であることが、このエラーの性質を示しています。認証されていない、という区分です。 details 配列には、機械が読める識別子が入ります。設計の指針では、すべてのエラー応答が識別子を含むべきとされているため、reason の値で原因を分岐できます。 コマンド行の道具からは、認証情報が見つからない旨の文言が出ます。この場合、要求は送られてすらいないことがあります。手元で認証情報を探す段階で失敗しているためです。応答としての 401 なのか、手元での失敗なのかは、文言で区別できます。 まず最初に：誰として認証されているかを確認する 第一に、いま自分がどの身元で操作しているかを確認します。 gcloud auth list 第二に、実際に使われる認証情報が何かを確認します。ここが意図と違っていることが、このエラーの大半です。 gcloud auth application-default print-access-token > /dev/null && echo "既定の認証情報あり" || echo "既定の認証情報なし" 第三に、status が UNAUTHENTICATED か PERMISSION_DENIED かを見ます。後者であれば、認証は通っており、問題は権限の側です。調べる先が変わります（GCP の 403 の記事）。 ...