/assured-workloads-basics

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](references/attribution.md).

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](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](references/attribution.md)).
• 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](https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt)) 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](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} \
     --displ