---

name: assured-workloads-basics description: >- Provisions, inspects, updates, and deletes Google Cloud Assured Workloads V1 compliant folders, CMEK settings, Sovereign Controls by Partners, and service usage restrictions. Use when creating, listing, describing, updating, or deleting an Assured Workloads workload for any compliance regime or data boundary (FedRAMP, DoD IL2/IL4/IL5, ITAR, CJIS, Healthcare, Sovereign Controls by Partners, or Regional Data Boundaries). Don't use for brownfield assessments or custom frameworks (use assuredworkloads-environment-assessor or assuredworkloads-frameworks-*), or non-compliant folders. metadata: version: "1.0.0" category: Security

Google Cloud Assured Workloads Basics (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).

Usage Attribution

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

Mandatory Guardrails

1. 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.
2. 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.
3. 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).
4. 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").

Step 0: Prerequisites & Environment Setup

Verify these 5 prerequisites before running Assured Workloads operations:

1. CLI & Python Libraries: Install the Google Cloud SDK (gcloud — see the Google Cloud SDK Installation Guide) and Python client libraries:

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

2. 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").
3. Quota & Admin Project: gcloud config set project {admin_project_id} and gcloud auth application-default set-quota-project {admin_project_id}.
4. API Enablement: Enable the Assured Workloads API (assuredworkloads.googleapis.com):

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

5. 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 on --billing-account=billingAccounts/{billing_id} when creating workloads (plus billing.resourceAssociations.create on --partner-services-billing-account for partner workloads).
   • 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)

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

1. 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.
2. 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}.
3. Validate & Create: Validate with python3 scripts/validate_params.py --operation=create ..., surface any warnings, obtain explicit user confirmation, and execute 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 & 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).

Phase 2 (Optional): Allowlist Compliant Services / Enable 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:

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

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

Read-only list and describe operations do not require user confirmation after validating with scripts/validate_params.py.

1. List Workloads (ListWorkloads):

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

2. Describe a Specific Workload (GetWorkload):

   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.

Workflow 3: Delete an Assured Workloads workload (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.

1. 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}.
2. Confirm & Execute Ordered Deletion Sequence: Obtain explicit user confirmation, then run in strict bottom-up order:

   # 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 workl