assured-workloads-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Cloud Assured Workloads Basics (V1 GA)

Google Cloud Assured Workloads 基础操作（V1 GA）

Validate prerequisites, create Assured Workloads V1 compliant folders, allowlist compliant services, and list, inspect, update, or delete existing workloads using

gcloud

and the Google Cloud Python Client Libraries (

google-cloud-assured-workloads

and

google-api-python-client

校验前置条件、创建符合 Assured Workloads V1 要求的文件夹、将合规服务加入允许列表，并使用

gcloud

和 Google Cloud Python 客户端库（

google-cloud-assured-workloads

与

google-api-python-client

）列出、检查、更新或删除已有工作负载。

Usage Attribution

使用归属（Usage Attribution）

For all

gcloud

CLI, REST API, and MCP attribution requirements when executing commands with this skill, follow the instructions in Usage Attribution.

使用本 skill 执行命令时，所有

gcloud

CLI、REST API 和 MCP 归属要求请遵循 Usage Attribution 中的说明。

Mandatory Guardrails

强制性防护规则（Guardrails）

No Fabrication: Never invent Organization IDs, Billing Account IDs, Folder IDs, Project IDs, Workload IDs, or Compliance Regime enums. Validate parameters with
```
scripts/validate_params.py
```
before running commands.
Regional / Multi-Regional Locations & CLI Surface: Assured Workloads V1 does not support
```
--location=global
```
; always use a regional or multi-regional location compatible with the compliance regime (see references/regimes.md). Never use
```
gcloud compliance-manager
```
commands for Assured Workloads V1 workloads.
Human Confirmation Before Mutation: Read-only operations (
```
list
```
,
```
describe
```
, and
```
scripts/manage_workload_updates.py --action=list
```
) can run immediately after validation, but you must obtain explicit user confirmation before executing any mutating or destructive command (
```
create
```
,
```
restrict_allowed_resources.py
```
,
```
update
```
,
```
manage_workload_updates.py --action=apply
```
,
```
delete
```
,
```
folders delete
```
, or
```
projects delete
```
).
Telemetry Attribution & Regional Endpoints:
- Prefix every
```
gcloud
```
  command you execute directly with
```
CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:assured-workloads-basics)"
```
  (see Usage Attribution).
- Configure Python GAPIC and Discovery clients with regional
```
ClientOptions(api_endpoint="{location}-assuredworkloads.googleapis.com")
```
  .

禁止编造： 绝不臆造 Organization ID、Billing Account ID、Folder ID、Project ID、Workload ID 或 Compliance Regime 枚举值。运行命令前必须使用
```
scripts/validate_params.py
```
校验参数。
区域/多区域位置与 CLI 界面： Assured Workloads V1 不支持
```
--location=global
```
；始终使用与合规制度兼容的区域或多区域位置（参见 references/regimes.md）。切勿对 Assured Workloads V1 工作负载使用
```
gcloud compliance-manager
```
命令。
变更操作前需人工确认： 只读操作（
```
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
```
）之前，必须获得用户的明确确认。
遥测归属与区域端点：
- 你直接执行的每条
```
gcloud
```
  命令都必须以
```
CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:assured-workloads-basics)"
```
  作为前缀（参见 Usage Attribution）。
- 配置 Python GAPIC 与 Discovery 客户端时使用区域端点
```
ClientOptions(api_endpoint="{location}-assuredworkloads.googleapis.com")
```
  。

Step 0: Prerequisites & Environment Setup

步骤 0：前置条件与环境准备

Verify these 5 prerequisites before running Assured Workloads operations:

CLI & Python Libraries: Install the Google Cloud SDK (
```
gcloud
```
— see the Google Cloud SDK Installation Guide) and Python client libraries:
bash
```
pip install "google-cloud-assured-workloads>=1.0,<2" "google-api-python-client>=2.0,<3" "google-auth>=2.0,<3"
```

Dual Authentication (CLI + ADC): Authenticate both

gcloud

and Application Default Credentials (

gcloud auth login && gcloud auth application-default login

, or

gcloud auth activate-service-account --key-file=/path/to/key.json

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Quota & Admin Project:

gcloud config set project {admin_project_id}

and

gcloud auth application-default set-quota-project {admin_project_id}

API Enablement: Enable the Assured Workloads API (

assuredworkloads.googleapis.com

bash

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

Organization-Level IAM Roles (
organizations/{org_id}
):

Caller:

roles/assuredworkloads.admin

(or

roles/assuredworkloads.reader

roles/assuredworkloads.editor

for read-only

list

describe

roles/resourcemanager.organizationViewer

, and

roles/billing.user

--billing-account=billingAccounts/{billing_id}

when creating workloads (plus

billing.resourceAssociations.create

--partner-services-billing-account

for partner workloads).

Assured Workloads Service Agent (
service-{org_number}@gcp-sa-assuredworkloads.iam.gserviceaccount.com
):

roles/assuredworkloads.serviceAgent

在执行 Assured Workloads 操作前，验证以下 5 项前置条件：

CLI 与 Python 客户端库： 安装 Google Cloud SDK（
```
gcloud
```
——参见 Google Cloud SDK 安装指南）以及 Python 客户端库：
bash
```
pip install "google-cloud-assured-workloads>=1.0,<2" "google-api-python-client>=2.0,<3" "google-auth>=2.0,<3"
```

双重认证（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"

）。

配额与管理项目：

gcloud config set project {admin_project_id}

和

gcloud auth application-default set-quota-project {admin_project_id}

。

启用 API： 启用 Assured Workloads API（

assuredworkloads.googleapis.com

）：

bash

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

组织级 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 Agent（
service-{org_number}@gcp-sa-assuredworkloads.iam.gserviceaccount.com
）：

roles/assuredworkloads.serviceAgent

。

Workflow 1: Create an Assured Workloads workload (Two-Phase Provisioning)

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

Phase 1: Validate Parameters & Create Workload (

gcloud assured workloads create

)

阶段 1：校验参数并创建工作负载（

gcloud assured workloads create

）

Select Regime & Location: Check references/regimes.md for all 45 V1
```
--compliance-regime
```
enums and valid
```
--location
```
values.
- Free-Tier Regional Data Boundaries (
  REGIONAL_DATA_BOUNDARY
  ): Free-tier regional data boundaries (e.g., US Data Boundary with standard commercial support and without sovereign personnel support uplift, EU Data Boundary, Australia/India/UK/Canada/Israel Data Boundary) map to
```
--compliance-regime=REGIONAL_DATA_BOUNDARY
```
  (legacy alias:
```
REGIONAL_CONTROLS
```
  ) paired with
```
--location={location}
```
  (except Japan, which uses
```
JAPAN_DATA_BOUNDARY
```
  ). Do not set
```
--compliance-regime
```
  to paid sovereign support regimes (
```
US_REGIONS_AND_US_SUPPORT
```
  ,
```
US_DATA_BOUNDARY_AND_SUPPORT
```
  ,
```
FEDRAMP_MODERATE
```
  ) when the user requests the free-tier boundary, and never invent non-existent enums like
```
US_DATA_BOUNDARY
```
  .

Billing Account Discovery (If Omitted): Never guess a billing account ID. If omitted, run

gcloud billing accounts list --filter="open=true" --format="table(name,displayName)"

or ask the user for

billingAccounts/{billing_id}

Validate & Create: Validate with

python3 scripts/validate_params.py --operation=create ...

, surface any warnings, obtain explicit user confirmation, and execute

gcloud assured workloads create

bash

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 & Resource Settings Rules:
```
--next-rotation-time
```
(RFC 3339 timestamp) and
```
--rotation-period
```
(seconds, e.g.
```
172800s
```
) must be specified together.
```
encryption-keys-project-id
```
,
```
encryption-keys-project-name
```
, and
```
keyring-id
```
in
```
--resource-settings
```
require both rotation flags.
Sovereign Controls by Partners (
--compliance-regime=ASSURED_WORKLOADS_FOR_PARTNERS
):
- Requests for partner-managed sovereign controls (S3NS, T-Systems, SIA Minsait, PSN, CNTXT, Telefónica) map to
```
--compliance-regime=ASSURED_WORKLOADS_FOR_PARTNERS
```
  .
- Requires
```
--partner
```
  and a supported partner region (see references/regimes.md for valid
```
--partner
```
  values, supported regions, and partner billing account requirements).
- Configure partner permissions on the CLI with
```
--partner-permissions=data-logs-viewer=true
```
  (or
```
data-logs-viewer=false
```
  ).

选择制度与位置： 查看 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
```
  这类不存在的枚举值。
发现 Billing Account（若未提供）： 绝不猜测 billing account ID。若未提供，运行
```
gcloud billing accounts list --filter="open=true" --format="table(name,displayName)"
```
或向用户询问
```
billingAccounts/{billing_id}
```
。

校验并创建： 使用

python3 scripts/validate_params.py --operation=create ...

进行校验，输出所有警告，获得用户明确确认后执行

gcloud assured workloads create

：

bash

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
```
  取值、支持区域和合作伙伴 billing account 要求见 references/regimes.md）。
- 在 CLI 上通过
```
--partner-permissions=data-logs-viewer=true
```
  （或
```
data-logs-viewer=false
```
  ）配置合作伙伴权限。

Phase 2 (Optional): Allowlist Compliant Services / Enable BigQuery (

google-cloud-assured-workloads

)

阶段 2（可选）：将合规服务加入允许列表 / 启用 BigQuery（

google-cloud-assured-workloads

）

When Required: For
```
FEDRAMP_MODERATE
```
and
```
DATA_BOUNDARY_FOR_FEDRAMP_MODERATE
```
, BigQuery is automatically enabled at creation (skip Phase 2). For all other regimes (such as
```
FEDRAMP_HIGH
```
), BigQuery is initially blocked by the folder's
```
constraints/gcp.restrictServiceUsage
```
organization policy while a background configuration process completes (typically 5–10 minutes after creation).
Never Bypass Org Policies Manually: Do not manually override or delete
```
constraints/gcp.restrictServiceUsage
```
on the folder to bypass Assured Workloads compliance controls.

Programmatic Allowlisting (
AssuredWorkloadsServiceClient.restrict_allowed_resources
): Once background setup completes and compliant services (like BigQuery) appear in

compliantButDisallowedServices

, run

python3 scripts/restrict_allowed_resources.py --organization={org_id} --location={location} --workload-id={workload_id} --restriction-type=ALLOW_COMPLIANT_RESOURCES

(after user confirmation), or call the official

google-cloud-assured-workloads

Python client library directly:

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)

(Supported
RestrictionType
values:
ALLOW_COMPLIANT_RESOURCES
,
APPEND_COMPLIANT_RESOURCES
, or
ALLOW_ALL_GCP_RESOURCES
).

何时需要： 对于
```
FEDRAMP_MODERATE
```
和
```
DATA_BOUNDARY_FOR_FEDRAMP_MODERATE
```
，BigQuery 会在创建时自动启用（跳过阶段 2）。对于其他所有制度（如
```
FEDRAMP_HIGH
```
），在后台配置流程完成之前（通常为创建后 5–10 分钟），BigQuery 会被文件夹的
```
constraints/gcp.restrictServiceUsage
```
组织策略阻止。
切勿手动绕过组织策略： 不要手动覆盖或删除文件夹上的
```
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 客户端库：

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
。）

Workflow 2: List & Describe Assured Workloads workloads (

gcloud

)

工作流 2：列出与描述 Assured Workloads 工作负载（

gcloud

）

Read-only

list

and

describe

operations do not require user confirmation after validating with

scripts/validate_params.py

List Workloads (
ListWorkloads
):

bash

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

Describe a Specific Workload (
GetWorkload
):

bash

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

(Or pass the full resource name
organizations/{org_id}/locations/{location}/workloads/{workload_id}
).

Key
describe
Output Fields:

name

displayName

complianceRegime

partner

resources

(provisioned

CONSUMER_FOLDER

folder ID,

CONSUMER_PROJECT

ENCRYPTION_KEYS_PROJECT

, and

KEYRING

etag

(optimistic concurrency token required for

update

delete

compliantButDisallowedServices

kajEnrollmentState

saaEnrollmentResponse

violationNotificationsEnabled

, and

labels

只读的

list

和

describe

操作在使用

scripts/validate_params.py

校验通过后无需用户确认即可执行。

列出工作负载（
ListWorkloads
）：

bash

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

描述指定工作负载（
GetWorkload
）：

bash

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

。

Workflow 3: Delete an Assured Workloads workload (

DeleteWorkload

)

工作流 3：删除 Assured Workloads 工作负载（

DeleteWorkload

）

An Assured Workloads workload cannot be deleted while its provisioned Cloud Resource Manager folder (

folders/{folder_id}

) or child projects still exist (

FAILED_PRECONDITION: Workload is not empty

ERROR_CODE_WORKLOAD_NOT_EMPTY

). Never run

gcloud assured workloads delete

before deleting the provisioned folder and its child projects.

Inspect & Validate: Run

gcloud assured workloads describe

to identify the provisioned folder (

folders/{folder_id}

) and child projects (

{project_id}

), and validate with

python3 scripts/validate_params.py --operation=delete --workload-id={workload_id} --organization={org_id} --location={location}

Confirm & Execute Ordered Deletion Sequence: Obtain explicit user confirmation, then run in strict bottom-up order:

bash

# 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

Propagation Delay &
--etag
Note: Folder deletion state (
```
DELETE_REQUESTED
```
) can take a brief propagation delay (15–60s) before Assured Workloads recognizes the folder as deleted. If
```
ERROR_CODE_WORKLOAD_NOT_EMPTY
```
transiently persists after deleting the folder, wait 15–20 seconds and retry
```
gcloud assured workloads delete
```
without a stale
```
--etag
```
(as deleting underlying resources changes the workload's concurrency token).

当 Assured Workloads 工作负载已置备的 Cloud Resource Manager 文件夹（

folders/{folder_id}

）或子项目仍然存在时，无法删除该工作负载（

FAILED_PRECONDITION: Workload is not empty

ERROR_CODE_WORKLOAD_NOT_EMPTY

）。在删除已置备文件夹及其子项目之前，切勿运行

gcloud assured workloads delete

。

检查与校验： 运行

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}

进行校验。

确认并按序执行删除流程： 获得用户明确确认后，严格按自底向上的顺序执行：

bash

# 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 秒后重试
```
gcloud assured workloads delete
```
，且不要携带过期的
```
--etag
```
（因为删除底层资源会改变工作负载的并发令牌）。

Workflow 4: Update an Assured Workloads workload (

UpdateWorkload

& Compliance Updates)

工作流 4：更新 Assured Workloads 工作负载（

UpdateWorkload

与合规更新）

4A. Update Workload Metadata & Notifications (

gcloud assured workloads update

)

4A. 更新工作负载元数据与通知（

gcloud assured workloads update

）

Updatable Fields (at least one required):
- ```
--display-name="{new_display_name}"
```
  : 4–30 characters (
```
[a-zA-Z0-9 -]
```
  , no trailing spaces).
- ```
--labels=key1=val1,key2=val2
```
  : Replaces the workload's label map (include existing labels to preserve them).
- ```
--violation-notifications-enabled=true|false
```
  : Enables or disables email notifications for organization policy compliance violations to Essential Contacts (Legal category).
- ```
--etag={etag}
```
  : Current concurrency token from
```
describe
```
  /
```
list
```
  .
Immutable Fields (Cannot Be Modified After Creation):
```
complianceRegime
```
,
```
location
```
,
```
billingAccount
```
, and
```
partner
```
are immutable.
```
gcloud assured workloads update
```
cannot change a workload's
```
complianceRegime
```
or
```
location
```
in-place; changing regimes requires creating a new Assured Workloads workload.

Validate, Confirm, & Execute: Validate with

python3 scripts/validate_params.py --operation=update ...

, obtain explicit user confirmation, and run:

bash

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

可更新字段（至少需提供一个）：
- ```
--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 ...

校验，获得用户明确确认后运行：

bash

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. List & Apply Compliance Posture Updates (

updates.list

updates.apply

)

4B. 列出并应用合规态势更新（

updates.list

与

updates.apply

）

gcloud assured workloads

does not have a built-in CLI subcommand to list or apply compliance posture updates from the

updates

sub-resource (

gcloud assured workloads update

only updates workload metadata). Use

scripts/manage_workload_updates.py

(

--action=list

--action=apply

after user confirmation) or

googleapiclient.discovery.build

against the regional Assured Workloads v1 API (

https://{location}-assuredworkloads.googleapis.com

AVAILABLE
vs.
WITHDRAWN
Update States:
- AVAILABLE
  (One Update Per Constraint): Each
```
AVAILABLE
```
  update record corresponds to an individual organization policy constraint update (
```
details.orgPolicyUpdate.suggestedPolicy.constraint
```
  ). If multiple updates are
```
AVAILABLE
```
  , each corresponds to a different constraint and must be applied individually (or sequentially via
```
--update-id=ALL
```
  )—applying the newest update does not apply older
```
AVAILABLE
```
  updates for other constraints.
- WITHDRAWN
  (Superseded): When a newer policy update supersedes an older unapplied update for the same constraint, Assured Workloads marks the older update
```
WITHDRAWN
```
  . Filter for state
```
AVAILABLE
```
  and never apply
```
WITHDRAWN
```
  updates.

Python Discovery API Pattern (
updates.list
,
updates.apply
, & LRO Polling):

python

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()
    )

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 轮询）：

python

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()
        )

Common Error Handling & Troubleshooting (

scripts/diagnose_error.py

)

常见错误处理与故障排查（

scripts/diagnose_error.py

）

Never blindly retry deterministic

400 INVALID_ARGUMENT

403 PERMISSION_DENIED

404 NOT_FOUND

, or

FAILED_PRECONDITION

errors. Run

python3 scripts/diagnose_error.py --error-message="{error_output_text}"

to match any error against the full Assured Workloads

ErrorInfo.reason

catalog.

对于确定性的

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

目录。

Troubleshooting

Folder creation was unsuccessful. Please try again.

(LRO Inspection)

故障排查

Folder creation was unsuccessful. Please try again.

（LRO 检查）

When

gcloud assured workloads create

fails with the generic message

Folder creation was unsuccessful. Please try again.

, do not blindly retry. Inspect the failed Long-Running Operation (LRO) in the same organization and location to retrieve the specific

ErrorInfo.reason

bash

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

(Or run
python3 scripts/diagnose_error.py --fetch-latest-lro --organization={org_id} --location={location}
).

Common Folder Creation Preconditions to Check in the LRO Error:

Duplicate sibling folder display name (
ERROR_CODE_FOLDER_NAME_UNIQUENESS
): A sibling folder with the same
```
--display-name
```
already exists under the target parent (
```
organizations/{org_id}
```
or
```
folders/{parent_folder_id}
```
). Choose a unique
```
--display-name
```
or a different
```
--provisioned-resources-parent
```
.
Nesting inside an existing Assured Workloads folder (
ERROR_CODE_INVALID_PROVISIONED_RESOURCES_PARENT
): Assured Workloads folders cannot be nested inside another Assured Workloads folder. Specify a standard non-workload parent folder or omit
```
--provisioned-resources-parent
```
.
Folder quota or nesting depth limit (
ERROR_CODE_FOLDER_CREATION_PRECONDITION_FAILED
): The target parent reached the Cloud Resource Manager 300 direct child-folder quota or the 10-level folder nesting depth limit.

当

gcloud assured workloads create

因通用错误信息

Folder creation was unsuccessful. Please try again.

失败时，不要盲目重试。请在同一组织与位置下检查失败的 Long-Running Operation（LRO），以获取具体的

ErrorInfo.reason

：

bash

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 层文件夹嵌套深度上限。

Reference Documentation

参考文档

references/regimes.md: Complete table of all 45 Assured Workloads V1 compliance regimes, modern
```
DATA_BOUNDARY_FOR_*
```
enums, legacy aliases, partner enums, and supported regional/multi-regional locations.
Official Google Cloud Documentation: Assured Workloads Overview, Supported Locations & Data Boundaries, Assured Workloads Pricing, Apply Workload Updates, Sovereign Controls by Partners Overview, Sovereign Controls by Partners Locations.

references/regimes.md： 包含全部 45 个 Assured Workloads V1 合规制度、现代
```
DATA_BOUNDARY_FOR_*
```
枚举值、旧别名、合作伙伴枚举值以及受支持的区域/多区域位置的完整表格。
Google Cloud 官方文档： Assured Workloads 概览、支持的位置与数据边界、Assured Workloads 定价、应用工作负载更新、合作伙伴主权控制概览、合作伙伴主权控制位置。

assured-workloads-basics

Original

Translation

Google Cloud Assured Workloads Basics (V1 GA)

Google Cloud Assured Workloads 基础操作（V1 GA）

Usage Attribution

使用归属（Usage Attribution）

Mandatory Guardrails

强制性防护规则（Guardrails）

Step 0: Prerequisites & Environment Setup

步骤 0：前置条件与环境准备

Workflow 1: Create an Assured Workloads workload (Two-Phase Provisioning)

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

Phase 1: Validate Parameters & Create Workload (
`gcloud assured workloads create`
)

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

Phase 2 (Optional): Allowlist Compliant Services / Enable BigQuery (
`google-cloud-assured-workloads`
)

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

Workflow 2: List & Describe Assured Workloads workloads (
`gcloud`
)

工作流 2：列出与描述 Assured Workloads 工作负载（
`gcloud`
）

Workflow 3: Delete an Assured Workloads workload (
`DeleteWorkload`
)

工作流 3：删除 Assured Workloads 工作负载（
`DeleteWorkload`
）

Workflow 4: Update an Assured Workloads workload (
`UpdateWorkload`
& Compliance Updates)

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

4A. Update Workload Metadata & Notifications (
`gcloud assured workloads update`
)

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

4B. List & Apply Compliance Posture Updates (
`updates.list`
&
`updates.apply`
)

4B. 列出并应用合规态势更新（
`updates.list`
与
`updates.apply`
）

Common Error Handling & Troubleshooting (
`scripts/diagnose_error.py`
)

常见错误处理与故障排查（
`scripts/diagnose_error.py`
）

Troubleshooting
`Folder creation was unsuccessful. Please try again.`
(LRO Inspection)

故障排查
`Folder creation was unsuccessful. Please try again.`
（LRO 检查）

Reference Documentation

参考文档

assured-workloads-basics

Original

Translation

Google Cloud Assured Workloads Basics (V1 GA)

Google Cloud Assured Workloads 基础操作（V1 GA）

Usage Attribution

使用归属（Usage Attribution）

Mandatory Guardrails

强制性防护规则（Guardrails）

Step 0: Prerequisites & Environment Setup

步骤 0：前置条件与环境准备

Workflow 1: Create an Assured Workloads workload (Two-Phase Provisioning)

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

Phase 1: Validate Parameters & Create Workload (gcloud assured workloads create)

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

Phase 2 (Optional): Allowlist Compliant Services / Enable BigQuery (google-cloud-assured-workloads)

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

Workflow 2: List & Describe Assured Workloads workloads (gcloud)

工作流 2：列出与描述 Assured Workloads 工作负载（gcloud）

Workflow 3: Delete an Assured Workloads workload (DeleteWorkload)

工作流 3：删除 Assured Workloads 工作负载（DeleteWorkload）

Workflow 4: Update an Assured Workloads workload (UpdateWorkload & Compliance Updates)

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

4A. Update Workload Metadata & Notifications (gcloud assured workloads update)

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

4B. List & Apply Compliance Posture Updates (updates.list & updates.apply)

4B. 列出并应用合规态势更新（updates.list 与 updates.apply）

Common Error Handling & Troubleshooting (scripts/diagnose_error.py)

常见错误处理与故障排查（scripts/diagnose_error.py）

Troubleshooting Folder creation was unsuccessful. Please try again. (LRO Inspection)

故障排查 Folder creation was unsuccessful. Please try again.（LRO 检查）

Reference Documentation

参考文档

Phase 1: Validate Parameters & Create Workload (
`gcloud assured workloads create`
)

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

Phase 2 (Optional): Allowlist Compliant Services / Enable BigQuery (
`google-cloud-assured-workloads`
)

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

Workflow 2: List & Describe Assured Workloads workloads (
`gcloud`
)

工作流 2：列出与描述 Assured Workloads 工作负载（
`gcloud`
）

Workflow 3: Delete an Assured Workloads workload (
`DeleteWorkload`
)

工作流 3：删除 Assured Workloads 工作负载（
`DeleteWorkload`
）

Workflow 4: Update an Assured Workloads workload (
`UpdateWorkload`
& Compliance Updates)

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

4A. Update Workload Metadata & Notifications (
`gcloud assured workloads update`
)

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

4B. List & Apply Compliance Posture Updates (
`updates.list`
&
`updates.apply`
)

4B. 列出并应用合规态势更新（
`updates.list`
与
`updates.apply`
）

Common Error Handling & Troubleshooting (
`scripts/diagnose_error.py`
)

常见错误处理与故障排查（
`scripts/diagnose_error.py`
）

Troubleshooting
`Folder creation was unsuccessful. Please try again.`
(LRO Inspection)

故障排查
`Folder creation was unsuccessful. Please try again.`
（LRO 检查）