workload-manager-basics

Workload Manager Basics

Workload Manager 会根据 Google Cloud 的最佳实践与建议对企业级工作负载进行校验。其公共客户端库的核心围绕“评估（Evaluations）”展开：定义资源作用域，选择内置或自定义规则，运行评估，随后查看结果与已扫描的资源。

Use This Flow

flowchart LR
    Rules["列出规则"] --> Eval["创建或更新评估"]
    Resources["项目、文件夹或组织作用域"] --> Eval
    Eval --> Run["运行评估"]
    Run --> Results["查看评估结果"]
    Results --> Remediate["修复发现的问题"]
    Results --> Export["可选：导出至 BigQuery"]

Core API Constraints

为了确保兼容性、安全性及顺利集成，请遵循以下核心 API 约束：

• 仅限公共接口： 必须且仅能通过官方公共 google-cloud-workloadmanager 客户端库或公共 REST API（workloadmanager.googleapis.com/v1）与 Workload Manager 进行交互。
• 禁止使用内部或未公开 API： 切勿尝试使用内部 RPC 协议、私有服务后端或未公开的发现机制。这些方式不支持公共集成，且会导致调用失败。
• 无服务专用 CLI： 目前不存在公共的 gcloud workload-manager CLI 命令组。gcloud 仅用于身份认证、IAM 角色分配以及获取原始 REST Token。
• 沙箱执行健壮性（认证/Mock 退避策略）： 当在沙箱或受限环境中出现 gcloud 身份认证或 Workload Manager API 调用失败时（例如因上下文感知访问 Token 拦截、API 未启用或 Mock 资源返回 404/403），应立即退避并展示参考文档中的示例代码与静态结果，而非陷入死循环重试。请展示正确的客户端库代码结构或 REST API Payload 示例，清晰说明认证或资源限制，并静态列出典型规则或 Mock 发现结果以响应请求。

Prerequisites

1. 启用 Workload Manager API：

   gcloud services enable workloadmanager.googleapis.com --quiet
   

2. 在启动客户端库前，先通过应用默认凭据（ADC）完成本地认证：

   gcloud auth application-default login
   

3. 确保项目的 Workload Manager 服务代理已获授所需角色（这是使用 API/客户端库的必要条件，详见 IAM & Security）。

4. 遵循最小权限原则授予任务所需角色。若只需只读访问评估资源，请优先使用 roles/workloadmanager.viewer；仅在需要创建、更新、运行或删除评估时，才使用 roles/workloadmanager.evaluationAdmin 或 roles/workloadmanager.admin。

Quick Client Library Example

以 Python 客户端库为例，开启你的首个自动化路径：

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）、结果、已扫描资源、支持的工作负载类型及 API 结构。

• General Best Practices：Google Cloud 通用最佳实践合规检查、OTHER 评估类型指南、自定义 Rego 规则以及规模化/自动化模式。

• Client Libraries：包含 Python 和 Go 客户端库示例，涵盖列出规则、创建评估、运行评估以及读取发现结果。

• REST Usage：公共 Workload Manager API 的直接 REST 调用示例及 Operations 轮询说明。

• Public CLI Status：目前没有官方公开的 gcloud workload-manager 专用命令组；gcloud 仅用于认证、IAM、API 启用和 REST Token 获取。

• Public MCP Status：目前没有官方公开的 Workload Manager MCP Server；请改用客户端库或 REST API。

• Setup Prerequisites：仅包含周边前置条件的 Terraform 示例（如 API 启用、IAM、BigQuery 导出数据集和 KMS 密钥）。这不属于 Workload Manager 本身的资源管理。

• IAM & Security：Workload Manager 角色、最小权限指南、服务代理、数据处理及 CMEK 注意事项。

如果某些产品行为或 API 字段未在此列出，在动手开发前请先查阅最新的 Workload Manager 产品文档和客户端库参考手册。

Authoritative References

• Workload Manager overview
• Google Cloud best practices
• Workload Manager REST API
• About custom rules
• Write custom rules using Rego
• Python package
• Workload Manager IAM roles
• 如需了解更多信息，可使用 Developer Knowledge MCP Server 的 search_documents 工具。

Additional Context

• Mastering cloud posture management with Workload Manager