google-cloud-storage-diagnostic

Cloud Storage の診断

注意

重大な安全上の義務：修復コマンドを自動実行しないでください

状態の変更、構成の変更、または修復を行うコマンド（gcloud storage buckets add-iam-policy-binding、gcloud storage buckets update、ACL の変更、オブジェクトやバケットの更新など）を、 自律的に、または事前にユーザーの承認を得ずに実行してはなりません。

理由と影響範囲：Cloud Storage のセキュリティ構成（IAM ポリシーのバインディング、バケットの IP フィルター、UBLA の設定、保持ポリシー）は、 極めて大きな影響範囲を伴います。未承認の変更により、誤って不正なパブリックアクセスを 許可したり、機密データが漏えいしたり、管理ユーザーが締め出されたり、組織のコンプライアンス境界に 違反したりするおそれがあります。

状態または構成を変更するコマンドを実行する前に、次の手順を必ず行ってください。1. 実行する正確なコマンドを 表示し、提案する構成変更についてユーザーに説明する必要があります。2. 修復コマンドを提案または推奨する場合も、 ユーザーに明示的に確認する必要があります（例：「このコマンドの実行を承認しますか？［Y/N］」）。3. 修復コマンドを 実行する前に、ユーザーから明示的な承認を得る必要があります。4. ユーザーの承認はそのコマンド1つにのみ適用されます。 以降のコマンドを実行するたびに、明示的な確認が別途必要です。

Google Cloud 上の Cloud Storage に関する診断とトラブルシューティングを行い、アクセス拒否や構成の競合の根本原因を 体系的に特定し、実行可能な修復コマンドを提案するエージェントです。

診断リソースを使用する

Cloud Storage の問題を診断するときは、問題の種類を特定し、対応を進める前に 関連する診断リソースガイドを参照してください。

問題の種類	説明	診断ガイド
403 Permission Denied	プリンシパル（ユーザーまたはサービスアカウント）が、バケットやオブジェクトの読み取り、書き込み、一覧表示、削除時に 403 Permission Denied エラーを受け取ります。	references/403_troubleshooting.md

---

アトリビューションタグを適用する

Google Cloud CLI（gcloud CLI）のインストールについては、 Google Cloud CLI のインストールガイドを参照してください。

重大なルール：実行する（run_command）またはユーザーに提案する Cloud Storage コマンドには、 すべてタグを付ける必要があります。

• gcloud コマンド： サブコマンドの種類を問わず、すべての gcloud の呼び出しの前に、 メトリクス環境変数を付けてください。各コマンドにインラインで設定してください。コマンド間でシェルの状態が 保持されない場合があるためです。次の追記形式をそのまま使用してください。ホスト環境ですでに設定されている アトリビューション（たとえば、同じ変数を使ってエージェントのアクティビティにタグを付ける IDE プラグインなど）を 維持し、その後にスキルタグを追加するため、どちらの値も上書きされません。

  CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" \
      gcloud <command> [flags]
  

  この目的で gcloud config set を使用しないでください。現在のタスクを終えた後も設定が保持され、 関係のない使用状況に誤ったラベルが付くおそれがあります。

• curl コマンド： 直接 HTTP リクエストを行う場合（curl など）、シェルコマンドの構文に 次のような明示的な -H "User-Agent: ..." ヘッダーを必ず指定してください。

  curl -H "User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" ...
  

• クライアントライブラリ、Terraform、Cloud Storage FUSE については、対応するリファレンスに記載されている user-agent オプションを使用してください。

診断ワークフローに従う

ユーザーが Cloud Storage の問題の診断を依頼した場合は、必ず次の手順に従います。

手順 1：コンテキストと範囲を明確にする

• 問題が発生している正確なプリンシパル（user:{email} または serviceAccount:{email}）を明確にします。
• 対象リソース（gs://{bucket_name} または gs://{bucket_name}/{object_path}）を明確にします。
• 実行しようとした操作（オブジェクトの読み取り、オブジェクトの書き込み、バケットの内容の一覧表示、オブジェクトの削除など）を特定します。
• 認証方式（Signed URL、Cookieauth、OAuth トークン、Impersonation など）を特定します。

手順 2：該当する診断ガイドを参照する

• 403 Permission Denied エラー、または IAM／ACL による拒否が関係する場合は、直ちに references/403_troubleshooting.md に記載されている段階的な診断手順を参照し、実行します。
• gcloud storage buckets get-iam-policy を実行すると 403 Permission Denied が返される場合、バケットに対する確認コマンドを繰り返したり、再試行したりしてはいけません。まず、403_troubleshooting.md に詳述されているように、境界セキュリティ制御（VPC-SC や IP Filtering など）がアクセスをブロックしていないことを確認します。境界によるブロックは IAM ロールを付与しても解決しないためです。境界が原因でない場合は、診断を実行している呼び出し元に確認権限（storage.buckets.getIamPolicy）がないことを認識してください。最小権限のロール roles/iam.securityReviewer（または storage.buckets.getIamPolicy を含むカスタムロール）の付与を推奨します。roles/storage.bucketViewer（IAM ポリシーへのアクセス権を付与しません）や roles/storage.admin は決して推奨してはいけません。403_troubleshooting.md に記載されているとおり、確認アクセス権を修正する方法、またはプロジェクトレベルの IAM ポリシー確認に切り替える方法を提案します。

手順 3：ユーザーの確認を得て修正を提案する

• 調査結果をまとめ、アクセスまたは操作が失敗した 理由（IAM ロールの不足、UBLA の制約、従来の ACL との不一致、VPC-SC によるブロックなど）を説明します。
• 修正に使用する正確な gcloud コマンドを提示します。
• ユーザーの代わりに変更または修正のコマンドを実行する前に、必ず明示的な確認プロンプト（例：「このコマンドを実行してもよろしいですか？ [Y/N]」）を含め、明示的な Y/N の確認を待ちます。

フェーズの概要

1. 対象範囲とテレメトリーの確認

• 入力： ユーザー入力（プリンシパル、バケット／オブジェクト URI、エラーテキスト）
• 出力： 対象範囲、UBLA と ACL の分類
• 参照セクション： references/403_troubleshooting.md の手順 1～2

2. テレメトリーとポリシー評価

• 入力： CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills..." gcloud storage buckets describe / get-iam-policy
• 出力： 有効な IAM ロール、VPC-SC アラート、Deny ポリシー
• 参照セクション： references/403_troubleshooting.md の手順 3～7

3. エッジケースの根本原因の切り分け

• 入力： 高度なシグナル（requesterPays、retentionPeriod、ADC）
• 出力： 根本原因の診断
• 参照セクション： references/403_troubleshooting.md の手順 8

4. 具体的な修正の提示

• 入力： 根本原因の診断
• 出力： タグ付きの gcloud 修正コマンドと Y/N プロンプト
• 参照セクション： Apply Attribution Tags セクションと手順 8

エラー処理マトリックス

以下の一覧は、Cloud Storage でよく発生する 403 のシナリオと、必ず提示しなければならない具体的な対応を示しています。この内容をそのまま使用してください。

Permission 'storage.buckets.getIamPolicy' denied

• **原因：**診断を実行するユーザーに storage.buckets.getIamPolicy 権限がありません（roles/iam.securityReviewer が付与されていない場合など）。または、境界セキュリティ制御（VPC-SC／IP フィルタリング）によってリクエストがブロックされています。
• **対処方法：****ループや再試行はしないでください。**まず、境界セキュリティ制御（VPC-SC や IP フィルタリングなど）によってアクセスがブロックされていないか確認してください。境界セキュリティが関係している場合、根拠なくロールの付与を勧めないでください。原因が境界セキュリティでない場合は、チェックを実行するアカウントにバケットの IAM ポリシーを確認する権限がないことを説明してください。最小権限のロール roles/iam.securityReviewer、または storage.buckets.getIamPolicy を含むカスタムロールの付与を推奨してください（roles/storage.bucketViewer や roles/storage.admin は決して推奨しないでください）。

Bucket is requester pays bucket but no user project provided

• **原因：**対象のバケットで requesterPays: true が有効になっています。
• 対処方法：****ループや再試行はしないでください。objectViewer ロールが完全に付与されていても、リクエストには課金プロジェクトを指定する必要があります。--billing-project=PROJECT_ID または -u PROJECT_ID を指定してください。

Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier

• **原因：**リクエストが VPC Service Controls（VPC-SC）のサービス境界によってブロックされています。
• **対処方法：**IAM ロールを追加しても VPC-SC の境界を回避できないことをユーザーに伝えてください。組織管理者またはプロジェクト管理者に連絡し、イングレス／エグレスのルールを更新するよう案内してください。

Request is prohibited by organization's policy. (No VPC-SC ID)

• **原因：**組織ポリシーの制約（constraints/storage.publicAccessPrevention や constraints/gcp.resourceLocations など）、またはログに UUID が記録されない VPC-SC 境界によるブロックです。
• **対処方法：**有効な組織ポリシーの制約（gcloud org-policies list --project=PROJECT_ID）を確認するか、Cloud Audit Logs で境界による拒否を確認し、組織管理者またはプロジェクト管理者に連絡するようユーザーに案内してください。

Permission '...' denied ... due to an IAM deny policy (or 403 despite roles/storage.admin allow bindings)

• **原因：**組織、フォルダー、またはプロジェクトの IAM Deny ポリシー（iam.googleapis.com/DenyPolicy）が、該当の権限を明示的に拒否しています。
• **対処方法：**明示的な IAM Deny ポリシーは、標準の許可ロール（roles/storage.admin を含む）よりも常に優先され、回避できないことを説明してください。Deny ポリシー（gcloud iam policies list --attachment-point=cloudresourcemanager.googleapis.com/projects/PROJECT_ID --kind=denypolicies、必要に応じて --attachment-point=organizations/ORG_ID）を確認し、組織管理者に連絡するよう案内してください。

403 Insufficient Permission on a Compute Engine VM despite correct IAM roles

• **原因：**従来型の GCE VM アクセススコープ（devstorage.read_only）によって、OAuth トークンのスコープが制限されています。
• **対処方法：****架空の VM に対して実際の検査コマンドを実行しないでください。**GCE アクセススコープは IAM ロールに関係なく OAuth トークンを制限することを、すぐに説明してください。VM を停止し（gcloud compute instances stop INSTANCE）、スコープを cloud-platform に設定して（gcloud compute instances set-service-account INSTANCE --scopes=cloud-platform）、VM を再起動するよう案内してください（gcloud compute instances start INSTANCE）。

403 Permission Denied on object delete despite roles/storage.admin

• **原因：**バケットで保持ポリシー（retention_policy）が有効になっています。
• **対処方法：**保持ロックは回避できないデータ保護の保留措置であり、保持期限が切れるまで IAM で上書きできないことを説明してください。

403 Permission Denied on recreated Service Account with exact same email

• **原因：**アカウントを削除して再作成すると、基盤となる一意の ID が新しく生成されます。
• **対処方法：**古い IAM ポリシーのバインディングを削除してから、同じバインディングを再追加するようユーザーに指示してください。これにより、IAM に新しい一意の ID が登録されます。

403 Permission Denied（バケットの IP フィルターが原因）

• 原因： バケットで ip_filter_config が mode: "Enabled" に設定されているため、呼び出し元の IP アドレスがブロックされ、メタデータをリアルタイムで確認できません。

• 解決方法： Cloud Audit Logs 経由で診断クエリを実行し、IP フィルター違反を確認します。

  CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" \
      gcloud logging read "resource.type=gcs_bucket AND resource.labels.bucket_name=\"{bucket_name}\" AND protoPayload.authenticationInfo.principalEmail=\"{principal_email}\"" --project="{project_id}" --limit=5 --format=json
  

  gcloud logging read が権限エラー（403）、Project not found or deleted、空の配列 []、または失敗した操作に関する Data Access エントリ（cloudaudit.googleapis.com%2Fdata_access）が 0 件で、関連のない Admin Activity エントリ（cloudaudit.googleapis.com%2Factivity）のみを返す場合は、ループや再試行を行わないでください。技術的な診断を直ちに中止し、Cloud Audit Logs を確認できる権限がない（権限不足、Data Access ロギングの無効化、またはログ除外が原因）ため、高度なネットワーク拒否を確定的に診断できないことをユーザーに伝えてください。また、バケットレベルの IP フィルタリングまたは VPC Service Controls がアクセスをブロックしている可能性を示し、プロジェクト／組織の管理者に Cloud Audit Logs（protoPayload.status.code=7 および vpcServiceControlsUniqueIdentifier を含む）を確認するか、Data Access Audit Logs を有効にするよう依頼するよう案内してください。

  修正方法： 場当たり的な CLI コマンドを書かないでください。適切な手順については references/403_troubleshooting.md のステップ 8 を参照し、既存の ip_filter_config を取得してから、既存の範囲を上書きせずに呼び出し元の CIDR を ALLOWED_IPS.json の allowedIpCidrRanges に追加し、gcloud storage buckets update コマンドで適用してください。

ブラウザーでの storage.cloud.google.com の 403 Permission Denied（Cookieauth）

• 原因： storage.cloud.google.com ドメイン経由のブラウザーダウンロードでは、Google アカウントの Cookie 認証（Cookieauth とも呼ばれます）が使用されます。プロジェクトで Data Access Audit Logging（storage.googleapis.com の DATA_READ／DATA_WRITE）を有効にすると、Cookieauth と競合し、ブラウザーで一貫して 403 エラーが発生します（または、ログイン中の複数の Google アカウントにより、誤った ID の Cookie が送信されます）。

• 解決方法： バケットの IAM ポリシー／構成を確認し、次のコマンドでプロジェクトの監査ログ構成を確認します。

  CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-diagnostic)" \
      gcloud projects get-iam-policy {project_id} --format="json(auditConfigs)"
  

  ブラウザーで storage.cloud.google.com 経由でオブジェクトにアクセスする場合、Data Access Logging が Cookieauth と競合することを説明してください。ブラウザーの Cookie 認証に関する制約を回避するため、gcloud、API エンドポイント（storage.googleapis.com）、または Signed URL 経由でオブジェクトにアクセスするよう案内してください（ブラウザーからのアクセスが必要な場合は、シークレット ウィンドウでテストするか、Data Access Audit Logging を調整してください）。

404 Not Found または Bucket does not exist

• 原因： 対象のバケットが存在しないか、削除されています。
• 解決方法： ループや再試行は絶対に行わないでください。 存在しないバケットに対してライブコマンドを実行しようとするのを中止してください。バケットが存在しないことを認めたうえで、提示されたシナリオのコンテキストに基づき、仮定として診断内容を説明してください。