cloud-logging-cross-project-configuration

プロジェクト間ロギングの構成

このスキルでは、gcloud コマンドを使用して Cloud Logging を構成し、ログデータの発生元にかかわらず、ログデータを一元的な場所に保存する方法について説明します。また、複数のプロジェクトに保存されているログデータをクエリする方法についても説明します。

重要

サンドボックスのネットワーク制限（エージェントのテストでは重大）： 評価中または制限されたサンドボックス環境では、GCP API へのネットワーク通信がブロックされます。リソース名、プロジェクト ID、組織 ID を探すために、ネットワークを使った探索コマンドを実行しないでください。ユーザープロンプトまたは指示で指定された正確なプロジェクト ID またはプレースホルダー（例：{project_id}、{source_project_id}、{central_project_id}）を必ず使用してください。これらのリソースは存在すると仮定し、構成コマンドを直接実行してください。こうした探索コマンドを実行すると、処理がハングしてタイムアウトします。

帰属情報

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず使用状況の帰属情報をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、またはユーザーコード内での実行は不可）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-logging-cross-project-configuration)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:cloud-logging-cross-project-configuration) を追加してください。

安全性と確認の段階（重大）

ユーザーに代わってコマンドを実行する前に、要求された操作に応じて、以下の安全性の段階を必ず遵守してください。

1. 段階 R：読み取り専用
   • 説明： 状態の読み取りまたはログのクエリのみを行うコマンドです。
   • コマンドの例：
     • gcloud logging read
     • gcloud logging buckets list
   • ルール： 確認は不要です。情報収集のため、これらのコマンドをすぐに実行できます。
2. 段階 M：変更（課金なし）
   • 説明： 直接的なストレージ料金や課金が発生せず、リソースのセキュリティ／アクセス ポリシーにも影響しない、構成の変更または無料のメタデータ作成です。
   • コマンドの例：
     • gcloud logging views create
     • gcloud logging views update
     • gcloud logging scopes create
     • gcloud logging buckets create
   • ルール： 確認は不要です。構成を適用するため、これらのコマンドをすぐに実行できます。
3. 段階 B：課金およびセキュリティに関わる変更（高リスク）
   • 説明： 課金が発生するリソースや統合を作成する操作、またはセキュリティと IAM のアクセス制御ポリシーを変更する操作です（権限昇格のリスクがあります）。
   • コマンドの例：
     • gcloud logging metrics create
     • gcloud logging links create
     • gcloud projects add-iam-policy-binding
   • ルール： 対話形式での確認が必要です。 これらのコマンドは課金が発生するリソースを作成するか、セキュリティ アクセスを変更します。実行前に、正確なコマンドをそのまま提示し、ユーザーの確認を得る必要があります。確認を求めるのと同じターンで実行してはなりません。
4. 段階 D：取り消せないデータ損失を引き起こす操作
   • 説明： シンクの除外など、ログを恒久的に破棄または削除する操作です。
   • コマンドの例：
     • gcloud logging buckets delete
     • gcloud logging sinks update --add-exclusion
   • ルール： 明示的な文字入力による確認が必要です。 これらのコマンドはログを直ちに、取り消せない形で破棄または削除するか、ログデータが保存されない結果を招く可能性があります。「はい、ログを破棄します」など、明示的な文字入力による確認をユーザーに求め、返答があるまで実行を停止する必要があります。

決定マトリクス：集中ストレージと読み取り時の集約

この決定マトリクスを使用して、集中ストレージと読み取り時の集約のどちらを選ぶか評価してください。集中ストレージでは、ログデータの発生元にかかわらず、1 つのログバケットにルーティングします。クエリは集中管理されたログバケットに対して実行します。読み取り時の集約では、ログデータは発生元のリソースに保存されます。ただし、1 つのクエリで、すべてのリソースにクエリを実行してデータを集約します。

プロジェクト間のログを処理するための最適なアーキテクチャを決定したら、以下に記載されている該当する設定手順に従ってください。

基準	集中ストレージ	読み取り時の集約
GCP プロジェクトの規模	数千のプロジェクトまで拡張可能	375 未満のプロジェクトに最適です。
: : : :
ログストレージ	1 つのログバケットに集約	発生元のリソースに保存
: : : :
SQL 分析	簡単です。Observability	困難です。複数のログバケットに
: : Analytics を使用して : クエリを実行する必要があります。
: : 統一的にクエリを実行できます。 : :
アクセス制御	集中管理されたログバケットの	ログデータを保存するリソース上の
: : ログビューでアクセスを制限できます。 : すべてのビューに IAM アクセスが必要です。
: : : :
設定の複雑さ	プロジェクト、フォルダ、	バケットベースのログベース指標に
: : 組織の構造に応じて選択肢が異なります。 : 影響しません。 :
コスト	除外を設定しない場合、ログ	費用対効果に優れています。データの
: : バケットにデータが重複して保存される : レプリケーションはありません。
: : 可能性があります。 : :

アーキテクチャ

集中ストレージ（ログルーティング）

graph LR
    subgraph "Source Project(s)"
        Log[Resource Logs] --> Sink["Sink: route-to-central-project"]
    end

    subgraph "Central Project"
        Sink --> Bucket["Bucket: central-logs-bucket (us-central1)"]
    end

読み取り時の集約（ログスコープ）

graph LR
    subgraph "Source Project 1"
        Log1[Resource Logs] --> Bucket1["Bucket: _Default"]
    end

    subgraph "Source Project 2"
        Log2[Resource Logs] --> Bucket2["Bucket: _Default"]
    end

    subgraph "Scoping Project (No Log Storage)"
        Scope["Log scope: central-query-scope"]
        Scope -.-> View1["_AllLogs View on Bucket1"]
        Scope -.-> View2["_AllLogs View on Bucket2"]
    end

設定手順：集中ストレージ（ログルーティング）

以下の手順で、1 つ以上のソースプロジェクトのログを、プロジェクト内の中央ログバケットにルーティングします。ログデータの保存に使用する Google Cloud プロジェクトを作成するか、選択してください。これが中央プロジェクトです。

1. 中央プロジェクトにログバケットを作成する（Tier M）

Log Analytics を有効にしたカスタムログバケットを作成します。

[Tip] リージョンログバケットを使用してください。たとえば、ロケーションを us-central1 に設定します。global ロケーションは使用しないでください。この方法により、 Observability Analytics と SQL クエリとの互換性が確保されます。

gcloud logging buckets create {bucket_id} \
    --project={central_project_id} \
    --location={region} \
    --retention-days={retention_days} \
    --enable-analytics

2. 中央プロジェクトにログシンクを作成する（Tier M）

中央プロジェクトにプロジェクトレベルのシンクを作成し、中央ログバケットを指定します。このシンクは、中央プロジェクトの Log Router に到達したログを中央ログバケットにルーティングします。

新しく作成したバケットが他のプロジェクトのデータを集中管理するためのものであり、中央プロジェクトがソースプロジェクトの 1 つではない場合、中央シンクでは中央プロジェクト自身のログを除外する必要があります。{bucket_id} と _Required バケット間の重複を避けるため、この中央シンクで _Required 監査ログの除外を設定してください。

gcloud logging sinks create {sink_name} \
    logging.googleapis.com/projects/{central_project_id}/locations/{region}/buckets/{bucket_id} \
    --project={central_project_id} \
    --exclusion=filter='logName:"projects/{central_project_id}/"' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/activity")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/activity")' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/system_event")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/system_event")' \
    --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/access_transparency")' \
    --exclusion=filter='LOG_ID("externalaudit.googleapis.com/access_transparency")'

3. ソースリソースにログシンクを作成する（Tier M）

ログを中央プロジェクトにルーティングするには、各ソース組織、フォルダ、またはプロジェクトにログシンクを作成する必要があります。--log-filter 引数を使用して、一部のログだけをルーティングするようシンクを構成することもできますが、すべての監査ログ以外のログをルーティングし、中央ログバケットのカスタムログビューを使って、宛先でアクセスを制限するかログを分割することを推奨します。

• 組織レベルのログシンクの場合

  gcloud logging sinks create {sink_name} \
      logging.googleapis.com/projects/{central_project_id} \
      --organization={source_organization_id} \
      --include-children \
      --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/activity")' \
      --exclusion=filter='LOG_ID("externalaudit.googleapis.com/activity")' \
      --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/system_event")' \
      --exclusion=filter='LOG_ID("externalaudit.googleapis.com/system_event")' \
      --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/access_transparency")' \
      --exclusion=filter='LOG_ID("externalaudit.googleapis.com/access_transparency")'
  

• プロジェクトレベルのログシンクの場合

  gcloud logging sinks create {sink_name} \
      logging.googleapis.com/projects/{central_project_id} \
      --project={source_project_id} \
      --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/activity")' \
      --exclusion=filter='LOG_ID("externalaudit.googleapis.com/activity")' \
      --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/system_event")' \
      --exclusion=filter='LOG_ID("externalaudit.googleapis.com/system_event")' \
      --exclusion=filter='LOG_ID("cloudaudit.googleapis.com/access_transparency")' \
      --exclusion=filter='LOG_ID("externalaudit.googleapis.com/access_transparency")'
  

4. シンクの書き込み元に IAM 権限を付与する（Tier B）

重要

セキュリティアクション（Tier B）： IAM 権限を付与するとアクセス制御ポリシーが変更されるため、実行前にユーザーから明示的な確認を得る必要があります。

ソースシンクが中央プロジェクトのルーターにログをルーティングできるようにし、中央シンクが中央バケットにログを書き込めるようにするには、次の手順を実行します。

1. ソースシンクにログ書き込み権限を付与します： ソースログシンクの writerIdentity を取得し、中央プロジェクトで roles/logging.logWriter を付与します。

   # ソースシンクの書き込み元の ID を取得します
   gcloud logging sinks describe {sink_name} \
       --project={source_project_id} \
       --format="value(writerIdentity)"
   

   出力されるのは、次のコマンドで使用する {source_writer_identity} の値です（例：serviceAccount:...）。

   # 中央プロジェクトでログ書き込み権限を付与します
   gcloud projects add-iam-policy-binding {central_project_id} \
       --member={source_writer_identity} \
       --role=roles/logging.logWriter
   

2. 中央シンクにバケット書き込み権限を付与します： 中央ログシンクの writerIdentity を取得し、中央プロジェクトで roles/logging.bucketWriter を付与します。

   # 中央シンクの書き込み元の ID を取得します
   gcloud logging sinks describe {central_sink_name} \
       --project={central_project_id} \
       --format="value(writerIdentity)"
   

   出力されるのは、次のコマンドで使用する {central_writer_identity} の値です。

   # 中央プロジェクトでバケット書き込み権限を付与します
   gcloud projects add-iam-policy-binding {central_project_id} \
       --member={central_writer_identity} \
       --role=roles/logging.bucketWriter
   

5. 中央バケットにカスタムログビューを作成する（Tier M）

すべてのログが同じ中央バケットにルーティングされているため、ログを分割したり、ログ ID やプロジェクトごとにアクセスを制限したりするには、中央バケットにカスタムログビューを作成します。

• ログ ID でフィルタリングする場合：

  gcloud logging views create {view_id} \
      --bucket={bucket_id} \
      --location={region} \
      --project={central_project_id} \
      --log-filter='LOG_ID("{log_id}")'
  

• ソースプロジェクトでフィルタリングする場合：

  gcloud logging views create {view_id} \
      --bucket={bucket_id} \
      --location={region} \
      --project={central_project_id} \
      --log-filter='project_id="{source_project_id}"'
  

集中ログルーティングを確認する（Tier R）

ソースプロジェクトから中央リージョナルログバケットにログがルーティングされていることを確認します。

1. ソースプロジェクトにテストログを書き込む：

   gcloud logging write {test_log_id} "Test log entry for verification" \
       --severity=WARNING \
       --project={source_project_id}
   

2. 中央ログバケットからテストログを読み取る： リージョナルログバケットでは、--view フラグを必ず指定する必要があります。デフォルトビュー _Default にはデフォルトフィルタに一致するログしか含まれないため、中央バケットの**_AllLogs**ビューまたはカスタムログビューをクエリしてください。

   gcloud logging read 'logName:"projects/{source_project_id}/logs/{test_log_id}"' \
       --bucket={bucket_id} \
       --location={region} \
       --view=_AllLogs \
       --project={central_project_id}
   

---

セットアップ手順：読み取り時の集約（ログスコープ）

ログデータのクエリに使用する Google Cloud プロジェクトを作成するか、選択します。これがスコーププロジェクトです。次の手順でログスコープを設定します。ログスコープを使用すると、複数のプロジェクトに保存されたログデータをクエリできます。

1. カスタムログビューを作成する（任意ですが推奨）（Tier M）

アクセスできるログを制限するため、ソースプロジェクトにログビューを作成します。

重要

注意点： ログビューのフィルタに含められるのは、特定の制限のみです。 https://docs.cloud.google.com/logging/docs/logs-views.md.txt#view-filter を参照してください。

gcloud logging views create {view_id} \
    --bucket={bucket_id} \
    --location={region} \
    --project={source_project_id} \
    --log-filter='LOG_ID("{log_id}")'

• {bucket_id}：例：_Default
• {region}：例：global
• {view_id}：例：app-logs-view
• ログバケット内のすべてのログへのアクセスを許可する場合は、--log-filter フラグを省略します。

2. スコーププロジェクトにログスコープを作成する（Tier M）

ソースリソース（プロジェクトまたは特定のログビュー）を一覧にしたログスコープを、スコーププロジェクトに作成します。

gcloud logging scopes create {log_scope_id} \
    --project={scoping_project_id} \
    --resource-names={resource_names}

• {log_scope_id}：例：central-query-scope
• {resource_names}：ログビューのカンマ区切りリストです。例： projects/source-project-1/locations/global/buckets/_Default/views/app-logs-view,projects/source-project-2/locations/global/buckets/_Default/views/app-logs-view。 スコープには最大 100 個のビューを含めることができます。

3. デフォルトのオブザーバビリティスコープを更新する（任意）（Tier M）

ログスコープをプロジェクトのデフォルトのオブザーバビリティスコープにリンクし、Logs Explorer でデフォルトで使用されるようにします。

gcloud observability scopes update _Default \
    --project={scoping_project_id} \
    --location=global \
    --log-scope=//logging.googleapis.com/projects/{scoping_project_id}/locations/global/logScopes/{log_scope_id}

4. ユーザーに IAM 権限を付与する（Tier B）

集中ルーティングとは異なり、クエリの実行時にすべてのソースプロジェクトで権限が確認されます。クエリを実行するユーザーには、次の権限が必要です。

• 特定のログビューに付与された roles/logging.viewAccessor（IAM 条件付き）、またはソースプロジェクトに付与された roles/logging.viewer。
• スコーププロジェクトへのアクセス権。

プロジェクト間のログルーティングとシンク権限エラーのトラブルシューティング

集中ロギングを設定した後、中央プロジェクトのバケットにログが表示されない場合：

1. ソースリソースでログルーターのシンクフィルターを確認する

• ログシンクのフィルターが、ルーティングする想定のログに一致していることを確認してください。

  重要

  注意点： logName:abc や logName="projects/{project_id}/logs/abc" のような標準的なフィルター式は、ログシンクで一致しないことがあります。 ログシンクのフィルターで正確に一致させるには、必ず LOG_ID("abc") を使用してください。

• これらのログを誤って破棄する除外フィルターを設定していないことを確認してください。

2. 書き込み元の ID の権限を確認して付与する（最も一般的な原因）

ソースプロジェクトにあるログシンクの書き込み元 ID のサービスアカウントには、中央リソースで必要な権限を明示的に付与する必要があります。

• ステップ A：書き込み元の ID を取得する

  gcloud logging sinks describe {sink_name} \
      --project={source_project_id} \
      --format="value(writerIdentity)"
  

• ステップ B：中央プロジェクトで権限を付与する（Tier B）

  重要

  セキュリティ上の操作（Tier B）： IAM 権限を付与するとアクセス制御ポリシーが変更されるため、実行前にユーザーの明示的な確認が必要です。

  • Cloud Logging バケットの場合（標準）： roles/logging.bucketWriter を付与します。

    gcloud projects add-iam-policy-binding {central_project_id} \
        --member={writer_identity} \
        --role=roles/logging.bucketWriter
    

  • GCS バケットの場合： GCS バケットで roles/storage.objectCreator を付与します。

  • Pub/Sub トピックの場合： Pub/Sub トピックで roles/pubsub.publisher を付与します。

  • BigQuery データセットの場合： BigQuery データセットで roles/bigquery.dataEditor を付与します。

---

参考資料と関連リンク

• GCP Cloud Logging - ルーティングとストレージの概要
• GCP Cloud Logging - ログスコープ
• GCP Cloud Logging - カスタムログビュー