Workload Manager Basics
Workload Manager validates enterprise workloads against Google Cloud best
practices and recommendations. The public client libraries are centered on
evaluations: define a resource scope, choose built-in or custom rules, run an
evaluation, then inspect results and scanned resources.
Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you
MUST read Usage Attribution. For commands executed
directly in the terminal (never in generated scripts, Terraform, or user code),
prefix gcloud with
CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:workload-manager-basics)"
and append agent-skills/1.0 (skill:workload-manager-basics) to User-Agent headers.
Use This Flow
flowchart LR
Rules["List rules"] --> Eval["Create or update evaluation"]
Resources["Project, folder, or org scope"] --> Eval
Eval --> Run["Run evaluation"]
Run --> Results["Inspect evaluation results"]
Results --> Remediate["Remediate findings"]
Results --> Export["Optional BigQuery export"]
Core API Constraints
To ensure compatibility, security, and successful integration:
- Public Surface Only: You MUST strictly interact with Workload Manager
using the official public
google-cloud-workloadmanager client library or
the public REST API (workloadmanager.googleapis.com/v1).
- No Internal or Undocumented APIs: Do NOT attempt to use internal RPC
protocols, private service backends, or undocumented discovery mechanisms.
They are not supported for public integrations and will fail.
- No Service-Specific CLI: There is no public
gcloud workload-manager
CLI command group. Use gcloud only for authentication, IAM role
assignment, and fetching raw REST tokens.
- Sandbox Execution Robustness (Auth/Mock Fallbacks): When gcloud
authentication or Workload Manager API calls fail in sandboxed or restricted
environments (e.g., due to Context Aware Access token blocks, missing API
enablement, or
mock resources returning 404/403), immediately fall back to presenting
example code and static findings from your references instead of entering
retry loops. Present the correct client library code structure or REST API
payload example, clearly explain the auth or resource limitation, and list
typical rules or mock findings statically to satisfy the request.
Prerequisites
Enable the Workload Manager API:
gcloud services enable workloadmanager.googleapis.com --quiet
Authenticate locally using Application Default Credentials (ADC) before
using client libraries:
gcloud auth application-default login
Ensure the Workload Manager service agent has the required roles granted in
your project (mandatory for API/client library usage, see
IAM & Security).
Grant the least-privileged role needed for the task. Start with
roles/workloadmanager.viewer for read-only access to evaluation resources
and use roles/workloadmanager.evaluationAdmin or
roles/workloadmanager.admin only when creating, updating, running, or
deleting evaluations.
Quick Client Library Example
Use the Python client library for the first working automation path:
python3 -m pip install --upgrade google-cloud-workloadmanager
from google.cloud import workloadmanager_v1
project_id = "PROJECT_ID"
location = "LOCATION"
parent = f"projects/{project_id}/locations/{location}"
client = workloadmanager_v1.WorkloadManagerClient()
rules = client.list_rules(
request=workloadmanager_v1.ListRulesRequest(
parent=parent,
evaluation_type=workloadmanager_v1.Evaluation.EvaluationType.OTHER,
)
)
for rule in rules.rules:
print(rule.name, rule.display_name, rule.severity)
Reference Directory
Core Concepts: Evaluations, rules, results,
scanned resources, supported workload types, and API shape.
General Best Practices: Google Cloud
general best-practice posture checks, OTHER evaluation guidance, custom
Rego rules, and scale/automation patterns.
Client Libraries: Python and Go client
library examples for listing rules, creating evaluations, running
evaluations, and reading findings.
REST Usage: Direct REST examples for the public
Workload Manager API and operations polling.
Public CLI Status: No documented
service-specific gcloud workload-manager command group; use gcloud only
for auth, IAM, API enablement, and REST tokens.
Public MCP Status: No documented public
Workload Manager MCP server; use client libraries or REST API instead.
Setup Prerequisites: Terraform examples
only for adjacent prerequisites such as API enablement, IAM, BigQuery export
datasets, and KMS keys. This is not Workload Manager resource management.
IAM & Security: Workload Manager roles,
least-privilege guidance, service agents, data handling, and CMEK notes.
If product behavior or API fields are not covered here, check the current
Workload Manager product documentation and client library reference before
implementing.
Authoritative References
Additional Context
1---2name: workload-manager-basics-23metadata:4 source: https://skillmd.com/skills/google/workload-manager-basics-25 version: "1.0.1"6 category: CloudObservabilityAndMonitoring7description: >-8 Use this skill to manage Google Cloud Workload Manager evaluations, rules,9 scanned resources, and validation results by using public client libraries10 and the REST API. Use when you need to inspect workload best-practice rules,11 create and run evaluations for Google Cloud general best practices, SAP, SQL12 Server, or custom organizational rules, review violations, export results to13 BigQuery, or automate Workload Manager through client libraries because no14 service-specific public CLI or MCP server is available. Don't use for general15 Google Compute Engine instance management, VPC configuration, or standard IAM16 auditing.17---1819# Workload Manager Basics2021Workload Manager validates enterprise workloads against Google Cloud best22practices and recommendations. The public client libraries are centered on23evaluations: define a resource scope, choose built-in or custom rules, run an24evaluation, then inspect results and scanned resources.2526## Attribution2728**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you29MUST read [Usage Attribution](references/attribution.md). For commands executed30directly in the terminal (never in generated scripts, Terraform, or user code),31prefix `gcloud` with32`CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:workload-manager-basics)"`33and append `agent-skills/1.0 (skill:workload-manager-basics)` to `User-Agent` headers.3435## Use This Flow3637```mermaid38flowchart LR39 Rules["List rules"] --> Eval["Create or update evaluation"]40 Resources["Project, folder, or org scope"] --> Eval41 Eval --> Run["Run evaluation"]42 Run --> Results["Inspect evaluation results"]43 Results --> Remediate["Remediate findings"]44 Results --> Export["Optional BigQuery export"]45```4647## Core API Constraints4849To ensure compatibility, security, and successful integration:5051* **Public Surface Only:** You MUST strictly interact with Workload Manager52 using the official public `google-cloud-workloadmanager` client library or53 the public REST API (`workloadmanager.googleapis.com/v1`).54* **No Internal or Undocumented APIs:** Do NOT attempt to use internal RPC55 protocols, private service backends, or undocumented discovery mechanisms.56 They are not supported for public integrations and will fail.57* **No Service-Specific CLI:** There is no public `gcloud workload-manager`58 CLI command group. Use `gcloud` only for authentication, IAM role59 assignment, and fetching raw REST tokens.60* **Sandbox Execution Robustness (Auth/Mock Fallbacks):** When gcloud61 authentication or Workload Manager API calls fail in sandboxed or restricted62 environments (e.g., due to Context Aware Access token blocks, missing API63 enablement, or64 mock resources returning 404/403), immediately fall back to presenting65 example code and static findings from your references instead of entering66 retry loops. Present the correct client library code structure or REST API67 payload example, clearly explain the auth or resource limitation, and list68 typical rules or mock findings statically to satisfy the request.6970## Prerequisites71721. Enable the Workload Manager API:7374 ```bash75 gcloud services enable workloadmanager.googleapis.com --quiet76 ```77782. Authenticate locally using Application Default Credentials (ADC) before79 using client libraries:8081 ```bash82 gcloud auth application-default login83 ```84853. Ensure the Workload Manager service agent has the required roles granted in86 your project (mandatory for API/client library usage, see87 [IAM & Security](references/iam-security.md)).88894. Grant the least-privileged role needed for the task. Start with90 `roles/workloadmanager.viewer` for read-only access to evaluation resources91 and use `roles/workloadmanager.evaluationAdmin` or92 `roles/workloadmanager.admin` only when creating, updating, running, or93 deleting evaluations.9495## Quick Client Library Example9697Use the Python client library for the first working automation path:9899```bash100python3 -m pip install --upgrade google-cloud-workloadmanager101```102103```python104from google.cloud import workloadmanager_v1105106project_id = "PROJECT_ID"107location = "LOCATION"108parent = f"projects/{project_id}/locations/{location}"109110client = workloadmanager_v1.WorkloadManagerClient()111112rules = client.list_rules(113 request=workloadmanager_v1.ListRulesRequest(114 parent=parent,115 evaluation_type=workloadmanager_v1.Evaluation.EvaluationType.OTHER,116 )117)118119for rule in rules.rules:120 print(rule.name, rule.display_name, rule.severity)121```122123## Reference Directory124125- [Core Concepts](references/core-concepts.md): Evaluations, rules, results,126 scanned resources, supported workload types, and API shape.127128- [General Best Practices](references/general-best-practices.md): Google Cloud129 general best-practice posture checks, `OTHER` evaluation guidance, custom130 Rego rules, and scale/automation patterns.131132- [Client Libraries](references/client-library-usage.md): Python and Go client133 library examples for listing rules, creating evaluations, running134 evaluations, and reading findings.135136- [REST Usage](references/rest-usage.md): Direct REST examples for the public137 Workload Manager API and operations polling.138139- [Public CLI Status](references/public-cli-status.md): No documented140 service-specific `gcloud workload-manager` command group; use `gcloud` only141 for auth, IAM, API enablement, and REST tokens.142143- [Public MCP Status](references/public-mcp-status.md): No documented public144 Workload Manager MCP server; use client libraries or REST API instead.145146- [Setup Prerequisites](references/setup-prerequisites.md): Terraform examples147 only for adjacent prerequisites such as API enablement, IAM, BigQuery export148 datasets, and KMS keys. This is not Workload Manager resource management.149150- [IAM & Security](references/iam-security.md): Workload Manager roles,151 least-privilege guidance, service agents, data handling, and CMEK notes.152153If product behavior or API fields are not covered here, check the current154Workload Manager product documentation and client library reference before155implementing.156157## Authoritative References158159- [Workload Manager overview](https://docs.cloud.google.com/workload-manager/docs/overview)160- [Google Cloud best practices](https://docs.cloud.google.com/workload-manager/docs/reference/best-practices-general)161- [Workload Manager REST API](https://docs.cloud.google.com/workload-manager/docs/reference/rest)162- [About custom rules](https://docs.cloud.google.com/workload-manager/docs/evaluate/custom-rules/about-custom-rules)163- [Write custom rules using Rego](https://docs.cloud.google.com/workload-manager/docs/evaluate/custom-rules/rego-custom-rules)164- [Python package](https://pypi.org/project/google-cloud-workloadmanager/)165- [Workload Manager IAM roles](https://docs.cloud.google.com/iam/docs/roles-permissions/workloadmanager)166- For additional information, use the Developer Knowledge MCP server `search_documents` tool.167168## Additional Context169170- [Mastering cloud posture management with Workload Manager](https://discuss.google.dev/t/mastering-cloud-posture-management-security-reliability-and-finops-with-workload-manager/318258)