huawei-cloud-cci-instance-management

华为云 CCI 容器实例生命周期管理

概览

使用 hcloud CLI（KooCLI）管理华为云 CCI（Cloud Container Instance）的完整生命周期。CCI 是一项无服务器容器服务——无需管理集群，只需创建 Namespace、定义 Network，然后直接部署工作负载。

架构：hcloud CLI → CCI OpenAPI → Namespace / Network / Deployment / StatefulSet / Pod / EIPPool / Service / Ingress

约束和规则

安全规则

• 两步确认：所有破坏性操作（删除 Namespace/Network/Deployment/StatefulSet/Pod/EIPPool）都需要用户明确确认——先展示预览命令、资源详情和风险警告；只有在用户确认后才能执行。
• 凭证安全：切勿在对话、命令或输出中泄露 AK/SK 值。只能使用 hcloud configure list 检查凭证状态（仅检查是否存在）。优先使用配置文件模式或环境变量，而非显式传入 AK/SK 参数。

资源约束

• Namespace 必须设置 flavor 注解：每个 Namespace 都必须带有 namespace-kubernetes-io/flavor 注解（值为 general-computing 或 gpu-accelerated）。否则创建会失败。
• limits 必须等于 requests：CCI 强制要求 resources.limits == resources.requests。不匹配会导致“limit and request doesn't equal”错误。将两者设为相同的值（例如 500m/1Gi）。
• 工作负载之前必须先创建 Network：如果 Namespace 中不存在 Network，Pod/Deployment/StatefulSet 创建会失败或一直处于 Pending 状态。始终先创建 Network，再部署工作负载。
• VPC CIDR 限制：VPC 子网 CIDR 不得为 10.247.0.0/16——CCI 将此范围保留给 Service 网络。使用此范围会导致 IP 冲突和工作负载创建失败。
• 删除顺序：Pod → Deployment/StatefulSet → EIPPool → Network → Namespace。删除 Namespace 会级联删除其下的所有资源。

hcloud CLI 约束

• 创建 Network 必须使用 Python 辅助脚本：hcloud CLI 无法传递包含点号的注解键（network.alpha.kubernetes.io/default-security-group）。点号表示法和 --cli-jsonInput 均不可用。请使用 scripts/cci_network_helper.py。
• Namespace 注解使用连字符替换：namespace.kubernetes.io/flavor 之类的键可以使用连字符（namespace-kubernetes-io/flavor），CCI 会自动规范化。此变通方法仅适用于 Namespace，不适用于 Network。
• 始终使用 --help 验证参数：CCI 有数百个参数。在构造任何命令之前，先运行 hcloud CCI <Operation> --help。帮助输出是权威依据。

这些规则的详细说明见安全约束、hcloud CLI 限制和注意事项。

标准工作流

1. Create Namespace (with flavor annotation)
2. Create Network (requires Python helper script for annotation — see hcloud CLI Limitations)
3. Create Deployment / StatefulSet / Pod (run workloads)
4. Query status, view logs
5. (Optional) Create EIPPool for Pod public IP access
6. Cleanup: delete workload → delete Network → delete Namespace

前提条件

1. hcloud CLI 要求（必须满足）

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

2. 凭证配置

hcloud CLI 支持两种凭证模式。完整详情请参阅 references/credential-configuration.md。

快速设置（任选一种）：

# Mode A — Long-term AK/SK
export HUAWEI_CLOUD_AK=<your-ak>
export HUAWEI_CLOUD_SK=<your-sk>
export HUAWEI_CLOUD_REGION=cn-north-4

# Mode B — Temporary 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

• 安全规则：切勿公开 AK/SK/SecurityToken 值。使用 hcloud configure list 仅检查凭证是否存在。

⚠️ 已知限制 — Python 辅助脚本的凭证与 hcloud CLI 相互独立：Python 辅助脚本（scripts/cci_network_helper.py）使用 HW_ACCESS_KEY / HW_SECRET_KEY（以及可选的 HW_SECURITY_TOKEN）环境变量进行身份验证，这些凭证独立于 hcloud CLI 的凭证来源（配置文件或 HUAWEI_CLOUD_AK/HUAWEI_CLOUD_SK）。如果 HW_ACCESS_KEY/HW_SECRET_KEY 中的凭证缺少创建 CCI 网络所需的 IAM 权限，脚本将返回 403 错误。请确保这些变量包含具有足够 CCI 权限的凭证（例如 CCI FullAccess）。hcloud CLI 会继续独立使用自身的凭证来源——运行辅助脚本不会影响后续的 hcloud CLI 命令。

3. 验证检查

hcloud version
hcloud configure list

安全约束

危险操作确认机制

此技能严格要求所有破坏性操作都经过两步确认。

所有破坏性操作都必须在执行前获得用户明确确认。流程如下：

步骤 1：预览 — 显示命令、资源详情和风险警告

步骤 2：确认并执行 — 仅在用户明确确认后执行

需要确认的操作

操作	风险级别	描述
删除 Namespace	🔴 严重	级联删除——删除此 Namespace 下的所有资源（网络、Pod、Deployment 等）
删除网络	🟠 高	断开 Namespace 与 VPC 的连接；运行中的 Pod 将失去网络连接
删除 Deployment	🟠 高	终止工作负载的所有副本
删除 StatefulSet	🟠 高	终止所有副本；PVC 数据可能丢失
删除 Pod	🟠 高	终止容器实例
删除 EIPPool	🟡 中	释放分配给 Pod 的公网 IP

凭证安全

• 切勿在对话、命令或输出中公开 AK/SK/SecurityToken 值
• 切勿要求用户在对话中直接输入 AK/SK/SecurityToken
• 仅使用 hcloud configure list 检查凭证状态（仅检查是否存在，不查看值）
• 优先使用配置文件模式或环境变量，而不是显式传入 AK/SK 参数

命令格式标准

CCI 遵循标准的 hcloud 格式，并采用 Kubernetes 风格的嵌套参数：

hcloud CCI <Operation> --param=value --cli-region=<region> --cli-output=json

CCI 专用参数规则

CCI 参数遵循 Kubernetes API 约定——使用点号表示法的深层嵌套对象：

1. Annotations 使用 {*} 格式：--metadata.annotations.namespace-kubernetes-io/flavor=general-computing
2. Labels 使用 {*} 格式：--metadata.labels.app=my-app
3. Containers 数组（从 1 开始）：--spec.template.spec.containers.1.name=main --spec.template.spec.containers.1.image=nginx
4. Resources 使用 {*} 格式：--spec.template.spec.containers.1.resources.limits.cpu=500m
5. Selector 的 matchLabels 使用 {*} 格式：--spec.selector.matchLabels.app=my-app
6. 命名空间级操作需要 --namespace：所有工作负载操作都必须指定命名空间

⚠️ 严重：构造任何 CCI 命令前，始终运行 hcloud CCI <Operation> --help，以确认准确的参数名称。CCI 有数百个参数；帮助输出是权威依据。

参数格式详情

完整的 CCI 参数格式规则和示例，请参阅 references/parameter-format.md。

场景路由

用户意图	参考文档
创建/查询/删除 Namespace	references/task-namespace-management.md
创建/查询/删除 Network	references/task-network-management.md
创建/查询/更新/删除/扩缩 Deployment	references/task-deployment-management.md
创建/查询/更新/删除 StatefulSet	references/task-statefulset-management.md
创建/查询/删除 Pod	references/task-pod-management.md
创建/查询/删除 EIPPool	references/task-eippool-management.md
查询状态、查看日志和事件	references/task-logs-and-status.md
完整工作流（创建→运行→清理）	references/common-workflows.md
所有 CCI 操作速查	references/cci-operation-catalog.md
故障排查	references/troubleshooting.md
IAM 权限	references/iam-policies.md
验证步骤	references/verification-method.md
正确/错误模式对比	references/acceptance-criteria.md

核心命令

Namespace

# Create namespace (general-computing flavor)
hcloud CCI createCoreV1Namespace \
  --metadata.name=<ns-name> \
  --metadata.annotations.namespace-kubernetes-io/flavor=general-computing \
  --cli-region=<region \
  --cli-output=json

# List namespaces
hcloud CCI listCoreV1Namespace --cli-region=<region> --cli-output=json

# Read namespace details
hcloud CCI readCoreV1Namespace --name=<ns-name> --cli-region=<region> --cli-output=json

# Delete namespace (TWO-STEP CONFIRMATION REQUIRED)
hcloud CCI deleteCoreV1Namespace --name=<ns-name> --cli-region=<region>

Network

⚠️ hcloud CLI 限制：创建 Network 需要使用 Python 辅助脚本，因为 hcloud CLI 无法传递注解键 network.alpha.kubernetes.io/default-security-group（其中的点号会被 hcloud 视为嵌套层级）。由于 hcloud 存在一个错误，注解会显示在 --dryrun 中，但不会在实际请求中传递，因此 --cli-jsonInput 方式也不起作用。请参见下文的 hcloud CLI 限制。

⚠️ 凭证要求：Python 辅助脚本使用环境变量 HW_ACCESS_KEY/HW_SECRET_KEY（以及可选的 HW_SECURITY_TOKEN）进行身份验证。这与 hcloud CLI 的凭证来源相互独立（后者从 HUAWEI_CLOUD_AK/HUAWEI_CLOUD_SK 或其配置文件中读取）。如果 HW_ACCESS_KEY/HW_SECRET_KEY 中的凭证没有创建 CCI Network 的权限，脚本将以 403 错误失败。请确保这些凭证具有足够的 IAM 权限（例如 CCI FullAccess）。脚本运行后，hcloud CLI 命令仍会使用自身的凭证来源，不受影响。

# Step 1: Get VPC subnet details (including neutron_network_id)
hcloud VPC ShowSubnet --vpc_id=<vpc-id> --subnet_id=<subnet-id> --cli-region=<region> --cli-output=json

# Step 2: Create network via Python helper script
python scripts/cci_network_helper.py create \
  --namespace=<ns-name> \
  --name=<network-name> \
  --vpc-id=<vpc-id> \
  --subnet-id=<subnet-id> \
  --network-id=<neutron-network-id> \
  --security-group-id=<sg-id> \
  --region=<region>

# Step 3: Check network status until Active
hcloud CCI readNetworkingCciIoV1beta1NamespacedNetworkStatus \
  --name=<network-name> \
  --namespace=<ns-name> \
  --cli-region=<region> \
  --cli-output=json

# List networks
hcloud CCI listNetworkingCciIoV1beta1NamespacedNetwork \
  --namespace=<ns-name> \
  --cli-region=<region> \
  --cli-output=json

Network 必需的 spec 字段：创建 Network 需要 attachedVPC、subnetID、networkType 和 networkID（neutron 网络 ID）。networkID 字段为必填项，即通过 hcloud VPC ShowSubnet 获取的 neutron 网络 ID。

Network 必需的注解：network.alpha.kubernetes.io/default-security-group（CCI Network 安全组的正确注解键，而非 security-group-id）。必须将此注解设置为安全组 ID。

Deployment

# Create deployment
hcloud CCI createAppsV1NamespacedDeployment \
  --namespace=<ns-name> \
  --metadata.name=<deploy-name> \
  --spec.replicas=1 \
  --spec.selector.matchLabels.app=<deploy-name> \
  --spec.template.metadata.labels.app=<deploy-name> \
  --spec.template.spec.containers.1.name=<container-name> \
  --spec.template.spec.containers.1.image=<image> \
  --spec.template.spec.containers.1.resources.limits.cpu=500m \
  --spec.template.spec.containers.1.resources.limits.memory=1Gi \
  --spec.template.spec.containers.1.resources.requests.cpu=500m \
  --spec.template.spec.containers.1.resources.requests.memory=1Gi \
  --cli-region=<region> \
  --cli-output=json

# Scale deployment
hcloud CCI patchAppsV1NamespacedDeploymentScale \
  --name=<deploy-name> \
  --namespace=<ns-name> \
  --spec.replicas=<new-replicas> \
  --cli-region=<region>

# Read deployment status
hcloud CCI readAppsV1NamespacedDeploymentStatus \
  --name=<deploy-name> \
  --namespace=<ns-name> \
  --cli-region=<region> \
  --cli-output=json

StatefulSet

# Create statefulset
hcloud CCI createAppsV1NamespacedStatefulSet \
  --namespace=<ns-name> \
  --metadata.name=<sts-name> \
  --spec.replicas=1 \
  --spec.selector.matchLabels.app=<sts-name> \
  --spec.template.metadata.labels.app=<sts-name> \
  --spec.template.spec.containers.1.name=<container-name> \
  --spec.template.spec.containers.1.image=<image> \
  --spec.template.spec.containers.1.resources.limits.cpu=500m \
  --spec.template.spec.containers.1.resources.limits.memory=1Gi \
  --cli-region=<region> \
  --cli-output=json

# Read statefulset status
hcloud CCI readAppsV1NamespacedStatefulSetStatus \
  --name=<sts-name> \
  --namespace=<ns-name> \
  --cli-region=<region> \
  --cli-output=json

Pod

# Create pod (single container instance)
hcloud CCI createCoreV1NamespacedPod \
  --namespace=<ns-name> \
  --metadata.name=<pod-name> \
  --spec.containers.1.name=<container-name> \
  --spec.containers.1.image=<image> \
  --spec.containers.1.resources.limits.cpu=500m \
  --spec.containers.1.resources.limits.memory=1Gi \
  --cli-region=<region> \
  --cli-output=json

# Read pod status
hcloud CCI readCoreV1NamespacedPodStatus \
  --name=<pod-name> \
  --namespace=<ns-name> \
  --cli-region=<region> \
  --cli-output=json

# Read pod logs
hcloud CCI readCoreV1NamespacedPodLog \
  --name=<pod-name> \
  --namespace=<ns-name> \
  --container=<container-name> \
  --cli-region=<region>

EIPPool

# Create EIPPool (for pod public IP access — auto-create EIPs)
hcloud CCI createCrdYangtseCniV1NamespacedEIPPool \
  --namespace=<ns-name> \
  --apiVersion=crd.yangtse.cni/v1 \
  --kind=EIPPool \
  --metadata.name=<eippool-name> \
  --spec.amount=1 \
  --spec.eipAttributes.networkType=5_bgp \
  --spec.eipAttributes.ipVersion=4 \
  --spec.eipAttributes.bandwidth.shareType=PER \
  --spec.eipAttributes.bandwidth.size=5 \
  --spec.eipAttributes.bandwidth.chargeMode=bandwidth \
  --spec.eipAttributes.bandwidth.name=<bw-name> \
  --cli-region=<region> \
  --cli-output=json

# Read EIPPool status
hcloud CCI readCrdYangtseCniV1NamespacedEIPPoolStatus \
  --name=<eippool-name> \
  --namespace=<ns-name> \
  --cli-region=<region> \
  --cli-output=json

EIPPool 必需字段：--apiVersion=crd.yangtse.cni/v1 和 --kind=EIPPool 为必填项。spec.eipAttributes.networkType 为必填项（可选值：动态 BGP 使用 5_bgp，专用负载均衡使用 5_gray）。自动创建 EIP 时，spec.eipAttributes.bandwidth.chargeMode 和 name 为必填项。

Pod EIP 绑定：若要将 EIPPool 分配给 Pod，请添加注解 yangtse.io/eippool=<eippool-name>（使用连字符变通写法：--metadata.annotations.yangtse-io/eippool=<eippool-name>）。

VPC/子网前置条件

CCI 工作负载运行在映射到现有 VPC 子网的网络中。创建网络之前，请查询可用的 VPC 和子网，并获取 neutron 网络 ID（创建网络时必需）：

# List VPCs
hcloud VPC ListVpcs --cli-region=<region> --cli-output=json

# List subnets
hcloud VPC ListSubnets --cli-region=<region> --cli-output=json

# Get subnet details (including neutron_network_id — REQUIRED for Network creation)
hcloud VPC ShowSubnet --vpc_id=<vpc-id> --subnet_id=<subnet-id> --cli-region=<region> --cli-output=json

⚠️ VPC 子网 CIDR 限制：VPC 和子网 CIDR 不能为 10.247.0.0/16——此地址段由 CCI 保留用于服务网络。使用该地址段会导致 IP 冲突和工作负载创建失败。

⚠️ neutron_network_id 为必填项：VPC ShowSubnet 输出中的 neutron_network_id 是网络配置中 networkID 字段的值。创建网络时必须填写此字段。

命名空间规格类型

规格值	描述	用例
general-computing	通用计算类型	标准工作负载、Web 服务、微服务
gpu-accelerated	GPU 加速类型	AI、ML、高性能计算

资源配额和限制

CCI 会对每个命名空间实施资源配额。常见默认值：

资源	默认限制
Pod	因区域而异
每个 Pod 的 CPU	0.25 - 8 核
每个 Pod 的内存	0.5Gi - 32Gi
PVC	因区域而异

查询当前配额：

hcloud CCI listCoreV1NamespacedResourceQuota --namespace=<ns-name> --cli-region=<region> --cli-output=json

输出格式

JSON（推荐）

hcloud CCI <Operation> --cli-region=<region> --cli-output=json

表格（供手动查看）

hcloud CCI <Operation> --cli-region=<region> --cli-output=table

JMESPath 筛选

# Filter deployment status
hcloud CCI readAppsV1NamespacedDeploymentStatus --name=<deploy> --namespace=<ns> --cli-region=<region> --cli-output=json --cli-query="{replicas:status.replicas,ready:status.readyReplicas,available:status.availableReplicas}"

# Filter pod phase
hcloud CCI readCoreV1NamespacedPodStatus --name=<pod> --namespace=<ns> --cli-region=<region> --cli-output=json --cli-query="status.phase"

--cli-region= --cli-output=json
--cli-query="status.phase"

## Debugging

Add `--cli-debug=true` to any command for detailed request/response information:

```bash
hcloud CCI <Operation> --cli-debug=true --cli-region=<region>

参数确认

执行任何 CCI 操作之前，请确认以下参数：

参数	必填	描述	来源
--namespace	是	CCI 命名空间名称	现有或新建
--cli-region	是	华为云区域 ID	HUAWEI_CLOUD_REGION 或配置
--metadata.name	是	资源名称	用户指定
Flavor 注解	是（Namespace）	general-computing 或 gpu-accelerated	用户选择
VPC/子网 ID	是（Network）	来自 VPC ListVpcs / VPC ShowSubnet	查询现有资源
neutron_network_id	是（Network）	来自 VPC ShowSubnet 响应	查询结果

执行任何 CCI 命令之前，先运行 hcloud CCI <Operation> --help 验证参数名称，然后对照上表。

注意事项

详细的故障排查信息请参阅 references/troubleshooting.md。

快速参考：

问题	原因	快速修复
命名空间创建失败	缺少规格注解	添加 --metadata.annotations.namespace-kubernetes-io/flavor=general-computing
网络创建失败（400/403）	缺少 VPC/子网/注解/networkID，或凭据权限范围不足	验证子网/neutron ID、安全组；使用 Python 辅助程序；使用长期 AK/SK（模式 A）
Pod 一直处于 Pending 状态	命名空间中没有网络	先创建网络
403 权限错误	IAM 权限不足	查看 references/iam-policies.md
深层嵌套参数错误	点号表示法有误	使用 --help 验证准确的参数路径
未传递包含点号的注解	hcloud CLI 限制	使用 Python 辅助脚本创建网络
EIPPool 创建失败（400/422）	缺少 apiVersion/kind/networkType	添加所有必填字段（参见 EIPPool 部分）
limit/request 不匹配	CCI 要求 limits == requests	将 requests 设置为与 limits 相同（例如，两者均为 500m/1Gi）

验证方法

完整的验证步骤请参阅 references/verification-method.md。

快速检查清单：

步骤	命令	预期结果
命名空间	hcloud CCI readCoreV1Namespace --name=<ns> --cli-region=<region>	status.phase=Active
网络	hcloud CCI readNetworkingCciIoV1beta1NamespacedNetworkStatus --name=<net> --namespace=<ns>	status.phase=Active
部署	hcloud CCI readAppsV1NamespacedDeploymentStatus --name=<deploy> --namespace=<ns>	readyReplicas >= 1
Pod	hcloud CCI readCoreV1NamespacedPodStatus --name=<pod> --namespace=<ns>	status.phase=Running

最佳实践

1. 命名空间隔离：为不同的团队/项目使用不同的命名空间，以避免资源冲突
2. 按需创建 EIPPool：只有在 Pod 需要访问公网 IP 时才创建 EIPPool

hcloud CLI 的局限性

⚠️ 关键提示：hcloud CLI 存在一些已知局限性，会影响 CCI 操作。了解这些局限性对于成功创建 Network 至关重要。

局限性	影响	解决方法
无法通过 CLI 参数传递包含句点（.）的注解键	hcloud 会将参数名中的句点视为嵌套对象层级，因此 --metadata.annotations.network.alpha.kubernetes.io/default-security-group 会创建深层嵌套结构，而不是单个注解键	使用 Python 辅助脚本（scripts/cci_network_helper.py）创建 Network
--cli-jsonInput 无法正确传递注解	hcloud 的一个 bug：注解会出现在 --dryrun 输出中，但不会在实际 API 请求中传递	改用 Python 辅助脚本
--cli-jsonInput 要求使用 ASCII 编码	UTF-8 BOM 会导致 JSON 解析失败	确保 JSON 输入文件保存为纯 ASCII（不含 BOM）
命名空间注解支持用连字符替换句点	namespace.kubernetes.io/flavor 这样的键可以使用连字符（namespace-kubernetes-io/flavor），CCI 会自动将其规范化回原格式	此解决方法仅适用于 Namespace，不适用于 Network

Network 为何需要 Python 辅助脚本：无法通过 hcloud CLI 传递 Network 注解键 network.alpha.kubernetes.io/default-security-group（无论使用点号表示法还是 --cli-jsonInput）。与 Namespace 注解不同，CCI 不会将 Network 资源中用连字符替换的键规范化。Python 辅助脚本（scripts/cci_network_helper.py）会直接构造正确的 API 请求正文。

参考资料

文档	描述
task-namespace-management.md	命名空间生命周期操作
task-network-management.md	网络生命周期操作
task-deployment-management.md	Deployment 生命周期操作
task-statefulset-management.md	StatefulSet 生命周期操作
task-pod-management.md	Pod 生命周期操作
task-eippool-management.md	EIPPool 操作
task-logs-and-status.md	状态查询和日志查看
cci-operation-catalog.md	完整的 CCI 操作速查表
parameter-format.md	CCI 参数格式规则和示例
common-workflows.md	完整的工作流步骤
credential-configuration.md	凭证设置（长期 AK/SK 和临时 AK/SK+SecurityToken）
iam-policies.md	IAM 权限策略
troubleshooting.md	错误排查
verification-method.md	验证步骤
acceptance-criteria.md	正确模式与错误模式对比
scripts/cci_network_helper.py	用于创建 Network 的 Python 辅助脚本（绕过 hcloud CLI 的注解限制）