huawei-cloud-ucs-policy-governor

Huawei Cloud UCS Policy Governor

概述

此技能使用 hcloud CLI 为 Huawei Cloud UCS（Ubiquitous Cloud Native Service）提供策略治理和合规管理功能，涵盖策略实例生命周期、策略定义、策略执行和合规审计。

架构：hcloud CLI → UCS Service API → PolicyInstance/PolicyDefinition/PolicyJob 资源

相关技能：

• huawei-cloud-ucs-cluster-onboarding-manager - 集群注册、生命周期管理、舰队分组和访问管理

功能：

• 为集群或舰队组创建策略实例
• 更新、查询和删除策略实例
• 列出并查询策略定义（模板）
• 在集群或舰队组上启用和禁用策略
• 通过 ListPolicyJobs/ShowPolicyJob 检查策略执行作业状态
• 审计舰队合规性并查看策略执行结果

典型用例：

• “为我的生产集群创建安全策略实例”
• “为我的舰队组创建合规策略”
• “列出所有可用的策略定义”
• “在集群 ‘prod-backend’ 上启用策略”
• “在舰队组 ‘production-fleet’ 上启用策略”
• “为维护暂时禁用策略”
• “检查策略执行作业状态”
• “审计所有集群的策略执行情况”
• “更新策略实例配置”
• “删除过时的策略实例”
• “应用前查询策略定义详情”

工作流

此技能的工作流如下：

1. 环境检查 — 验证已安装 hcloud CLI，并已配置 AK/SK 凭据（参见 CLI 安装指南）
2. 策略定义查询 — 调用 ListPolicyDefinitions 浏览可用的治理策略模板
3. 策略实例管理 — 根据用户请求选择管理操作：
   • 创建：CreateClusterPolicyInstance 或 CreateClusterGroupPolicyInstance（需要启用策略中心的集群/舰队）
   • 更新：UpdatePolicyInstance（需要用户确认 — 参见参数确认）
   • 查询：ListPolicyInstances / ShowPolicyInstance
   • 删除：DeletePolicyInstance（⚠️ 不可撤销，需要用户确认）
4. 策略中心管理（可选）：
   • 启用：EnableClusterPolicy / EnableClusterGroupPolicy（需要集群/舰队处于 Available 状态）
   • 禁用：DisableClusterPolicy / DisableClusterGroupPolicy（需要用户确认 — 会暂停策略执行）
5. 合规审计 — 调用 ListPolicyJobs / ShowPolicyJob 查看策略执行历史和合规状态
6. 验证 — 确认策略实例状态和执行行为（参见验证）

KooCLI 命令格式标准

所有操作均使用 hcloud UCS <Operation> --<param>=<value> --cli-region=<region> 格式。参数采用 --key=value 形式（而非 JSON 请求体）。参数的详细说明请参见参数参考。

支持的区域（已验证）：

区域	状态	备注
cn-north-4	✅ 可用	主要区域，已验证所有命令
ap-southeast-3	✅ 可用	已在第二轮测试中验证
cn-south-4	❌ 不可用	DNS 解析失败，请勿使用

其他区域可能受支持，但尚未经过验证。请始终先使用 hcloud UCS ListPolicyDefinitions --cli-region=<region> 进行测试。

先决条件

1. hcloud CLI 要求（必须）

• 已安装 hcloud CLI（版本 >= 7.2.2）
• 运行 hcloud version 验证安装
• 首次使用：运行 printf "y\n" | hcloud version 接受隐私声明

2. 凭证配置

hcloud CLI 支持通过环境变量配置两种凭证模式，并会在运行时自动检测：

模式 A — 长期 AK/SK（永久访问）：

export HUAWEI_CLOUD_AK=<your-ak>
export HUAWEI_CLOUD_SK=<your-sk>
export HUAWEI_CLOUD_REGION=cn-north-4

模式 B — 临时 AK/SK + SecurityToken（推荐用于临时访问或委派访问）：

export HUAWEI_CLOUD_AK=<your-temp-ak>
export HUAWEI_CLOUD_SK=<your-temp-sk>
export HUAWEI_CLOUD_SECURITY_TOKEN=<your-security-token>
export HUAWEI_CLOUD_REGION=cn-north-4

存在 HUAWEI_CLOUD_SECURITY_TOKEN 时，hcloud CLI 会自动使用临时凭证进行身份验证。仅设置 AK/SK 时，则使用长期凭证进行身份验证。

• 安全规则：
  • 🚫 切勿在代码、对话或命令中暴露 AK/SK/SecurityToken 值
  • 🚫 切勿使用 echo $HUAWEI_CLOUD_AK 或 echo $HUAWEI_CLOUD_SK 检查凭证
  • ✅ 使用环境变量：HUAWEI_CLOUD_AK、HUAWEI_CLOUD_SK、HUAWEI_CLOUD_REGION、HUAWEI_CLOUD_SECURITY_TOKEN
  • ✅ 云操作优先使用 IAM 用户，而非根账户
  • ✅ 为敏感操作启用 MFA

⚠️ 重要安全提示：

• 切勿将凭证提交到版本控制系统
• 使用具有最低所需权限的 IAM 用户
• 为敏感操作启用 MFA
• 定期轮换 AK/SK

3. IAM 权限要求

API 操作	权限	用途
ucs:clusterPolicyInstance:create	创建策略	创建集群级策略实例
ucs:clusterGroupPolicyInstance:create	创建策略	创建舰队组级策略实例
ucs:policyInstance:update	更新策略	修改策略实例
ucs:policyInstance:get	获取策略	查看策略实例详情
ucs:policyInstance:delete	删除策略	移除策略实例
ucs:policyInstance:list	列出策略	列出所有策略实例
ucs:policyDefinition:list	列出定义	列出可用的策略定义
ucs:policyDefinition:get	获取定义	查看策略定义详情
ucs:clusterPolicy:enable	启用策略	启用集群级策略强制执行
ucs:clusterPolicy:disable	禁用策略	禁用集群级策略强制执行
ucs:clusterGroupPolicy:enable	启用策略	启用舰队组级策略强制执行
ucs:clusterGroupPolicy:disable	禁用策略	禁用舰队组级策略强制执行
ucs:policyJob:list	列出作业	列出策略强制执行作业
ucs:policyJob:get	获取作业	查看策略强制执行作业详情

完整的策略 JSON 请参阅 IAM 权限策略。

权限失败处理：

1. 任何命令因权限错误而失败时，请阅读 references/iam-policies.md
2. 向用户显示所需权限列表和策略 JSON
3. 指导用户在 IAM 控制台中创建自定义策略并授予授权
4. 暂停执行，等待用户确认已授予权限

核心命令

1. 策略实例管理

详细工作流请参阅任务：策略管理。

# Create a cluster-level policy instance
hcloud UCS CreateClusterPolicyInstance --clusterid=<ucs-cluster-id> --constraintTemplateID=<template-id> --enforcementAction=deny --namespaces.1=default --namespaces.2=production --parameters='{"maxReplicas":"3"}' --cli-region=cn-north-4

# Create a fleet group-level policy instance
hcloud UCS CreateClusterGroupPolicyInstance --clustergroupid=<fleet-group-id> --constraintTemplateID=<template-id> --enforcementAction=warn --parameters='{"cpuLimit":"2"}' --cli-region=cn-north-4

# Update a policy instance
hcloud UCS UpdatePolicyInstance --policyinstanceid=<instance-id> --constraintTemplateID=<new-template-id> --enforcementAction=warn --parameters='{"cpuLimit":"4"}' --cli-region=cn-north-4

# Show policy instance details
hcloud UCS ShowPolicyInstance --policyinstanceid=<instance-id> --cli-region=cn-north-4

# Delete a policy instance
hcloud UCS DeletePolicyInstance --policyinstanceid=<instance-id> --cli-region=cn-north-4

# List all policy instances (no filter parameters available)
hcloud UCS ListPolicyInstances --cli-region=cn-north-4

2. 策略定义管理

# List all available policy definitions (no filter parameters available)
hcloud UCS ListPolicyDefinitions --cli-region=cn-north-4

# Show policy definition details
# NOTE: --policydefinitionid requires the metadata.uid (UUID format) from ListPolicyDefinitions,
# NOT the policy definition name. Using a name will return UCS.000000 error.
# Step 1: List policy definitions to get the UID
hcloud UCS ListPolicyDefinitions --cli-region=cn-north-4
# Step 2: Use the metadata.uid value from the list result
hcloud UCS ShowPolicyDefinition --policydefinitionid=<metadata.uid> --cli-region=cn-north-4

3. 策略强制执行（启用/禁用）

# Enable a policy on a cluster
hcloud UCS EnableClusterPolicy --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# Enable a policy on a fleet group
hcloud UCS EnableClusterGroupPolicy --clustergroupid=<fleet-group-id> --cli-region=cn-north-4

# Enable a policy on a cluster with retry
hcloud UCS EnableClusterPolicy --clusterid=<ucs-cluster-id> --retry=true --cli-region=cn-north-4

# Disable a policy on a cluster
hcloud UCS DisableClusterPolicy --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# Disable a policy on a fleet group
hcloud UCS DisableClusterGroupPolicy --clustergroupid=<fleet-group-id> --cli-region=cn-north-4

4. 策略强制执行作业状态

详细工作流请参阅任务：合规性审计。

# List policy enforcement jobs
hcloud UCS ListPolicyJobs --cli-region=cn-north-4

# List policy enforcement jobs filtered by kind
hcloud UCS ListPolicyJobs --kind=EnablePolicy --cli-region=cn-north-4

# Show a specific policy enforcement job
hcloud UCS ShowPolicyJob --jobid=<job-id> --cli-region=cn-north-4

参数确认

操作	CLI 命令	风险等级	需确认事项
DeletePolicyInstance	hcloud UCS DeletePolicyInstance --policyinstanceid=<id>	High	删除策略实例会永久移除强制执行。集群／舰队将不再受此策略管控，从而增加合规风险。建议先禁用。
UpdatePolicyInstance	hcloud UCS UpdatePolicyInstance --policyinstanceid=<id> --enforcementAction=<action>	Medium	修改策略参数会影响强制执行行为。将 enforcementAction 从 warn 改为 deny 会阻止不合规部署。请确认新参数。
DisableClusterPolicy	hcloud UCS DisableClusterPolicy --clusterid=<id>	Medium	禁用集群上的策略会暂停强制执行。现有违规记录会保留，但不会执行新的检查。请在继续前确认。
DisableClusterGroupPolicy	hcloud UCS DisableClusterGroupPolicy --clustergroupid=<id>	Medium	禁用舰队级策略会影响舰队组中所有集群的合规治理。现有违规记录会保留，但不会执行新的检查。请在继续前确认。

参数参考

通用参数

参数	必填／可选	描述	默认值
--cli-region	必填	Huawei Cloud 区域 ID	配置值或 HUAWEI_CLOUD_REGION

策略实例参数

参数	必填	描述	约束
--clusterid	是*	目标 UCS 集群 ID	CreateClusterPolicyInstance 必需
--clustergroupid	是*	目标舰队组 ID	CreateClusterGroupPolicyInstance 必需
--constraintTemplateID	否	约束模板 ID	引用现有约束模板
--enforcementAction	否	强制执行操作	warn 或 deny
--namespaces.[N]	否	目标命名空间数组	数组索引从 1 开始
--parameters	否	策略参数对象	JSON 对象字符串
--policyinstanceid	是	实例 ID（用于获取／更新／删除）	用于 Show／Update／Delete 操作
--retry	否	启用时的重试标记	EnableClusterPolicy／EnableClusterGroupPolicy 的查询参数

*注：集群级操作（CreateClusterPolicyInstance、EnableClusterPolicy、DisableClusterPolicy）需要 --clusterid。舰队组级操作（CreateClusterGroupPolicyInstance、EnableClusterGroupPolicy、DisableClusterGroupPolicy）需要 --clustergroupid。

策略定义参数

参数	必填	描述	约束
--policydefinitionid	是	定义 UID（metadata.uid）	UUID 格式，取自 ListPolicyDefinitions 响应。使用策略名称而非 UID 会返回 UCS.000000 错误

策略作业参数

参数	必填	描述	约束
--jobid	是	策略作业 ID	用于 ShowPolicyJob
--kind	否	作业类型筛选条件	默认值为 EnablePolicy，用于 ListPolicyJobs

输出格式

CreateClusterPolicyInstance / CreateClusterGroupPolicyInstance

[待验证——根据已验证的 ShowClusterList/ListPolicyDefinitions 模式，UCS 响应采用 k8s 风格格式]

UCS API 返回的是 Kubernetes 风格对象，而非扁平 JSON。根据已验证的 ShowClusterList 和 ListPolicyDefinitions 响应，策略实例响应可能采用包含 kind、apiVersion、metadata、spec 和 status 字段的 k8s 风格对象结构，而不是包含 id、constraintTemplateID、enforcementAction 等字段的扁平结构。

关键字段（预期格式，待验证）：

• 实例 UUID：可能位于 metadata.uid（而非扁平的 id）
• 约束模板引用：可能位于 spec.constraintTemplateID
• 强制执行操作：可能位于 spec.enforcementAction（warn 或 deny）
• 状态：可能位于 status.phase（Enabled、Disabled、Pending）

ListPolicyDefinitions

响应示例（已验证）：

{
  "items": [
    {
      "kind": "ConstraintTemplate",
      "apiVersion": "templates.gatekeeper.sh/v1beta1",
      "metadata": {
        "name": "k8srequiredresources",
        "uid": "3b900254-0086-11ee-924e-0255ac1000d3",
        "creationTimestamp": "2023-06-01T14:11:41Z",
        "annotations": {
          "name-chinese": "K8sRequiredResources",
          "tag-chinese": "集群安全策略",
          "description-chinese": "..."
        }
      },
      "spec": {
        "type": "general",
        "officialTag": "ClusterSecurityPolicies",
        "level": "1",
        "targetKind": "Pod",
        "official": true,
        "description": "Requires containers to have defined resources set...",
        "constraintTemplate": {
          "kind": "ConstraintTemplate",
          "apiVersion": "templates.gatekeeper.sh/v1",
          "metadata": { "name": "k8srequiredresources" },
          "spec": {
            "crd": {
              "spec": {
                "names": { "kind": "K8sRequiredResources" },
                "validation": { "openAPIV3Schema": { "properties": {} } }
              }
            },
            "targets": [
              {
                "target": "admission.k8s.gatekeeper.sh",
                "rego": "...",
                "libs": []
              }
            ]
          }
        }
      }
    }
  ]
}

关键字段：

• metadata.name：约束模板名称（在 CreateClusterPolicyInstance 中用作 constraintTemplateID，而非扁平的 id）
• metadata.uid：定义 UUID
• spec.officialTag：策略类别/标签（而非扁平的 category）
• spec.level：严重级别（而非扁平的 severity）
• spec.targetKind：目标资源类型（例如 Pod）
• spec.description：策略描述
• spec.constraintTemplate.spec.crd.spec.validation.openAPIV3Schema.properties：参数定义（而非扁平的 parameters 数组）
• spec.type：策略类型（例如 general）
• spec.official：是否为官方（内置）策略

ListPolicyJobs

响应示例（空结果已验证）：

没有作业时，返回 { "items": [] }（空数组）。有作业时，根据已验证的 UCS 模式，返回 k8s 风格对象：

{
  "items": []
}

[有作业时的响应待验证——可能是包含 kind、apiVersion、metadata、spec 和 status 字段的 k8s 风格对象]

关键字段（预期格式，待验证）：

• 作业 UUID：可能位于 metadata.uid（而非扁平的 jobid）
• 作业类型：可能位于 spec.kind（EnablePolicy 等）
• 作业状态：可能位于 status.phase（Success、Failed、InProgress）

验证

逐步验证方法请参阅验证方法。

常见区域 ID

区域名称	区域 ID
中国北方 - 北京 4	cn-north-4
中国北方 - 北京 1	cn-north-1
中国东部 - 上海 1	cn-east-3
中国东部 - 上海 2	cn-east-2
中国南方 - 广州	cn-south-1
中国南方 - 深圳	cn-south-4
中国西南 - 贵阳 1	cn-southwest-2
亚太地区 - 曼谷	ap-southeast-2
亚太地区 - 新加坡	ap-southeast-1
亚太地区 - 香港	ap-southeast-3
欧洲 - 巴黎	eu-west-0

最佳实践

1. 策略参数：使用 --constraintTemplateID 引用约束模板，而不是 --policy_definition_id
2. 舰队级策略：使用 CreateClusterGroupPolicyInstance 将策略应用于舰队组，以实现一致的强制执行
3. 逐步推出：先使用 EnableClusterPolicy 在预发布集群上启用策略，再使用 EnableClusterGroupPolicy 将策略推广到生产舰队组
4. 合规性监控：使用 ListPolicyJobs 和 ShowPolicyJob 监控强制执行任务状态
5. 强制执行操作：初期推出时选择 warn（报告违规情况但不阻止），之后切换为 deny 以严格强制执行
6. 删除前先禁用：删除前使用 DisableClusterPolicy/DisableClusterGroupPolicy 禁用策略，以避免强制执行突然出现空档
7. 命名空间范围：使用 --namespaces.[N] 将策略强制执行范围限定为特定命名空间

参考文档

文档	说明
UCS Policy API 指南	hcloud UCS 策略 API 参考
IAM 权限策略	所需权限和策略 JSON
验证方法	分步验证
常见问题	故障排查指南
任务：策略管理	策略实例 CRUD 工作流
任务：合规审计	合规与审计工作流
CLI 安装指南	KooCLI 安装和身份验证设置
验收标准	测试检查清单和标准

注意事项

• 删除策略不可逆 — 强制执行配置将被永久删除
• 禁用策略会暂停强制执行 — 策略禁用期间不会检查违规情况
• 舰队组策略适用于所有成员集群 — 应用策略前，请确认组成员关系正确
• 不得硬编码 AK/SK — 只能通过环境变量获取凭据
• hcloud CLI 是唯一受支持的方法 — 所有操作都使用 hcloud UCS <Operation> 格式
• CreatePolicyInstance 分为两个独立操作 — 集群级策略使用 CreateClusterPolicyInstance，舰队组级策略使用 CreateClusterGroupPolicyInstance
• 启用/禁用操作因作用范围而异 — 集群使用 EnableClusterPolicy/DisableClusterPolicy，舰队组使用 EnableClusterGroupPolicy/DisableClusterGroupPolicy
• GetPolicyAssignment 不存在 — 使用 ListPolicyJobs 和 ShowPolicyJob 检查强制执行任务状态
• ListPolicyInstances 和 ListPolicyDefinitions 没有筛选参数 — 仅提供 --cli-region
• ShowPolicyDefinition 需要 UID，而非名称 — --policydefinitionid 参数必须是 ListPolicyDefinitions 响应中的 metadata.uid（UUID 格式）。使用策略定义名称会返回 UCS.000000 错误。务必先调用 ListPolicyDefinitions 获取 UID
• 解析 hcloud JSON 输出 — 默认的 hcloud 输出会将 JSON 与诊断表格混合，导致 json.loads() 失败。以编程方式解析时，请使用 --cli-output=json 获取纯 JSON 输出：

# Default output (mixed format, json.loads() will fail)
hcloud UCS ListPolicyDefinitions --cli-region=cn-north-4

# Pure JSON output (safe for json.loads())
hcloud UCS ListPolicyDefinitions --cli-region=cn-north-4 --cli-output=json

常见问题

详细的故障排查指南请参阅常见问题与解决方案。

快速参考：

问题	症状	快速修复
创建操作错误	创建时作用范围错误	集群使用 CreateClusterPolicyInstance，舰队组使用 CreateClusterGroupPolicyInstance
未找到约束模板	创建失败	使用 ListPolicyDefinitions 查找有效模板 ID
集群未注册	EnableClusterPolicy 失败	使用 huawei-cloud-ucs-cluster-onboarding-manager 注册集群
舰队组为空	策略未在任何位置强制执行	先将集群添加到舰队组
参数名称错误	命令失败（下划线与驼峰命名不匹配）	使用 --policyinstanceid 而不是 --instance_id，使用 --clusterid 而不是 --cluster_id
使用了 GetPolicyAssignment	找不到操作	改用 ListPolicyJobs/ShowPolicyJob
使用了列表筛选参数	行为异常	ListPolicyInstances/ListPolicyDefinitions 没有筛选参数，仅支持 --cli-region