assured-workloads-basics

Google Cloud Assured Workloads の基本（V1 GA）

前提条件を検証し、Assured Workloads V1 準拠フォルダーを作成し、準拠サービスを許可リストに追加して、gcloud と Google Cloud Python クライアントライブラリ（google-cloud-assured-workloads および google-api-python-client）を使用して既存のワークロードを一覧表示、確認、更新、削除します。

使用状況のアトリビューション

このスキルでコマンドを実行する際の、gcloud CLI、REST API、および MCP のアトリビューション要件については、使用状況のアトリビューションの手順に従ってください。

必須のガードレール

1. 捏造禁止： 組織 ID、請求先アカウント ID、フォルダー ID、プロジェクト ID、ワークロード ID、コンプライアンス体制の enum 値を決して捏造しないでください。コマンドを実行する前に、scripts/validate_params.py でパラメーターを検証してください。
2. リージョン／マルチリージョンのロケーションと CLI の仕様： Assured Workloads V1 は --location=global をサポートしていません。必ずコンプライアンス体制に適合するリージョンまたはマルチリージョンのロケーションを使用してください（references/regimes.md を参照）。Assured Workloads V1 ワークロードに gcloud compliance-manager コマンドを使用しないでください。
3. 変更前のユーザー確認： 読み取り専用の操作（list、describe、scripts/manage_workload_updates.py --action=list）は検証後すぐに実行できますが、変更または破壊を伴うコマンド（create、restrict_allowed_resources.py、update、manage_workload_updates.py --action=apply、delete、folders delete、projects delete）を実行する前に、必ずユーザーから明示的な確認を得てください。
4. テレメトリーのアトリビューションとリージョナルエンドポイント：
   • 直接実行するすべての gcloud コマンドの先頭に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:assured-workloads-basics)" を付けてください（使用状況のアトリビューションを参照）。
   • Python GAPIC クライアントと Discovery クライアントは、リージョナルの ClientOptions(api_endpoint="{location}-assuredworkloads.googleapis.com") で構成してください。

ステップ 0：前提条件と環境のセットアップ

Assured Workloads の操作を実行する前に、次の 5 つの前提条件を確認してください。

1. CLI と Python ライブラリ： Google Cloud SDK（gcloud — Google Cloud SDK のインストールガイドを参照）と Python クライアントライブラリをインストールします。

   pip install "google-cloud-assured-workloads>=1.0,<2" "google-api-python-client>=2.0,<3" "google-auth>=2.0,<3"
   

2. 二重認証（CLI + ADC）： gcloud と Application Default Credentials の両方を認証します（gcloud auth login && gcloud auth application-default login、または gcloud auth activate-service-account --key-file=/path/to/key.json + export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"）。
3. クォータと管理者プロジェクト： gcloud config set project {admin_project_id} および gcloud auth application-default set-quota-project {admin_project_id} を設定します。
4. API の有効化： Assured Workloads API（assuredworkloads.googleapis.com）を有効にします。

   gcloud services enable assuredworkloads.googleapis.com --project={admin_project_id}
   

5. 組織レベルの IAM ロール（organizations/{org_id}）：
   • 呼び出し元： roles/assuredworkloads.admin（または読み取り専用の list／describe には roles/assuredworkloads.reader／roles/assuredworkloads.editor）、roles/resourcemanager.organizationViewer、およびワークロード作成時には --billing-account=billingAccounts/{billing_id} に対する roles/billing.user（パートナーワークロードの場合は、--partner-services-billing-account に対する billing.resourceAssociations.create も必要です）。
   • Assured Workloads サービスエージェント（service-{org_number}@gcp-sa-assuredworkloads.iam.gserviceaccount.com）： roles/assuredworkloads.serviceAgent。

ワークフロー 1：Assured Workloads ワークロードを作成する（二段階プロビジョニング）

フェーズ 1：パラメータを検証してワークロードを作成する（gcloud assured workloads create）

1. レジームとロケーションを選択する： references/regimes.mdで、V1 の 45 個すべての--compliance-regime列挙値と、有効な--location値を確認します。
   • 無料枠のリージョンデータ境界（REGIONAL_DATA_BOUNDARY）： 無料枠のリージョンデータ境界（標準の商用サポートが適用され、主権要員サポートの追加措置を含まない US Data Boundary、EU Data Boundary、Australia/India/UK/Canada/Israel Data Boundary など）は、--compliance-regime=REGIONAL_DATA_BOUNDARY（従来のエイリアス：REGIONAL_CONTROLS）と--location={location}の組み合わせに対応します（JAPAN_DATA_BOUNDARYを使用する日本を除く）。ユーザーが無料枠の境界を求めている場合、有料の主権サポートレジーム（US_REGIONS_AND_US_SUPPORT、US_DATA_BOUNDARY_AND_SUPPORT、FEDRAMP_MODERATE）を--compliance-regimeに設定してはなりません。また、US_DATA_BOUNDARYのような存在しない列挙値を決して作り出してはなりません。
2. 課金アカウントの確認（省略されている場合）： 課金アカウント ID を決して推測してはなりません。省略されている場合は、gcloud billing accounts list --filter="open=true" --format="table(name,displayName)"を実行するか、ユーザーにbillingAccounts/{billing_id}を尋ねます。
3. 検証して作成する： python3 scripts/validate_params.py --operation=create ...で検証し、警告があれば提示します。ユーザーから明示的な確認を得てから、gcloud assured workloads createを実行します。

   gcloud assured workloads create \
     --organization={org_id} --location={location} \
     --display-name="{display_name}" --compliance-regime={compliance_regime} \
     --billing-account=billingAccounts/{billing_id} \
     [--provisioned-resources-parent=folders/{parent_folder_id}] [--enable-sovereign-controls] \
     [--next-rotation-time={next_rotation_time} --rotation-period={rotation_seconds}s] \
     [--resource-settings=consumer-project-id={consumer_project_id},consumer-project-name={consumer_project_name},encryption-keys-project-id={kms_project_id},encryption-keys-project-name={kms_project_name},keyring-id={keyring_id}] \
     [--partner={partner_enum}] [--partner-permissions=data-logs-viewer=true|false] \
     [--partner-services-billing-account=billingAccounts/{partner_billing_id}] \
     [--labels=key1=val1,key2=val2] [--external-identifier={external_id}] --format=json
   

   • CMEK とリソース設定のルール： --next-rotation-time（RFC 3339 タイムスタンプ）と--rotation-period（秒数。例：172800s）は、必ず同時に指定する必要があります。--resource-settings内のencryption-keys-project-id、encryption-keys-project-name、およびkeyring-idを指定する場合は、両方のローテーションフラグが必要です。
   • パートナーによる主権管理（--compliance-regime=ASSURED_WORKLOADS_FOR_PARTNERS）：
     • パートナー管理の主権管理（S3NS、T-Systems、SIA Minsait、PSN、CNTXT、Telefónica）のリクエストは、--compliance-regime=ASSURED_WORKLOADS_FOR_PARTNERSに対応します。
     • --partnerと、サポート対象のパートナーリージョンが必要です。有効な--partner値、サポート対象リージョン、およびパートナーの課金アカウント要件については、references/regimes.mdを参照してください。
     • --partner-permissions=data-logs-viewer=true（またはdata-logs-viewer=false）を使用して、CLI でパートナーの権限を設定します。

フェーズ 2（任意）：準拠サービスを許可リストに登録する／BigQuery を有効にする（google-cloud-assured-workloads）

• 必要となる場合： FEDRAMP_MODERATEおよびDATA_BOUNDARY_FOR_FEDRAMP_MODERATEでは、作成時に BigQuery が自動的に有効になるため、フェーズ 2 を省略します。その他すべてのレジーム（FEDRAMP_HIGHなど）では、バックグラウンドの設定処理が完了するまで、フォルダの組織ポリシーconstraints/gcp.restrictServiceUsageによって BigQuery が初期状態でブロックされます（通常、作成後 5～10 分で完了します）。
• 組織ポリシーを手動で回避しないでください： Assured Workloads のコンプライアンス管理を回避するために、フォルダのconstraints/gcp.restrictServiceUsageを手動で上書きまたは削除してはなりません。
• プログラムによる許可リストへの登録（AssuredWorkloadsServiceClient.restrict_allowed_resources）： バックグラウンド設定が完了し、準拠サービス（BigQuery など）がcompliantButDisallowedServicesに表示されたら、（ユーザーの確認後に）python3 scripts/restrict_allowed_resources.py --organization={org_id} --location={location} --workload-id={workload_id} --restriction-type=ALLOW_COMPLIANT_RESOURCESを実行するか、公式のgoogle-cloud-assured-workloads Python クライアントライブラリを直接呼び出します。

  from google.api_core.client_options import ClientOptions
  from google.cloud import assuredworkloads_v1
  
  client = assuredworkloads_v1.AssuredWorkloadsServiceClient(
      client_options=ClientOptions(
          api_endpoint=f"{location}-assuredworkloads.googleapis.com"
      ),
      transport="rest",
  )
  request = assuredworkloads_v1.RestrictAllowedResourcesRequest(
      name=f"organizations/{org_id}/locations/{location}/workloads/{workload_id}",
      restriction_type=assuredworkloads_v1.RestrictAllowedResourcesRequest.RestrictionType.ALLOW_COMPLIANT_RESOURCES,
  )
  client.restrict_allowed_resources(request=request)
  

  （サポート対象のRestrictionTypeの値：ALLOW_COMPLIANT_RESOURCES、APPEND_COMPLIANT_RESOURCES、またはALLOW_ALL_GCP_RESOURCES。）

ワークフロー 2：Assured Workloads のワークロードを一覧表示・説明する（gcloud）

読み取り専用の list および describe 操作では、scripts/validate_params.py による検証後のユーザー確認は不要です。

1. ワークロードを一覧表示する（ListWorkloads）：

   gcloud assured workloads list --organization={org_id} --location={location} \
     [--filter="{filter_expression}"] [--limit={limit}] [--page-size={page_size}] --format=json
   

2. 特定のワークロードを説明する（GetWorkload）：

   gcloud assured workloads describe {workload_id} --organization={org_id} --location={location} --format=json
   

   （または、リソース名全体 organizations/{org_id}/locations/{location}/workloads/{workload_id} を渡します。）
   • 主な describe 出力フィールド： name、displayName、complianceRegime、partner、resources（プロビジョニングされた CONSUMER_FOLDER フォルダー ID、CONSUMER_PROJECT、ENCRYPTION_KEYS_PROJECT、KEYRING）、etag（update／delete に必要な楽観的同時実行制御トークン）、compliantButDisallowedServices、kajEnrollmentState、saaEnrollmentResponse、violationNotificationsEnabled、labels。

ワークフロー 3：Assured Workloads のワークロードを削除する（DeleteWorkload）

プロビジョニングされた Cloud Resource Manager フォルダー（folders/{folder_id}）または子プロジェクトが残っている間は、Assured Workloads のワークロードを削除できません（FAILED_PRECONDITION: Workload is not empty／ERROR_CODE_WORKLOAD_NOT_EMPTY）。プロビジョニングされたフォルダーとその子プロジェクトを削除する前に、gcloud assured workloads delete を実行しないでください。

1. 調査と検証： gcloud assured workloads describe を実行して、プロビジョニングされたフォルダー（folders/{folder_id}）と子プロジェクト（{project_id}）を特定し、python3 scripts/validate_params.py --operation=delete --workload-id={workload_id} --organization={org_id} --location={location} で検証します。
2. 確認して順序どおりに削除を実行： ユーザーから明示的な確認を得てから、次の順序を厳守して実行します。

   # Step 1: Delete child projects inside the workload folder first
   gcloud projects delete {project_id} --quiet
   
   # Step 2: Delete the provisioned Assured Workloads folder
   gcloud resource-manager folders delete {folder_id}
   
   # Step 3: Delete the Assured Workloads workload after folder deletion propagates
   gcloud assured workloads delete {workload_id} --organization={org_id} --location={location} --quiet
   

   • 反映遅延と --etag に関する注意： Assured Workloads がフォルダーの削除を認識するまで、フォルダーの削除状態（DELETE_REQUESTED）の反映に多少時間がかかる場合があります（15～60 秒）。フォルダーの削除後も ERROR_CODE_WORKLOAD_NOT_EMPTY が一時的に続く場合は、15～20 秒待ってから、古い --etag を指定せずに gcloud assured workloads delete を再試行してください（基盤となるリソースを削除すると、ワークロードの同時実行制御トークンが変わるためです）。

ワークフロー 4：Assured Workloads のワークロードを更新する（UpdateWorkload とコンプライアンスの更新）

4A. ワークロードのメタデータと通知を更新する（gcloud assured workloads update）

• 更新可能なフィールド（少なくとも 1 つ必須）：
  • --display-name="{new_display_name}"：4～30 文字（[a-zA-Z0-9 -]。末尾にスペースを含めることはできません）。
  • --labels=key1=val1,key2=val2：ワークロードのラベルマップを置き換えます（既存のラベルを維持するには、それらも含めてください）。
  • --violation-notifications-enabled=true|false：Essential Contacts（Legal カテゴリ）への組織ポリシーコンプライアンス違反に関するメール通知を有効または無効にします。
  • --etag={etag}：describe／list で取得した現在の同時実行制御トークン。
• 変更不可のフィールド（作成後は変更できません）： complianceRegime、location、billingAccount、partner は変更できません。gcloud assured workloads update では、ワークロードの complianceRegime または location をインプレースで変更できません。コンプライアンス体制を変更するには、新しい Assured Workloads のワークロードを作成する必要があります。
• 検証、確認、実行： python3 scripts/validate_params.py --operation=update ... で検証し、ユーザーから明示的な確認を得てから、次を実行します。

  gcloud assured workloads update {workload_id} --organization={org_id} --location={location} \
    [--display-name="{new_display_name}"] [--labels=key1=val1,key2=val2] \
    [--violation-notifications-enabled=true|false] [--etag={etag}] --format=json
  

4B. コンプライアンス体制の更新を一覧表示して適用する（updates.list と updates.apply）

gcloud assured workloads には、updates サブリソースからコンプライアンス体制の更新を一覧表示したり適用したりする組み込みの CLI サブコマンドはありません（gcloud assured workloads update はワークロードのメタデータのみを更新します）。scripts/manage_workload_updates.py（ユーザーの確認後に --action=list または --action=apply を指定）を使用するか、リージョンの Assured Workloads v1 API（https://{location}-assuredworkloads.googleapis.com）に対して googleapiclient.discovery.build を使用してください。

• AVAILABLE と WITHDRAWN の更新状態：
  • AVAILABLE（制約ごとに 1 件の更新）： 各 AVAILABLE 更新レコードは、個別の組織ポリシー制約の更新（details.orgPolicyUpdate.suggestedPolicy.constraint）に対応します。複数の更新が AVAILABLE の場合、それぞれ異なる制約に対応しているため、個別に（または --update-id=ALL を使用して順番に）適用する必要があります。最新の更新を適用しても、他の制約に関する古い AVAILABLE 更新は適用されません。
  • WITHDRAWN（置き換え済み）： 新しいポリシー更新によって、同じ制約に関する未適用の古い更新が置き換えられると、Assured Workloads は古い更新を WITHDRAWN としてマークします。状態が AVAILABLE のものに絞り込み、WITHDRAWN の更新は決して適用しないでください。
• Python Discovery API のパターン（updates.list、updates.apply、LRO のポーリング）：

  import time
  from google.api_core.client_options import ClientOptions
  from googleapiclient import discovery
  
  service = discovery.build(
      "assuredworkloads",
      "v1",
      client_options=ClientOptions(
          api_endpoint=f"https://{location}-assuredworkloads.googleapis.com"
      ),
  )
  parent = f"organizations/{org_id}/locations/{location}/workloads/{workload_id}"
  
  # 1. List updates and filter for AVAILABLE state
  resp = (
      service.organizations()
      .locations()
      .workloads()
      .updates()
      .list(parent=parent)
      .execute()
  )
  available = [u for u in resp.get("updates", []) if u.get("state") == "AVAILABLE"]
  
  # 2. Apply each AVAILABLE update and poll the returned Long-Running Operation (LRO)
  for update in available:
    op = (
        service.organizations()
        .locations()
        .workloads()
        .updates()
        .apply(name=update["name"], body={})
        .execute()
    )
    while not op.get("done", False):
      time.sleep(3)
      op = (
          service.organizations()
          .locations()
          .operations()
          .get(name=op["name"])
          .execute()
      )
  

一般的なエラー処理とトラブルシューティング（scripts/diagnose_error.py）

決定的な 400 INVALID_ARGUMENT、403 PERMISSION_DENIED、404 NOT_FOUND、または FAILED_PRECONDITION エラーをむやみに再試行しないでください。python3 scripts/diagnose_error.py --error-message="{error_output_text}" を実行して、エラーを Assured Workloads の ErrorInfo.reason 全カタログと照合してください。

Folder creation was unsuccessful. Please try again. のトラブルシューティング（LRO の検査）

gcloud assured workloads create が一般的なメッセージ Folder creation was unsuccessful. Please try again. で失敗した場合、むやみに再試行しないでください。同じ組織とロケーションにおける失敗した Long-Running Operation（LRO）を検査し、具体的な ErrorInfo.reason を取得してください。

gcloud assured operations list --organization={org_id} --location={location} --format=json
gcloud assured operations describe {operation_id} --organization={org_id} --location={location} --format=json

（または、python3 scripts/diagnose_error.py --fetch-latest-lro --organization={org_id} --location={location} を実行してください。）

LRO エラーで確認すべきフォルダー作成の一般的な前提条件：

• 同じ階層に同名のフォルダーが存在する（ERROR_CODE_FOLDER_NAME_UNIQUENESS）： ターゲットの親（organizations/{org_id} または folders/{parent_folder_id}）の直下に、同じ --display-name を持つフォルダーがすでに存在します。一意の --display-name を選ぶか、別の --provisioned-resources-parent を指定してください。
• 既存の Assured Workloads フォルダー内へのネスト（ERROR_CODE_INVALID_PROVISIONED_RESOURCES_PARENT）： Assured Workloads フォルダーは、別の Assured Workloads フォルダー内にネストできません。標準の非ワークロード親フォルダーを指定するか、--provisioned-resources-parent を省略してください。
• フォルダーのクォータまたはネストの深さ制限（ERROR_CODE_FOLDER_CREATION_PRECONDITION_FAILED）： ターゲットの親が、Cloud Resource Manager の直下の子フォルダー 300 個のクォータ、またはフォルダーのネスト深さ 10 階層の上限に達しています。

リファレンスドキュメント

• references/regimes.md： Assured Workloads V1 の全45種類のコンプライアンス体制、最新の DATA_BOUNDARY_FOR_* 列挙値、旧式のエイリアス、パートナーの列挙値、対応するリージョンおよびマルチリージョンのロケーションをまとめた完全な表です。
• Google Cloud 公式ドキュメント： Assured Workloads の概要、対応するロケーションとデータ境界、Assured Workloads の料金、ワークロードの更新を適用する、パートナーによる Sovereign Controls の概要、パートナーによる Sovereign Controls のロケーション。