assured-workloads-basics

Google Cloud Assured Workloads 基础知识（V1 GA）

使用 gcloud 和 Google Cloud Python 客户端库（google-cloud-assured-workloads 和 google-api-python-client）验证前置条件、创建符合 Assured Workloads V1 要求的文件夹、将合规服务加入许可名单，并列出、检查、更新或删除现有工作负载。

使用情况归属

使用此技能执行命令时，所有 gcloud CLI、REST API 和 MCP 归属要求均请遵循使用情况归属中的说明。

强制防护措施

1. **不得捏造：**切勿虚构组织 ID、结算账号 ID、文件夹 ID、项目 ID、工作负载 ID 或合规制度枚举值。运行命令前，请使用 scripts/validate_params.py 验证参数。
2. **区域 / 多区域位置与 CLI 界面：**Assured Workloads V1 不支持 --location=global；请始终使用与合规制度兼容的区域或多区域位置（请参阅 references/regimes.md）。切勿使用 gcloud compliance-manager 命令管理 Assured Workloads V1 工作负载。
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 和应用默认凭据（执行 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 服务 Agent（service-{org_number}@gcp-sa-assuredworkloads.iam.gserviceaccount.com）：roles/assuredworkloads.serviceAgent。

工作流 1：创建 Assured Workloads 工作负载（两阶段配置）

阶段 1：验证参数并创建工作负载（gcloud assured workloads create）

1. 选择监管制度和位置： 查看 references/regimes.md，了解全部 45 个 V1 --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）。用户请求免费层级边界时，不要将 --compliance-regime 设为付费主权支持制度（US_REGIONS_AND_US_SUPPORT、US_DATA_BOUNDARY_AND_SUPPORT、FEDRAMP_MODERATE），也绝不要编造不存在的枚举值，例如 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）。
     • 在 CLI 中使用 --partner-permissions=data-logs-viewer=true（或 data-logs-viewer=false）配置合作伙伴权限。

阶段 2（可选）：将合规服务加入允许列表／启用 BigQuery（google-cloud-assured-workloads）

• 需要时： 对于 FEDRAMP_MODERATE 和 DATA_BOUNDARY_FOR_FEDRAMP_MODERATE，创建时会自动启用 BigQuery（跳过阶段 2）。对于所有其他制度（例如 FEDRAMP_HIGH），在后台配置流程完成期间，文件夹的 constraints/gcp.restrictServiceUsage 组织政策会先阻止 BigQuery（通常在创建后 5–10 分钟完成）。
• 绝不要手动绕过组织政策： 不要手动覆盖或删除文件夹上的 constraints/gcp.restrictServiceUsage，以绕过 Assured Workloads 合规控制。
• 以编程方式加入允许列表（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）

通过 scripts/validate_params.py 验证后，list 和 describe 只读操作无需用户确认。

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 注意事项： 文件夹删除状态（DELETE_REQUESTED）可能需要短暂的传播时间（15–60 秒），Assured Workloads 才会识别到文件夹已删除。如果删除文件夹后 ERROR_CODE_WORKLOAD_NOT_EMPTY 暂时仍然存在，请等待 15–20 秒，然后在不使用过时 --etag 的情况下重试 gcloud assured workloads delete（因为删除底层资源会改变工作负载的并发令牌）。

工作流 4：更新 Assured Workloads 工作负载（UpdateWorkload 和合规性更新）

4A. 更新工作负载元数据和通知（gcloud assured workloads update）

• 可更新字段（至少需要一个）：
  • --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 没有内置 CLI 子命令来列出或应用 updates 子资源中的合规态势更新（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（每项约束对应一项更新）： 每条 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. 而失败时，不要盲目重试。请检查同一组织和位置中的失败长时间运行操作（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 定价、应用工作负载更新、合作伙伴主权控制概览、合作伙伴主权控制位置。