huawei-cloud-cce-cluster-management

Huawei Cloud CCE 集群管理

概述

管理 CCE（Cloud Container Engine）集群生命周期，包括创建、删除、休眠、唤醒集群，管理节点池，控制节点调度，以及管理插件。

此技能通过 hcloud (KooCLI) 调用 Huawei Cloud API，并通过 kubectl cce（kubectl-cce 插件）执行 Kubernetes 节点操作（cordon/uncordon/drain/状态）。该插件使用 AK/SK 凭证连接到 CCE API Gateway，无需集群 EIP 或手动配置 kubeconfig。由于已知的 hcloud 元数据解析缺陷，有两项操作（创建集群、创建节点池）会回退到 Python SDK，详见 cce-api-guide.md。

依赖项：此技能需要 kubectl 和 kubectl-cce 插件。请通过 huawei-cloud-kubectl-cce-installer 技能安装。

⛔ 安全限制

危险操作确认机制

此技能对所有危险操作严格执行两步确认机制，以防止意外中断服务或丢失数据。

所有危险操作都需要 confirm=true 参数才能执行。否则，操作会返回预览和确认提示。

需要确认的操作

工具	操作类型	风险级别	描述
huawei_delete_cce_cluster	删除	🔴 严重	删除整个 CCE 集群，且无法撤销
huawei_hibernate_cce_cluster	休眠	🟠 高	停止所有工作负载，暂停控制平面计费
huawei_awake_cce_cluster	唤醒	🟠 高	从休眠状态恢复集群
huawei_resize_cce_nodepool	扩缩容	🟡 中	调整节点池大小，影响容量
huawei_delete_cce_nodepool	删除	🟠 高	删除节点池，影响业务容量
huawei_delete_cce_node	删除	🟠 高	从集群中移除节点，影响调度
huawei_uninstall_cce_addon	卸载	🟠 高	移除插件，可能影响集群功能
huawei_cce_node_cordon	封锁	🟡 中	将节点标记为不可调度，不会再向其分配新 Pod
huawei_cce_node_uncordon	解除封锁	🟡 中	将节点标记为可调度，可能立即向其分配新 Pod
huawei_cce_node_drain	驱逐	🟠 高	封锁节点并驱逐其上的所有 Pod，影响正在运行的工作负载

工作流

步骤 1：预览操作 - 不传入 confirm 参数调用

# Example: Preview cluster deletion
python3 huawei-cloud.py huawei_delete_cce_cluster \
  region=cn-north-4 \
  cluster_id=xxx

返回：操作预览、风险警告和确认示例

步骤 2：确认执行 - 使用 confirm=true 调用

# Example: Confirm and execute deletion
python3 huawei-cloud.py huawei_delete_cce_cluster \
  region=cn-north-4 \
  cluster_id=xxx \
  confirm=true

凭证安全

✅ 此技能严格遵循以下安全规则：

1. 不持久化存储凭证 - 绝不会将 AK/SK、令牌或证书保存到磁盘
2. 不使用长期内存缓存 - AK/SK 仅在 API 调用期间存在，调用后立即释放
3. 仅缓存项目 ID - 非敏感的项目 ID 缓存在进程内存中
4. 不泄露凭证 - 绝不会在日志、响应或错误中包含 AK/SK
5. 清理临时文件 - 临时 kubeconfig 文件在使用后立即删除
6. 优先通过配置传递凭证 - 如果 hcloud CLI 配置中已包含凭证，则不会将 AK/SK 作为 CLI 参数传递（避免通过 ps aux 泄露）。仅当父进程环境中尚未设置环境变量时，才会为子进程设置这些变量。

凭证从参数或环境变量中解析（仅在进程级使用，绝不会写入磁盘）：

• 永久凭证：HW_ACCESS_KEY + HW_SECRET_KEY
• 临时凭证（推荐用于 CI/CD / IAM 临时访问密钥）：HW_ACCESS_KEY + HW_SECRET_KEY + HW_SECURITY_TOKEN
• HW_PROJECT_ID 为可选项 — 未提供时，通过 hcloud IAM KeystoneListProjects 自动获取（仅 hcloud API 调用需要；kubectl-cce 节点操作不需要）
• 每次调用的 ak / sk 参数会覆盖环境变量，且仅对该次调用生效

安全加固建议：在父进程环境中设置 HW_ACCESS_KEY / HW_SECRET_KEY（例如，在 ~/.bashrc 或 systemd 环境文件中），这样子进程无需显式传递即可继承这些变量。此技能会检测已存在的环境变量，并跳过将 AK/SK 作为 CLI 参数传递给 hcloud 的步骤，以防止凭证出现在进程列表中（ps aux）。kubectl-cce 直接从进程环境中读取这些环境变量。

# Permanent
export HW_ACCESS_KEY  # your access key ID
export HW_SECRET_KEY  # your secret access key
export HW_REGION_NAME="cn-north-4"

# Temporary (add security token)
export HW_SECURITY_TOKEN  # your security token

节点登录密码安全

创建节点或节点池时，登录凭证按以下四级优先级解析：

1. ssh_key 参数 — SSH 密钥对名称（如可用，优先使用）。不能与密码同时使用。
2. password 参数 — 每次调用时传入的原始节点登录密码（8–26 个字符，且至少包含以下类型中的 3 种：大写字母 / 小写字母 / 数字 / 特殊字符）。
3. CCE_NODE_PASSWORD 环境变量 — 未提供 ssh_key 或 password 时使用。
4. 自动生成的随机密码 — 未提供上述任何内容时，此技能会自动生成强随机密码。

⚠️ 自动生成的密码绝不会在工具响应中返回（既不会出现在 data 中，也不会出现在 message 或日志中）。之后若要访问节点，用户必须通过 CCE 控制台或 ECS API 重置节点密码。成功消息仅会包含提示用户重置密码的说明。

原始密码绝不会直接发送到 CCE API；此技能会在内部使用 SHA-512 加盐加密并进行 base64 编码（参见 cce-cluster-parameters.md）。

---

前置条件

CLI 工具

• hcloud（Huawei Cloud KooCLI 7.2+）— 用于执行所有 Huawei Cloud API 调用。安装：

  curl -sSL https://cn-north-4-hdn-koocli.obs.cn-north-4.myhuaweicloud.com/cli/latest/hcloud_install.sh -o ./hcloud_install.sh && bash ./hcloud_install.sh
  hcloud version   # verify install
  

  kubectl + kubectl-cce 插件 — 节点调度操作（cordon/uncordon/drain/status）需要此插件。通过 huawei-cloud-kubectl-cce-installer 技能安装：

  # Check if already installed
  bash ../huawei-cloud-kubectl-cce-installer/scripts/install_kubectl_cce.sh --check
  
  # Install (after confirming the plan)
  sudo bash ../huawei-cloud-kubectl-cce-installer/scripts/install_kubectl_cce.sh --execute --bin-dir /usr/local/bin
  

  kubectl cce 插件通过 CCE API Gateway 使用 AK/SK 凭证连接 — 无需集群 EIP 或手动配置 kubeconfig。

Python 环境

• Python 3.8+

• 安装 SDK 软件包（保留用于 create-cluster / create-nodepool 回退）和辅助工具：

  pip install huaweicloudsdkcce huaweicloudsdkcore huaweicloudsdkiam passlib pyyaml
  

  passlib 用于 SHA-512 加盐。huaweicloudsdkcce + huaweicloudsdkcore + huaweicloudsdkiam 用于两个 SDK 回退函数（创建集群、创建节点池）以及 IAM 项目 ID 解析。pyyaml 用于解析 hcloud JSON 输出。

环境变量

该技能会在向子进程传递凭据前检测现有环境变量：

• hcloud CLI 调用：如果 HW_ACCESS_KEY/HW_SECRET_KEY 已存在于 os.environ 中，该技能会跳过将 --cli-access-key/--cli-secret-key 作为 CLI 参数传递，以防止凭据暴露在 ps aux 中。
• kubectl-cce 调用：该插件会直接从进程环境中读取 HW_ACCESS_KEY/HW_SECRET_KEY。如果这些变量已设置，子进程会自然继承它们——该技能不会再次设置。

**🔒 安全提示：**在系统或会话级别设置 HW_ACCESS_KEY/HW_SECRET_KEY（例如，在 ~/.bashrc 或 systemd 环境文件中），这样该技能就无需将它们作为显式 CLI 参数传递。这可以消除凭据暴露在进程列表（ps aux）和 Shell 历史记录中的风险。

# Set credentials at session level (the skill detects these and skips
# passing them as explicit CLI arguments to hcloud/kubectl-cce)
export HW_ACCESS_KEY  # your access key ID
export HW_SECRET_KEY  # your secret access key
export HW_REGION_NAME="cn-north-4"
# Optional, for temporary credentials:
export HW_SECURITY_TOKEN  # your security token
# Optional, for node login when ssh_key is not used:
export CCE_NODE_PASSWORD  # your node password (8-26 chars, at least 3 char categories)

IAM 权限策略

确保 IAM 用户拥有所需的最低权限：

权限	描述
cce:cluster:list	列出集群
cce:cluster:get	获取集群详情
cce:cluster:create	创建集群
cce:cluster:delete	删除集群
cce:cluster:update	更新集群（休眠/唤醒/绑定 EIP）
cce:node:list	列出节点
cce:node:get	获取节点详情
cce:node:create	创建节点
cce:node:delete	删除节点
cce:node:update	更新节点（设置禁止调度/取消禁止调度/驱逐）
cce:nodepool:list	列出节点池
cce:nodepool:create	创建节点池
cce:nodepool:delete	删除节点池
cce:nodepool:update	更新节点池（调整大小）
cce:addon:list	列出插件
cce:addon:get	获取插件详情
cce:addon:create	安装插件
cce:addon:update	更新插件
cce:addon:delete	卸载插件

---

参数确认

执行任何命令前，请与用户确认以下参数：

认证参数

参数	环境变量	必填	描述
Access Key ID	HW_ACCESS_KEY	✅	华为云 AK，永久或临时凭据
Secret Access Key	HW_SECRET_KEY	✅	华为云 SK，永久或临时凭据
区域	HW_REGION_NAME	✅	区域，例如 cn-north-4
安全令牌	HW_SECURITY_TOKEN	❌	临时凭据安全令牌，仅限 STS
节点密码	CCE_NODE_PASSWORD	❌	节点登录密码；未设置时自动生成

集群参数

参数	必填	默认值	描述
cluster_name	✅	—	集群名称，建议使用 <env>-<app>-cluster
cluster_type	❌	Turbo	集群类型（Turbo/VirtualMachine）
container_network_type	❌	eni	容器网络类型；Turbo 集群使用 eni
cluster_version	❌	API 最新版本	Kubernetes 版本；省略时自动选择最新版本
vpc_id	✅	—	VPC ID
subnet_id	✅	—	子网 ID
flavor_id	✅	—	节点规格，例如 c7.large.2
confirm	❌	false	危险操作确认标志；删除/休眠/调整大小时必须为 true

节点池参数

参数	必填	默认值	描述
nodepool_name	✅	—	节点池名称，建议使用 <env>-<role>-pool
node_count	❌	2	初始节点数；建议至少为 2，以实现高可用性
min_node_count	❌	—	自动扩缩容最小值
max_node_count	❌	—	自动扩缩容最大值
ssh_key	❌	—	SSH 密钥对名称；优先于密码使用
root_volume_size	❌	40	根磁盘大小（GB）
data_volume_size	❌	100	数据磁盘大小（GB）

其他参数

参数	必填	默认值	描述
duration	❌	30	Kubeconfig 有效期（天），以整数形式传入
eip_id	❌	auto	EIP ID；如果未提供，则自动查找或创建
addon_id	❌	—	Addon ID（UID），查询详情时必填

核心命令

集群查询

工具	功能	参数
huawei_list_cce_clusters	列出区域内的所有 CCE 集群	region
huawei_get_cce_nodes	获取节点详细信息	region、cluster_id
huawei_get_cce_kubeconfig	获取集群 kubeconfig	region、cluster_id、duration

集群管理

工具	功能	风险等级	需要确认
huawei_create_cce_cluster	创建 CCE 集群	🟢 低	否
huawei_delete_cce_cluster	删除 CCE 集群	🔴 严重	是
huawei_hibernate_cce_cluster	休眠集群	🟠 高	是
huawei_awake_cce_cluster	唤醒集群	🟠 高	否
huawei_bind_cce_cluster_eip	绑定集群 EIP（未提供 eip_id 时自动查找或创建）	🟢 低	否
huawei_unbind_cce_cluster_eip	解绑集群 EIP	🟡 中	否

动态绑定 EIP： huawei_bind_cce_cluster_eip 支持动态分配 EIP。如果未提供 eip_id，该技能会自动：（1）列出现有 EIP 并查找未绑定的 EIP（status=DOWN）；（2）如果没有可用 EIP，则创建新的 EIP（按流量计费，5Mbps，PER 共享类型）；（3）将其绑定到集群。响应中包含 eip_created（true/false）、eip_id、eip_address 和 public_endpoint（External API URL）。

推荐默认值：

• 集群类型：Turbo（使用 ENI 网络时性能最佳）
• 容器网络：Turbo 集群使用 eni（此技能的默认值）
• 集群版本：省略 cluster_version，让 API 选择最新支持的版本；仅在用户要求特定 Kubernetes 版本时指定
• 命名格式：<env>-<app>-cluster（例如，prod-web-cluster）

节点池管理

工具	功能	风险等级	需要确认
huawei_list_cce_nodepools	列出节点池	🟢 低	否
huawei_create_cce_nodepool	创建节点池	🟢 低	否
huawei_delete_cce_nodepool	删除节点池	🟠 高	是
huawei_resize_cce_nodepool	调整节点池大小	🟡 中	是

推荐默认值：

• 命名格式：<env>-<role>-pool（例如，prod-worker-pool）
• 初始节点数：高可用场景设为 2，或启用自动扩缩容时设为 0
• 启用自动扩缩容以实现动态扩缩
• 对于 Turbo 集群，使用兼容 ENI 的规格（例如，c7.large.2）

节点管理

工具	功能	风险级别	需要确认
huawei_list_cce_nodes	列出集群节点	🟢 低	否
huawei_create_cce_node	直接创建节点	🟢 低	否
huawei_delete_cce_node	删除节点	🟠 高	是
huawei_cce_node_cordon	将节点标记为不可调度	🟡 中	是
huawei_cce_node_uncordon	将节点标记为可调度	🟡 中	是
huawei_cce_node_drain	封锁节点 + 驱逐节点上的所有 Pod	🟠 高	是
huawei_cce_node_status	查询节点调度状态	🟢 低	否

节点 ID 注意事项： huawei_delete_cce_node 需要节点的 UID（通过 huawei_list_cce_nodes → metadata.uid 获取），而不是节点名称。使用名称而非 UID 会返回错误。

节点调度操作（cordon、uncordon、drain、status）通过 kubectl cce 执行——kubectl-cce 插件使用 AK/SK 凭据连接 CCE API Gateway。无需集群 EIP 或手动配置 kubeconfig。该插件原生处理 cordon、驱逐、PodDisruptionBudget（PDB）合规性以及跳过 DaemonSet Pod。

huawei_cce_node_drain 遵循标准 drain 语义：首先封锁节点，然后通过 k8s Eviction API 驱逐节点上的所有 Pod（DaemonSet Pod 除外），并遵循 PodDisruptionBudget（PDB）的限制。受 PDB 限制而无法驱逐的 Pod 会列在 failed_pods 字段中。

注意： 托管扩缩容优先使用节点池。直接创建节点适用于特殊情况。

插件管理

工具	功能	风险级别	需要确认
huawei_list_cce_addons	列出集群插件	🟢 低	否
huawei_get_cce_addon_detail	获取插件详情	🟢 低	否
huawei_install_cce_addon	安装插件	🟢 低	否
huawei_uninstall_cce_addon	卸载插件	🟠 高	是
huawei_update_cce_addon	更新插件	🟡 中	否

常见插件：

• coredns - DNS 服务
• metrics-server - 监控指标
• everest - 存储驱动

插件注意事项（根据 E2E 验证结果）：

• huawei_get_cce_addon_detail、huawei_uninstall_cce_addon 和 huawei_update_cce_addon 都需要插件的 UID（通过 huawei_list_cce_addons → metadata.uid 获取），而不是插件名称。使用名称而非 UID 会返回错误 CCE.03400001。
• 插件状态位于 status.status 字段中（例如 running、upgrading、abnormal），而不是 spec.status。
• 执行 huawei_update_cce_addon 后，插件可能会进入 upgrading 状态。请等待其恢复到 running 状态后再执行后续操作（例如卸载）。

网络前置条件

工具	功能	参数
huawei_list_vpc	列出 VPC 及其 CIDR 信息	region
huawei_list_vpc_subnets	列出子网及其 AZ 信息	region、vpc_id（可选）
huawei_list_eips	列出 EIP（显示已绑定/未绑定状态）	region
huawei_delete_eip	删除 EIP（释放公网 IP）	region、publicip_id

使用这些工具在创建集群前查找 VPC/子网 ID。

---

支持的区域

区域代码	区域名称
cn-north-4	中国华北-北京 4
cn-north-1	中国华北-北京 1
cn-north-2	中国华北-北京 2
cn-east-3	中国华东-上海 1
cn-south-1	中国华南-广州
cn-south-2	中国华南-广州友好
cn-east-4	中国华东 II
cn-southwest-2	贵阳 1
ap-southeast-1	亚太-香港
ap-southeast-2	亚太-曼谷
ap-southeast-3	亚太-新加坡

---

输出格式

所有工具都会返回 JSON 格式的结果，其中包含：

• status：操作结果（success / error）
• data：特定于操作的响应（集群信息、节点列表、插件详情等）
• message：对结果的易读描述
• warning：危险操作的风险警告（仅预览模式）

验证

详细验证步骤请参阅 verification-method.md。快速检查清单：

1. hcloud version（应为 7.2+）
2. kubectl version --client
3. 验证是否已设置 HW_ACCESS_KEY / HW_SECRET_KEY 环境变量（临时凭证需添加 HW_SECURITY_TOKEN）
4. hcloud CCE ListClusters --cli-region=cn-north-4（连通性测试）
5. 测试危险操作预览（不带 confirm=true 调用）

最佳实践

• 使用环境变量（HW_ACCESS_KEY / HW_SECRET_KEY）存储凭证，避免硬编码；临时凭证需添加 HW_SECURITY_TOKEN
• 确认危险操作前，务必先预览
• 高性能工作负载优先使用 Turbo 集群（container_network_type=eni），这是默认配置
• 除非用户要求特定的 Kubernetes 版本，否则省略 cluster_version
• 在低流量时段调整节点池大小，以尽量减少对业务的影响
• 生产工作负载的节点池至少保留 2 个节点，以确保冗余
• 定期通过 huawei_list_cce_clusters 检查集群健康状况

---

参考资料

文档	描述
task-cluster-management.md	集群生命周期操作
task-nodepool-management.md	节点池操作
task-node-management.md	节点调度操作
iam-policies.md	IAM 权限策略
verification-method.md	验证步骤
troubleshooting.md	故障排除指南
cce-api-guide.md	hcloud 操作参考
cce-cluster-parameters.md	集群/节点池创建参数
cli-installation-guide.md	CLI 安装和配置指南

---

备注

• 确保 AK/SK（临时凭证还需 HW_SECURITY_TOKEN）具有正确的 IAM 权限
• 不同区域可能提供不同的资源
• 所有危险操作都需要确认
• 删除操作不可逆
• 休眠集群会停止所有工作负载，请在非业务时段使用
• 节点排空原生使用 kubectl drain：自动处理 cordon、驱逐、PDB 合规性以及跳过 DaemonSet。请使用 --ignore-daemonsets --delete-emptydir-data 标志。
• 推荐使用 Turbo 集群，以获得 ENI 网络的最佳性能
• 创建集群 / 创建节点池因已知的 hcloud 元数据解析缺陷而使用 Python SDK 回退方案；其他所有操作均使用 hcloud CLI