huawei-cloud-ucs-cluster-onboarding-manager

华为云 UCS 集群接入管理器

概述

此技能通过 hcloud CLI 提供华为云 UCS（无处不在的云原生服务）的集群接入、生命周期和集群组管理能力。

架构：hcloud CLI → UCS 服务 API → Cluster/ClusterGroup/AccessConfig/KubeConfig 资源

相关技能：

• huawei-cloud-ucs-policy-governor - UCS 策略治理、合规性和审计管理

功能：

• 将自管理集群或 CCE 集群注册到 UCS，以进行统一管理
• 将集群从 UCS 管理中移除（取消注册）
• 查询集群详情、列出受管理的集群
• 更新集群属性和元数据
• 创建、删除、更新和查询用于集群组织的集群组
• 在集群组中添加/移除集群（加入/离开）
• 重试集群激活
• 获取集群访问信息和 kubeconfig 凭证
• 下载用于多集群访问的联邦 kubeconfig
• 检查 UCS 资源配额

典型用例：

• “将我的 CCE 集群注册到 UCS”
• “列出 UCS 管理的所有集群”
• “将集群从 UCS 管理中移除”
• “为生产集群创建一个集群组”
• “获取我的 UCS 管理集群的 kubeconfig”
• “下载用于多集群访问的联邦 kubeconfig”
• “检查我的 UCS 配额使用情况”
• “更新集群元数据”
• “查询集群访问信息”
• “将集群添加到集群组”
• “将集群从集群组中移除”
• “重试集群激活”

前提条件

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. K8s 版本兼容性（关键）

⚠️ UCS 对受支持的 Kubernetes 版本设有最高限制。 使用默认设置创建的 CCE 集群可能会使用超出 UCS 支持范围的版本。注册不受支持的版本将失败，并显示错误 UCS.01030012: Register cce cluster error - cce cluster version not support in UCS service（已验证：截至 2025-07，CCE 默认创建 v1.35，而 UCS 最高支持 v1.34）。务必动态查询受支持的版本——不要硬编码版本号，因为 UCS 会随时间更新其支持范围：

hcloud UCS ListRegisteredClusterVersions --cli-region=cn-north-4

注册前版本检查：

# List unimported CCE clusters to check their versions
hcloud UCS ListManagedClusters --unimported=true --cli-region=cn-north-4

# Or check specific CCE cluster version via CCE API
hcloud CCE ShowCluster --clusterid=<cce-cluster-id> --cli-region=cn-north-4

如果集群的 K8s 版本超出 UCS 支持范围，可以：

• 将 CCE 集群的 K8s 版本降级到 UCS 支持范围内，或
• 等待 UCS 支持更新的版本

4. IAM 权限要求

API 操作	权限	用途
ucs:cluster:create	注册集群	将集群注册到 UCS
ucs:cluster:delete	删除集群	从 UCS 中移除集群
ucs:cluster:get	获取集群	查看集群详情
ucs:cluster:list	列出集群	列出所有受管集群
ucs:cluster:update	更新集群	修改集群属性
ucs:clusterGroup:create	创建组	创建集群组
ucs:clusterGroup:delete	删除组	移除集群组
ucs:clusterGroup:get	获取组	查看集群组详情
ucs:clusterGroup:update	更新组	更新集群组描述
ucs:clusterAccess:get	获取访问信息	获取集群访问信息
ucs:quota:get	获取配额	检查 UCS 资源配额
ucs:kubeconfig:create	创建 kubeconfig	获取集群 kubeconfig
ucs:federationKubeconfig:get	获取联邦信息	下载联邦 kubeconfig

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

权限失败处理：

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

核心命令

1. 集群注册与注销

详细工作流请参见任务：集群注册。

RegisterCluster 使用 Kubernetes API 风格的参数（apiVersion、kind、metadata.、spec.）。

# Register a CCE cluster to UCS (⚠️ paid service: requires user confirmation)
# **Confirm with user before executing** — UCS cluster onboarding is a paid service, costs will be incurred
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=prod-backend-cluster --spec.category=self --spec.provider=huaweicloud --spec.type=turbo --spec.manageType=discrete --spec.country=CN --spec.city=110000 --metadata.uid=<cce-cluster-id> --spec.projectID=<project-id> --spec.region=cn-north-4 --cli-region=cn-north-4

# Register a CCE cluster and assign to fleet group at registration
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=prod-backend-cluster --spec.category=self --spec.provider=huaweicloud --spec.type=turbo --spec.manageType=discrete --spec.country=CN --spec.city=110000 --metadata.uid=<cce-cluster-id> --spec.projectID=<project-id> --spec.region=cn-north-4 --spec.clusterGroupID=<group-id> --cli-region=cn-north-4

# Register a self-managed/attached cluster
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=datacenter-k8s --spec.category=onpremise --spec.provider=self_managed --spec.type=Kubernetes --spec.manageType=discrete --spec.country=CN --spec.city=110000 --metadata.annotations.kubeconfig=<kubeconfig-yaml-content> --cli-region=cn-north-4

# Retry cluster activation (if registration stuck)
hcloud UCS RetryClusterActivation --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# Remove a cluster from UCS (⚠️ destructive: requires user confirmation)
# **Confirm with user before executing** — deregistration is irreversible
hcloud UCS DeleteCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

集群类别（spec.category）：

• self：华为云 CCE（Cloud Container Engine）托管集群
  • UCS 通过内网直接访问 CCE API，无需 proxy-agent
  • 使用 CCE API CreateKubernetesClusterCert 获取 kubeconfig（不要使用 UCS CreateClusterKubeconfig）
  • ShowClusterAccessInfo 返回 UCS.01030011，此类别不支持该操作
  • RetryClusterActivation 返回 UCS.01000011，此类别不支持该操作
  • 注意：CCE 集群的 spec.category 为 Turbo，但 UCS ListManagedClusters 返回 category=self、type=turbo
• onpremise：自管或第三方 Kubernetes 集群
  • 需要部署 proxy-agent，以在集群与 UCS 之间建立隧道
  • 使用 ShowClusterAccessInfo 获取 proxy-agent 配置，然后部署 proxy-agent
  • proxy-agent 运行后，使用 CreateClusterKubeconfig 获取 kubeconfig

kubeconfig 获取决策树（已通过 API 测试验证）：

Need cluster kubeconfig?
├── category=self (CCE cluster)
│   └── CCE CreateKubernetesClusterCert --cluster_id=<cce-cluster-id> --duration=30
│       (CCE API, NOT UCS CreateClusterKubeconfig which returns internal error)
└── category=onpremise (self-managed cluster)
    ├── Step 1: ShowClusterAccessInfo --clusterid=<ucs-cluster-id>
    │   (obtain proxy-agent configuration — only for onpremise, returns UCS.01030011 for CCE)
    ├── Step 2: Deploy proxy-agent in the cluster
    └── Step 3: CreateClusterKubeconfig --clusterid=<ucs-cluster-id>
        (obtain kubeconfig after tunnel established)

集群提供商（spec.provider）：

• huaweicloud：华为云托管 CCE 集群
• self_managed：自管 Kubernetes 集群

管理类型（spec.manageType）：

• grouped：在集群组中管理的集群
• discrete：独立管理的集群

2. 集群查询与生命周期

# Show cluster details
hcloud UCS ShowCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# List managed clusters (with pagination)
hcloud UCS ShowClusterList --limit=20 --offset=0 --cli-region=cn-north-4

# List managed clusters with filters
hcloud UCS ShowClusterList --category=CCE --enablestatus=Available --clustergroupid=<group-id> --cli-region=cn-north-4

# List all managed clusters (with optional unimported flag)
# ⚠️ Prerequisite: ListManagedClusters requires IAM agency delegation configured at account level.
# If not configured, returns UCS.01010005: get IAM agency's token error.
# See references/common-pitfalls.md Pitfall 20 for IAM agency setup instructions.
hcloud UCS ListManagedClusters --cli-region=cn-north-4
hcloud UCS ListManagedClusters --unimported=true --cli-region=cn-north-4

# Update cluster properties (K8s API-style params) (⚠️ modification: requires user confirmation)
# **Confirm with user before executing**
hcloud UCS UpdateCluster --clusterid=<ucs-cluster-id> --apiVersion=v1 --kind=Cluster --spec.city=310000 --spec.country=CN --cli-region=cn-north-4

# Show cluster access information (only for category=onpremise clusters)
hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# Show cluster access information with optional filters (only for category=onpremise clusters)
hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --region=cn-north-4 --vpcendpoint=<vpc-id> --cli-region=cn-north-4

⚠️ ShowClusterAccessInfo 仅适用于 category=onpremise 集群。 对于 category=self（CCE）集群，该接口会返回 UCS.01030011: Cluster category not supported（已验证）。对于 CCE 集群的 kubeconfig，请使用 CCE API CreateKubernetesClusterCert，而不是 UCS CreateClusterKubeconfig。

ShowClusterList 支持的筛选参数：

• --category：按集群类别筛选（self、onpremise）
• --clustergroupid：按舰队组 ID 筛选
• --clusterids：按指定集群 ID 筛选
• --enablestatus：按集群状态筛选（Available、Unavailable）
• --managetype：按管理类型筛选（grouped、discrete）
• --limit：分页限制
• --offset：分页偏移量
• --order：排序顺序（asc、desc）
• --order_by：排序字段

⚠️ ShowClusterList API 不支持 --name 筛选。 要按名称查找集群，请在调用 ShowClusterList 时不使用名称筛选，并在本地根据响应中的 metadata.name 进行匹配。

3. 舰队组管理

详细工作流请参阅任务：舰队管理。

# Create a fleet group
hcloud UCS RegisterClusterGroup --metadata.name=production-fleet --spec.description="All production clusters" --spec.clusterIds.1=<cluster-id-1> --cli-region=cn-north-4

# List all fleet groups
hcloud UCS ListClusterGroup --limit=20 --offset=0 --cli-region=cn-north-4

# Show fleet group details
hcloud UCS ShowClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4

# Update fleet group description (⚠️ modification: requires user confirmation)
# **Confirm with user before executing**
hcloud UCS UpdateClusterGroup --clustergroupid=<group-id> --description="Updated fleet description" --cli-region=cn-north-4

# Add clusters to fleet group (⚠️ modification: requires user confirmation)
# **Confirm with user before executing**
hcloud UCS UpdateClusterGroupAssociatedClusters --clustergroupid=<group-id> --clusterIds.1=<cluster-id-1> --clusterIds.2=<cluster-id-2> --cli-region=cn-north-4

# Add a single cluster to fleet group (join)
hcloud UCS JoinGroup --clusterid=<ucs-cluster-id> --clusterGroupID=<group-id> --cli-region=cn-north-4

# Remove a cluster from fleet group (leave)
hcloud UCS LeaveGroup --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# Delete a fleet group (⚠️ destructive: requires user confirmation)
# **Confirm with user before executing** — deletion removes the group but clusters remain registered
hcloud UCS DeleteClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4

4. Kubeconfig 与访问管理

详细工作流请参阅任务：访问管理。

# Get kubeconfig for a specific cluster (⚠️ only for category=onpremise clusters)
# For category=self (CCE) clusters, use: hcloud CCE CreateKubernetesClusterCert --cluster_id=<cce-id> --duration=30 --cli-region=cn-north-4
hcloud UCS CreateClusterKubeconfig --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# Create cluster configuration
hcloud UCS CreateClusterConf --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# Download federation kubeconfig (for multi-cluster access)
hcloud UCS DownloadFederationKubeconfig --clustergroupid=<group-id> --duration=3600 --cli-region=cn-north-4

DownloadFederationKubeconfig 必需参数：

• --clustergroupid：舰队组 ID（必需的路径参数）
• --duration：令牌有效时长，单位为秒（必需的整数请求体参数）

5. 配额管理

# Show UCS resource quotas (domainid is required - account ID)
hcloud UCS ShowQuota --domainid=<account-id> --cli-region=cn-north-4

参数确认

⚠️ 费用提示：将集群接入 UCS 是一项付费服务。向 UCS 注册集群会产生费用。在执行 RegisterCluster 或其他接入操作前，必须先向用户确认其是否同意承担费用，并获得明确同意后才能继续。

常用参数

参数	必需/可选	说明	默认值
--cli-region	必需	华为云区域 ID	配置值或 HUAWEI_CLOUD_REGION
--clusterid	视上下文而定	UCS 集群 ID	不适用
--clustergroupid	视上下文而定	舰队组 ID	不适用

集群注册参数（K8s API 风格）

参数	必需	说明	约束
--spec.category	是	集群类别	self（CCE）或 onpremise（自管理）
--spec.provider	是	集群提供方	huaweicloud 或 self_managed
--spec.type	是	集群类型	cce、baremetal、Kubernetes 等
--spec.manageType	是	管理类型	grouped 或 discrete
--metadata.uid	仅 CCE	CCE 集群 ID	必须引用现有 CCE 集群
--spec.projectID	仅 CCE	项目 ID	通过 ListManagedClusters 响应获取
--spec.clusterGroupID	否	注册时分配到舰队	有效的舰队组 ID

写操作（需要用户确认）

操作	CLI 命令	风险级别	是否需要确认
RegisterCluster	hcloud UCS RegisterCluster	高	UCS 入驻是一项付费服务；注册后，集群将受到 UCS 策略治理约束。请确认集群名称、类别和付费同意。
DeleteCluster	hcloud UCS DeleteCluster	高	注销后无法撤销；集群将失去所有 UCS 管理能力、策略治理能力和舰队关联。请在继续前确认集群 ID。
UpdateCluster	hcloud UCS UpdateCluster	中	修改集群属性（例如位置、标签）。请在继续前确认这些更改。
RegisterClusterGroup	hcloud UCS RegisterClusterGroup	中	创建新的舰队分组，用于组织集群。请确认分组名称和描述。
DeleteClusterGroup	hcloud UCS DeleteClusterGroup	高	删除舰队分组；集群仍保持注册状态，但会失去分组级治理和联邦访问权限。请在继续前确认分组 ID。
UpdateClusterGroup	hcloud UCS UpdateClusterGroup	中	修改舰队分组描述。请确认新的描述。
JoinGroup	hcloud UCS JoinGroup	中	加入舰队分组会影响集群的治理范围和策略执行。请确认集群 ID 和目标分组 ID。
LeaveGroup	hcloud UCS LeaveGroup	中	离开舰队分组会影响集群的治理范围和策略执行；集群将不再受分组级策略治理。请确认集群 ID。

请参阅参数参考，了解完整的参数表。

输出格式

请参阅输出格式，查看详细的响应格式示例（ShowCluster、ShowClusterList、ShowQuota）。

关键字段摘要：

• ShowCluster：metadata.uid（UUID）、spec.category（onpremise/self）、status.phase（Failed/Available）
• ShowClusterList：items[]（k8s 风格数组）、total（计数）
• ShowQuota：quotas.resources[]，包含 type/quota/used/min/max

验证

请参阅验证方法，了解分步验证说明。

最佳实践

1. 集群命名：通过 --metadata.name 使用能够体现集群用途和环境的描述性名称（例如，prod-app-backend、staging-data-pipeline）
2. 集群分组：按环境（生产／预发布／开发）或业务领域组织集群，以实现统一治理
3. Kubeconfig 安全：安全存储 kubeconfig 文件；切勿将其暴露在公共代码库或 CI 日志中
4. 注销注意事项：从 UCS 中移除集群会禁用该集群的所有策略治理和联邦访问
5. 自管理集群注册：确保自管理集群的 kubeconfig 有效，且集群 API 服务器可访问；通过 --metadata.annotations.kubeconfig 传入
6. 配额监控：注册新集群前检查配额，避免达到上限
7. 联邦 kubeconfig 有效期：根据使用模式，为联邦 kubeconfig 令牌选择合适的 --duration

工作流

该技能的工作流如下：

0. ⚠️ 账单确认（必须） — 执行任何操作前，告知用户可能产生的费用影响，并取得明确同意：
   • UCS 是一项付费服务：向 UCS 注册集群会产生管理费用。注册后，该集群将受到 UCS 策略治理约束。
   • 策略中心费用：在集群上启用策略中心可能会产生额外的治理费用。
   • 请用户确认：“您是否了解费用影响并希望继续？（yes/no）”
   • 仅在用户明确确认后继续。如果用户拒绝，则停止，不执行任何操作。
1. 环境检查 — 确认已安装 hcloud CLI，且已配置 AK/SK 凭证（参见 CLI 安装指南）
2. 版本兼容性检查 — 调用 ListRegisteredClusterVersions 获取 UCS 支持的 K8s 版本列表，并确认目标集群版本在列表中
3. 集群注册 — 根据集群类型选择注册方式：
   • CCE 集群：--spec.category=self --spec.provider=huaweicloud --spec.type=turbo
   • 自管理集群：--spec.category=onpremise --spec.provider=self_managed（需要 kubeconfig）
4. 注册验证 — 调用 ShowCluster 或 ShowClusterList，确认集群状态为 Available
5. 集群管理（可选）：
   • 集群分组：RegisterClusterGroup / JoinGroup / LeaveGroup
   • 访问管理：CCE 集群使用 CreateKubernetesClusterCert，第三方集群使用 ShowClusterAccessInfo + proxy-agent
   • 属性更新：UpdateCluster（需要用户确认）
6. 注销集群（可选）— DeleteCluster（⚠️ 不可逆操作，需要用户确认）

KooCLI 命令格式规范

所有操作均使用 hcloud UCS <Operation> --<param>=<value> --cli-region=<region> 格式。详细示例和参数命名规则请参见 KooCLI 命令格式。

参考文档

文档	描述
UCS 集群接入 API 指南	hcloud UCS API 参考
输出格式	响应格式示例（已验证）
IAM 权限策略	所需权限和策略 JSON
验证方法	分步验证
常见问题	故障排查指南
任务：集群注册	注册和注销工作流
任务：舰队管理	舰队组工作流
任务：访问管理	Kubeconfig 和访问控制工作流
CLI 安装指南	hcloud CLI 安装和配置
参数参考	所有操作的完整参数表
KooCLI 命令格式	命令格式标准和示例
验收标准	技能验收标准和测试清单

注意事项

• K8s 版本兼容性 — UCS 支持的 K8s 版本上限会随时间更新。CCE 默认集群版本可能超过此上限。请使用 hcloud UCS ListRegisteredClusterVersions 查询支持的版本，并在注册前确认集群版本在列表中。
• 集群注销不可逆 — 集群将失去所有 UCS 管理能力
• 自管理集群的 kubeconfig 必须有效 — 无效的 kubeconfig 会导致注册失败；通过 --metadata.annotations.kubeconfig 传入
• 绝不能将 AK/SK 硬编码 — 凭据只能通过环境变量获取
• 仅支持 hcloud CLI — 所有操作均使用 hcloud UCS <Operation> 格式
• 联邦 kubeconfig 需要舰队组 ID 和时长 — --clustergroupid 和 --duration 均为必填项
• RegisterCluster 使用 K8s API 风格的参数 — 不是 --name/--cluster_type 这样的扁平参数；注意：spec.category 使用 self/onpremise（而非 CCE/AttachedCluster），spec.provider 使用 huaweicloud（而非 huawei_cloud），spec.type 使用小写 cce（而非 CCE），spec.city 使用城市代码（如 110000，而非 Beijing 这样的城市名称）
• ShowQuota 需要 domainid — 账户/域 ID 是必填的路径参数

常见问题

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