Back to Details

huawei-cloud-cci-instance-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Huawei Cloud CCI Container Instance Lifecycle Management

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

Overview

概述

Manage Huawei Cloud CCI (Cloud Container Instance) full lifecycle using hcloud CLI (KooCLI). CCI is a serverless container service — no cluster management needed, just create a Namespace, define a Network, then deploy workloads directly.
Architecture: hcloud CLI → CCI OpenAPI → Namespace / Network / Deployment / StatefulSet / Pod / EIPPool / Service / Ingress
使用hcloud CLI（KooCLI）管理华为云CCI（Cloud Container Instance，云容器实例）的全生命周期。CCI是一款无服务器容器服务——无需管理集群，只需创建Namespace、定义Network，即可直接部署工作负载。
架构：hcloud CLI → CCI OpenAPI → Namespace / Network / Deployment / StatefulSet / Pod / EIPPool / Service / Ingress

Constraints and Rules

约束与规则

Security Rules

安全规则

  • Two-step confirmation: All destructive operations (delete Namespace/Network/Deployment/StatefulSet/Pod/EIPPool) require explicit user confirmation — preview command, resource details, and risk warning first; execute only after user confirms.
  • Credential security: Never expose AK/SK values in conversation, commands, or output. Only use 
    hcloud configure list
    to check credential status (presence only). Prefer profile mode or environment variables over explicit AK/SK parameters.
  • 两步确认机制：所有破坏性操作（删除Namespace/Network/Deployment/StatefulSet/Pod/EIPPool）均需用户明确确认——先展示命令、资源详情和风险警告；仅在用户确认后执行。
  • 凭证安全：切勿在对话、命令或输出中暴露AK/SK值。仅使用
    hcloud configure list
    检查凭证状态（仅确认存在性）。优先使用配置文件模式或环境变量，而非显式AK/SK参数。

Resource Constraints

资源约束

  • Namespace flavor annotation is mandatory: Every namespace must carry 
    namespace-kubernetes-io/flavor
    annotation (value: 
    general-computing
    or 
    gpu-accelerated
    ). Without it, creation fails.
  • limits must equal requests: CCI enforces 
    resources.limits == resources.requests
    . Mismatch causes "limit and request doesn't equal" error. Set both to the same values (e.g., 
    500m/1Gi
    ).
  • Network must precede workloads: Pod/Deployment/StatefulSet creation fails or stays Pending if no Network exists in the namespace. Always create Network before deploying workloads.
  • VPC CIDR restriction: VPC subnet CIDR must NOT be 
    10.247.0.0/16
    — CCI reserves this range for Service networking. Using it causes IP conflicts and workload creation failures.
  • Deletion order: Pod → Deployment/StatefulSet → EIPPool → Network → Namespace. Deleting a Namespace cascades all resources under it.
  • Namespace必须添加规格注解：每个Namespace必须携带
    namespace-kubernetes-io/flavor
    注解（取值：
    general-computing
    或
    gpu-accelerated
    ）。缺少该注解将导致创建失败。
  • limits必须等于requests：CCI强制要求
    resources.limits == resources.requests
    。不匹配会触发“limit and request doesn't equal”错误。需将两者设置为相同值（例如：
    500m/1Gi
    ）。
  • 网络需先于工作负载创建：若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 Constraints

hcloud CLI约束

  • Network creation must use Python helper script: hcloud CLI cannot pass annotation keys containing dots (
    network.alpha.kubernetes.io/default-security-group
    ). Neither dot notation nor 
    --cli-jsonInput
    works. Use 
    scripts/cci_network_helper.py
    .
  • Namespace annotation uses hyphen replacement: Keys like 
    namespace.kubernetes.io/flavor
    can use hyphens (
    namespace-kubernetes-io/flavor
    ) and CCI auto-normalizes. This workaround only works for Namespace, NOT for Network.
  • Always verify parameters with 
    --help
    : CCI has hundreds of parameters. Run 
    hcloud CCI <Operation> --help
    before constructing any command. The help output is the authoritative source.
Detailed breakdowns of these rules are in Security Constraints, hcloud CLI Limitations, and Precautions.
  • 创建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限制和注意事项章节。

Standard Workflow

标准流程

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. 创建Namespace（添加规格注解）
2. 创建Network（需使用Python辅助脚本添加注解——详见hcloud CLI限制）
3. 创建Deployment / StatefulSet / Pod（运行工作负载）
4. 查询状态、查看日志
5. （可选）创建EIPPool以实现Pod公网访问
6. 清理：删除工作负载 → 删除Network → 删除Namespace

Prerequisites

前置条件

1. hcloud CLI Requirements (MANDATORY)

1. hcloud CLI要求（必填）

  • hcloud CLI installed (version >= 7.2.2)
  • Run 
    hcloud version
    to verify installation
  • First-time usage: 
    printf "y\n" | hcloud version
    to accept privacy statement
  • 已安装hcloud CLI（版本≥7.2.2）
  • 执行
    hcloud version
    验证安装
  • 首次使用：执行
    printf "y\n" | hcloud version
    接受隐私声明

2. Credential Configuration

2. 凭证配置

hcloud CLI supports two credential modes. See references/credential-configuration.md for full details.
Quick setup (choose one):
bash
undefined
hcloud CLI支持两种凭证模式。完整详情请查看references/credential-configuration.md。
快速配置（二选一）：
bash
undefined

Mode A — Long-term AK/SK

模式A — 长期AK/SK

export HUAWEI_CLOUD_AK=<your-ak> export HUAWEI_CLOUD_SK=<your-sk> export HUAWEI_CLOUD_REGION=cn-north-4
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

模式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

- **Security rules**: Never expose AK/SK/SecurityToken values. Use `hcloud configure list` to check presence only.

> ⚠️ **Known limitation — Python helper script credentials are independent of hcloud CLI**: The Python helper script (`scripts/cci_network_helper.py`) uses `HW_ACCESS_KEY` / `HW_SECRET_KEY` (and optionally `HW_SECURITY_TOKEN`) environment variables for authentication, which are **separate from** hcloud CLI's credential source (profile or `HUAWEI_CLOUD_AK`/`HUAWEI_CLOUD_SK`). If the credentials in `HW_ACCESS_KEY`/`HW_SECRET_KEY` lack the necessary IAM permissions for CCI Network creation, the script will fail with a 403 error. Ensure these variables contain credentials with sufficient CCI permissions (e.g., `CCI FullAccess`). The hcloud CLI continues using its own credential source independently — running the helper script does not affect subsequent hcloud CLI commands.
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 Network所需的IAM权限，脚本会返回403错误。请确保这些变量包含拥有足够CCI权限的凭证（例如：`CCI FullAccess`）。hcloud CLI会继续使用自身的凭证来源，运行辅助脚本不会影响后续hcloud CLI命令。

3. Validation Check

3. 验证检查

bash
hcloud version
hcloud configure list
bash
hcloud version
hcloud configure list

Security Constraints

安全约束

Dangerous Operation Confirmation Mechanism

危险操作确认机制

This skill strictly enforces a two-step confirmation mechanism for all destructive operations.
All destructive operations require explicit user confirmation before execution. The process:
Step 1: Preview — Show the command, resource details, and risk warning
Step 2: Confirm & Execute — Only after user explicitly confirms
本技能严格对所有破坏性操作执行两步确认机制。
所有破坏性操作执行前均需用户明确确认。流程如下：
步骤1：预览 — 展示命令、资源详情和风险警告
步骤2：确认并执行 — 仅在用户明确确认后执行

Operations Requiring Confirmation

需要确认的操作

OperationRisk LevelDescription
Delete Namespace🔴 CriticalCascades — deletes ALL resources under this namespace (Network, Pods, Deployments, etc.)
Delete Network🟠 HighDisconnects namespace from VPC; running pods lose network
Delete Deployment🟠 HighTerminates all replicas of the workload
Delete StatefulSet🟠 HighTerminates all replicas; PVC data may be lost
Delete Pod🟠 HighTerminates the container instance
Delete EIPPool🟡 MediumReleases public IPs allocated to pods
操作风险等级描述
删除Namespace🔴 严重级联删除——删除该Namespace下的所有资源（Network、Pods、Deployments等）
删除Network🟠 高断开Namespace与VPC的连接；运行中的Pods会失去网络连接
删除Deployment🟠 高终止工作负载的所有副本
删除StatefulSet🟠 高终止所有副本；PVC数据可能丢失
删除Pod🟠 高终止容器实例
删除EIPPool🟡 中释放分配给Pods的公网IP

Credential Security

凭证安全

  • Never expose AK/SK/SecurityToken values in conversation, commands, or output
  • Never ask user to input AK/SK/SecurityToken directly in conversation
  • Only use 
    hcloud configure list
    to check credential status (presence only, not values)
  • Prefer profile mode or environment variables over explicit AK/SK parameters
  • 切勿在对话、命令或输出中暴露AK/SK/SecurityToken值
  • 切勿在对话中要求用户直接输入AK/SK/SecurityToken
  • 仅使用
    hcloud configure list
    检查凭证状态（仅确认存在性，不显示值）
  • 优先使用配置文件模式或环境变量，而非显式AK/SK参数

Command Format Standard

命令格式标准

CCI follows the standard hcloud format with Kubernetes-style nested parameters:
bash
hcloud CCI <Operation> --param=value --cli-region=<region> --cli-output=json
CCI遵循标准hcloud格式，采用Kubernetes风格的嵌套参数：
bash
hcloud CCI <Operation> --param=value --cli-region=<region> --cli-output=json

CCI-Specific Parameter Rules

CCI专属参数规则

CCI parameters follow Kubernetes API conventions — deeply nested objects with dot notation:
  1. Annotations use 
    {*}
    format    : 
    --metadata.annotations.namespace-kubernetes-io/flavor=general-computing
  2. Labels use 
    {*}
    format    : 
    --metadata.labels.app=my-app
  3. Containers array (1-based): 
    --spec.template.spec.containers.1.name=main --spec.template.spec.containers.1.image=nginx
  4. Resources use 
    {*}
    format    : 
    --spec.template.spec.containers.1.resources.limits.cpu=500m
  5. Selector matchLabels use 
    {*}
    format    : 
    --spec.selector.matchLabels.app=my-app
  6. Namespaced operations require 
    --namespace
    : all workload operations must specify namespace
⚠️ Critical: Before constructing any CCI command, always run 
hcloud CCI <Operation> --help
to verify exact parameter names. CCI has hundreds of parameters; the help output is the authoritative source.
CCI参数遵循Kubernetes API约定——深度嵌套对象采用点号写法：
  1. 注解使用
    {*}
    格式    ：
    --metadata.annotations.namespace-kubernetes-io/flavor=general-computing
  2. 标签使用
    {*}
    格式    ：
    --metadata.labels.app=my-app
  3. 容器数组（从1开始计数）：
    --spec.template.spec.containers.1.name=main --spec.template.spec.containers.1.image=nginx
  4. 资源使用
    {*}
    格式    ：
    --spec.template.spec.containers.1.resources.limits.cpu=500m
  5. 选择器matchLabels使用
    {*}
    格式    ：
    --spec.selector.matchLabels.app=my-app
  6. 命名空间级操作需指定
    --namespace
    ：所有工作负载操作必须指定命名空间
⚠️ 重要提示：构造任何CCI命令前，务必执行
hcloud CCI <Operation> --help
验证准确的参数名称。CCI拥有数百个参数，帮助输出为权威来源。

Parameter Format Details

参数格式详情

See references/parameter-format.md for complete CCI parameter format rules and examples.
完整的CCI参数格式规则和示例请查看references/parameter-format.md。

Scenario Routing

场景路由

User IntentReference Document
Create/query/delete Namespacereferences/task-namespace-management.md
Create/query/delete Networkreferences/task-network-management.md
Create/query/update/delete/scale Deploymentreferences/task-deployment-management.md
Create/query/update/delete StatefulSetreferences/task-statefulset-management.md
Create/query/delete Podreferences/task-pod-management.md
Create/query/delete EIPPoolreferences/task-eippool-management.md
Query status, view logs, eventsreferences/task-logs-and-status.md
Full workflow (create→run→cleanup)references/common-workflows.md
All CCI operations quick referencereferences/cci-operation-catalog.md
Troubleshootingreferences/troubleshooting.md
IAM permissionsreferences/iam-policies.md
Verification stepsreferences/verification-method.md
Correct/error pattern comparisonreferences/acceptance-criteria.md
用户意图参考文档
创建/查询/删除Namespacereferences/task-namespace-management.md
创建/查询/删除Networkreferences/task-network-management.md
创建/查询/更新/删除/扩容Deploymentreferences/task-deployment-management.md
创建/查询/更新/删除StatefulSetreferences/task-statefulset-management.md
创建/查询/删除Podreferences/task-pod-management.md
创建/查询/删除EIPPoolreferences/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

Core Commands

核心命令

Namespace

Namespace

bash
undefined
bash
undefined

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
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
hcloud CCI listCoreV1Namespace --cli-region=<region> --cli-output=json

Read namespace details

查看命名空间详情

hcloud CCI readCoreV1Namespace --name=<ns-name> --cli-region=<region> --cli-output=json
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>
undefined
hcloud CCI deleteCoreV1Namespace --name=<ns-name> --cli-region=<region>
undefined

Network

Network

⚠️ hcloud CLI limitation: Network creation requires a Python helper script because hcloud CLI cannot pass the annotation key 
network.alpha.kubernetes.io/default-security-group
(contains dots that hcloud treats as nested levels). The 
--cli-jsonInput
approach also doesn't work due to an hcloud bug where annotations show in 
--dryrun
but aren't transmitted in actual requests. See hcloud CLI Limitations below.
⚠️ Credential requirement: The Python helper script uses 
HW_ACCESS_KEY
/
HW_SECRET_KEY
(and optionally 
HW_SECURITY_TOKEN
) environment variables for authentication. This is independent from hcloud CLI's credential source (which reads from 
HUAWEI_CLOUD_AK
/
HUAWEI_CLOUD_SK
or its profile). If the credentials in 
HW_ACCESS_KEY
/
HW_SECRET_KEY
lack CCI Network creation permissions, the script will fail with 403. Ensure they have sufficient IAM permissions (e.g., 
CCI FullAccess
). After the script runs, hcloud CLI commands continue using their own credential source unaffected.
bash
undefined
⚠️ hcloud CLI限制：创建Network需使用Python辅助脚本，因为hcloud CLI无法传递注解键
network.alpha.kubernetes.io/default-security-group
（包含点号，hcloud会将其视为嵌套层级）。
--cli-jsonInput
方案也因hcloud的bug无法生效——注解会显示在
--dryrun
输出中，但实际请求不会传递。详见下文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命令仍会使用自身的凭证来源，不受影响。
bash
undefined

Step 1: Get VPC subnet details (including neutron_network_id)

步骤1：获取VPC子网详情（包含neutron_network_id）

hcloud VPC ShowSubnet --vpc_id=<vpc-id> --subnet_id=<subnet-id> --cli-region=<region> --cli-output=json
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

步骤2：通过Python辅助脚本创建Network

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>
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

步骤3：检查Network状态直至变为Active

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

List networks

列出Networks

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

**Required Network spec fields**: Network creation requires `attachedVPC`, `subnetID`, `networkType`, AND `networkID` (neutron network ID). The `networkID` field is REQUIRED — it is the neutron network ID obtained from `hcloud VPC ShowSubnet`.

**Required Network annotation**: `network.alpha.kubernetes.io/default-security-group` (the correct annotation key for CCI Network security group, NOT `security-group-id`). This annotation must be set to the security group ID.
hcloud CCI listNetworkingCciIoV1beta1NamespacedNetwork
--namespace=<ns-name>
--cli-region=<region>
--cli-output=json

**Network必填字段**：创建Network需要`attachedVPC`、`subnetID`、`networkType`和`networkID`（neutron网络ID）。`networkID`字段为必填项——需从`hcloud VPC ShowSubnet`的结果中获取。

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

Deployment

Deployment

bash
undefined
bash
undefined

Create deployment

创建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
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

扩容Deployment

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

Read deployment status

查看Deployment状态

hcloud CCI readAppsV1NamespacedDeploymentStatus
--name=<deploy-name>
--namespace=<ns-name>
--cli-region=<region>
--cli-output=json
undefined
hcloud CCI readAppsV1NamespacedDeploymentStatus
--name=<deploy-name>
--namespace=<ns-name>
--cli-region=<region>
--cli-output=json
undefined

StatefulSet

StatefulSet

bash
undefined
bash
undefined

Create statefulset

创建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
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

查看StatefulSet状态

hcloud CCI readAppsV1NamespacedStatefulSetStatus
--name=<sts-name>
--namespace=<ns-name>
--cli-region=<region>
--cli-output=json
undefined
hcloud CCI readAppsV1NamespacedStatefulSetStatus
--name=<sts-name>
--namespace=<ns-name>
--cli-region=<region>
--cli-output=json
undefined

Pod

Pod

bash
undefined
bash
undefined

Create pod (single container instance)

创建Pod（单容器实例）

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
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

查看Pod状态

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

Read pod logs

查看Pod日志

hcloud CCI readCoreV1NamespacedPodLog
--name=<pod-name>
--namespace=<ns-name>
--container=<container-name>
--cli-region=<region>
undefined
hcloud CCI readCoreV1NamespacedPodLog
--name=<pod-name>
--namespace=<ns-name>
--container=<container-name>
--cli-region=<region>
undefined

EIPPool

EIPPool

bash
undefined
bash
undefined

Create EIPPool (for pod public IP access — auto-create EIPs)

创建EIPPool（用于Pod公网访问——自动创建弹性公网IP）

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
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

查看EIPPool状态

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

**EIPPool required fields**: `--apiVersion=crd.yangtse.cni/v1` and `--kind=EIPPool` are mandatory. `spec.eipAttributes.networkType` is required (values: `5_bgp` for dynamic BGP, `5_gray` for dedicated load balancing). `spec.eipAttributes.bandwidth.chargeMode` and `name` are required when auto-creating EIPs.

**Pod EIP binding**: To assign an EIPPool to a Pod, add annotation `yangtse.io/eippool=<eippool-name>` (use hyphen workaround: `--metadata.annotations.yangtse-io/eippool=<eippool-name>`).
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`为必填项（取值：`5_bgp`表示动态BGP，`5_gray`表示专属负载均衡）。自动创建弹性公网IP时，`spec.eipAttributes.bandwidth.chargeMode`和`name`为必填项。

**Pod绑定EIPPool**：若要为Pod分配EIPPool，需添加注解`yangtse.io/eippool=<eippool-name>`（使用连字符替代方案：`--metadata.annotations.yangtse-io/eippool=<eippool-name>`）。

VPC/Subnet Prerequisites

VPC/子网前置条件

CCI workloads run inside a Network that maps to an existing VPC subnet. Before creating a Network, query available VPCs and subnets, and obtain the neutron network ID (required for Network creation):
bash
undefined
CCI工作负载运行在映射到现有VPC子网的Network内。创建Network前，需查询可用的VPC和子网，并获取neutron网络ID（创建Network的必填项）：
bash
undefined

List VPCs

列出VPCs

hcloud VPC ListVpcs --cli-region=<region> --cli-output=json
hcloud VPC ListVpcs --cli-region=<region> --cli-output=json

List subnets

列出子网

hcloud VPC ListSubnets --cli-region=<region> --cli-output=json
hcloud VPC ListSubnets --cli-region=<region> --cli-output=json

Get subnet details (including neutron_network_id — REQUIRED for Network creation)

获取子网详情（包含neutron_network_id——创建Network的必填项）

hcloud VPC ShowSubnet --vpc_id=<vpc-id> --subnet_id=<subnet-id> --cli-region=<region> --cli-output=json

> **⚠️ VPC subnet CIDR restriction**: The VPC and subnet CIDR must NOT be `10.247.0.0/16` — this range is reserved by CCI for Service networking. Using it causes IP conflicts and workload creation failures.

> **⚠️ neutron_network_id is required**: The `neutron_network_id` from `VPC ShowSubnet` output is the value for the `networkID` field in Network spec. This field is 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预留用于Service网络。使用该网段会导致IP冲突，进而引发工作负载创建失败。

> **⚠️ neutron_network_id为必填项**：`VPC ShowSubnet`输出中的`neutron_network_id`是Network规格中`networkID`字段的取值。该字段为创建Network的必填项。

Namespace Flavor Types

Namespace规格类型

Flavor ValueDescriptionUse Case
general-computing
General computing typeStandard workloads, web services, microservices
gpu-accelerated
GPU accelerated typeAI, ML, high-performance computing
规格值描述使用场景
general-computing
通用计算型标准工作负载、Web服务、微服务
gpu-accelerated
GPU加速型AI、机器学习、高性能计算

Resource Quota and Limits

资源配额与限制

CCI enforces resource quotas per namespace. Common defaults:
ResourceDefault Limit
Podsvaries by region
CPU per Pod0.25 - 8 cores
Memory per Pod0.5Gi - 32Gi
PVCsvaries
Query current quotas:
bash
hcloud CCI listCoreV1NamespacedResourceQuota --namespace=<ns-name> --cli-region=<region> --cli-output=json
CCI对每个Namespace执行资源配额限制。常见默认值：
资源默认限制
Pods因地域而异
单Pod CPU0.25 - 8核
单Pod内存0.5Gi - 32Gi
PVCs因地域而异
查询当前配额：
bash
hcloud CCI listCoreV1NamespacedResourceQuota --namespace=<ns-name> --cli-region=<region> --cli-output=json

Output Format

输出格式

JSON (recommended)

JSON（推荐）

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

Table (for manual viewing)

表格（手动查看）

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

JMESPath Filtering

JMESPath过滤

bash
undefined
bash
undefined

Filter deployment status

过滤Deployment状态

hcloud CCI readAppsV1NamespacedDeploymentStatus --name=<deploy> --namespace=<ns> --cli-region=<region> --cli-output=json --cli-query="{replicas:status.replicas,ready:status.readyReplicas,available:status.availableReplicas}"
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

过滤Pod阶段

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

Debugging

调试

Add 
--cli-debug=true
to any command for detailed request/response information:
bash
hcloud CCI <Operation> --cli-debug=true --cli-region=<region>
在任意命令后添加
--cli-debug=true
以获取详细的请求/响应信息：
bash
hcloud CCI <Operation> --cli-debug=true --cli-region=<region>

Parameter Confirmation

参数确认

Before executing any CCI operation, confirm these parameters:
ParameterRequiredDescriptionSource
--namespace
YesCCI namespace nameExisting or newly created
--cli-region
YesHuawei Cloud region ID
HUAWEI_CLOUD_REGION
or config
--metadata.name
YesResource nameUser specified
Flavor annotationYes (Namespace)
general-computing
or 
gpu-accelerated
User choice
VPC/Subnet IDYes (Network)From 
VPC ListVpcs
/ 
VPC ShowSubnet
Query existing resources
neutron_network_idYes (Network)From 
VPC ShowSubnet
response		Query result
Run 
hcloud CCI <Operation> --help
before any CCI command to verify parameter names, then cross-reference the table above.
执行任何CCI操作前，请确认以下参数：
参数是否必填描述来源
--namespace
是CCI命名空间名称已存在或新建
--cli-region
是华为云地域ID
HUAWEI_CLOUD_REGION
或配置文件
--metadata.name
是资源名称用户指定
规格注解是（Namespace）
general-computing
或
gpu-accelerated
用户选择
VPC/子网ID是（Network）来自
VPC ListVpcs
/ 
VPC ShowSubnet
查询现有资源
neutron_network_id是（Network）来自
VPC ShowSubnet
响应		查询结果
执行任何CCI命令前，先运行
hcloud CCI <Operation> --help
验证参数名称，再对照上表进行确认。

Precautions

注意事项

See references/troubleshooting.md for detailed troubleshooting.
Quick reference:
IssueCauseQuick Fix
Namespace creation failsMissing flavor annotationAdd 
--metadata.annotations.namespace-kubernetes-io/flavor=general-computing
Network creation fails (400/403)Missing VPC/subnet/annotation/networkID, or credential scope insufficientVerify subnet/neutron IDs, security group; use Python helper; use long-term AK/SK (Mode A)
Pod stays PendingNo Network in namespaceCreate Network first
403 permission errorInsufficient IAMCheck references/iam-policies.md
Deep nested param errorsWrong dot notationUse 
--help
to verify exact parameter path
Annotation with dots not passedhcloud CLI limitationUse Python helper script for Network creation
EIPPool creation fails (400/422)Missing apiVersion/kind/networkTypeAdd all required fields (see EIPPool section)
limit/request mismatchCCI requires limits == requestsSet requests same as limits (e.g., both 
500m/1Gi
)
详细故障排查请查看references/troubleshooting.md。
快速参考:
问题原因快速修复
Namespace创建失败缺少规格注解添加
--metadata.annotations.namespace-kubernetes-io/flavor=general-computing
Network创建失败（400/403）缺少VPC/子网/注解/networkID，或凭证权限不足验证子网/neutron ID、安全组；使用Python辅助脚本；使用长期AK/SK（模式A）
Pod处于Pending状态Namespace内无Network先创建Network
403权限错误IAM权限不足查看references/iam-policies.md
深层嵌套参数错误点号写法错误使用
--help
验证准确的参数路径
含点号的注解未传递hcloud CLI限制使用Python辅助脚本创建Network
EIPPool创建失败（400/422）缺少apiVersion/kind/networkType添加所有必填字段（详见EIPPool章节）
limit/request不匹配CCI要求limits == requests将requests设置为与limits相同的值（例如：均为
500m/1Gi
）

Verification Method

验证方法

See references/verification-method.md for complete verification steps.
Quick checklist:
StepCommandExpected Result
Namespace
hcloud CCI readCoreV1Namespace --name=<ns> --cli-region=<region>
status.phase=Active
Network
hcloud CCI readNetworkingCciIoV1beta1NamespacedNetworkStatus --name=<net> --namespace=<ns>
status.phase=Active
Deployment
hcloud CCI readAppsV1NamespacedDeploymentStatus --name=<deploy> --namespace=<ns>
readyReplicas >= 1
Pod
hcloud CCI readCoreV1NamespacedPodStatus --name=<pod> --namespace=<ns>
status.phase=Running
完整验证步骤请查看references/verification-method.md。
快速检查清单:
步骤命令预期结果
Namespace
hcloud CCI readCoreV1Namespace --name=<ns> --cli-region=<region>
status.phase=Active
Network
hcloud CCI readNetworkingCciIoV1beta1NamespacedNetworkStatus --name=<net> --namespace=<ns>
status.phase=Active
Deployment
hcloud CCI readAppsV1NamespacedDeploymentStatus --name=<deploy> --namespace=<ns>
readyReplicas >= 1
Pod
hcloud CCI readCoreV1NamespacedPodStatus --name=<pod> --namespace=<ns>
status.phase=Running

Best Practices

最佳实践

  1. Namespace isolation: Use different namespaces for different teams/projects to avoid resource conflicts
  2. EIPPool on-demand: Only create EIPPool when Pod public IP access is needed
  1. Namespace隔离：为不同团队/项目使用不同的Namespace，避免资源冲突
  2. 按需创建EIPPool：仅当需要Pod公网访问时才创建EIPPool

hcloud CLI Limitations

hcloud CLI限制

⚠️ Critical: hcloud CLI has known limitations that affect CCI operations. Understanding these is essential for successful Network creation.
LimitationImpactWorkaround
Cannot pass annotation keys containing dots (.) via CLI parametershcloud treats dots in parameter names as nested object levels, so 
--metadata.annotations.network.alpha.kubernetes.io/default-security-group
creates a deeply nested structure instead of a single annotation key		Use Python helper script (
scripts/cci_network_helper.py
) for Network creation
--cli-jsonInput
doesn't properly transmit annotations		hcloud bug: annotations appear in 
--dryrun
output but are not transmitted in actual API requests		Use Python helper script instead
--cli-jsonInput
requires ASCII encoding		UTF-8 BOM causes JSON parsing failureEnsure JSON input files are saved as plain ASCII (no BOM)
Namespace annotation works with hyphen replacementKeys like 
namespace.kubernetes.io/flavor
can use hyphens (
namespace-kubernetes-io/flavor
) and CCI auto-normalizes them back		This workaround only works for Namespace, NOT for Network
Why Network needs a Python helper: The Network annotation key 
network.alpha.kubernetes.io/default-security-group
cannot be passed via hcloud CLI (neither dot notation nor 
--cli-jsonInput
). Unlike Namespace annotations, CCI does NOT normalize hyphen-replaced keys for Network resources. The Python helper script (
scripts/cci_network_helper.py
) constructs the correct API request body directly.
⚠️ 重要提示：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注解可使用连字符替代类似
namespace.kubernetes.io/flavor
的键可使用连字符（
namespace-kubernetes-io/flavor
），CCI会自动将其标准化回原格式		此方案仅适用于Namespace，不适用于Network
为何Network需要Python辅助脚本：Network的注解键
network.alpha.kubernetes.io/default-security-group
无法通过hcloud CLI传递（点号写法和
--cli-jsonInput
均无效）。与Namespace注解不同，CCI不会对Network资源的连字符替代键进行标准化。Python辅助脚本（
scripts/cci_network_helper.py
）可直接构造正确的API请求体。

References

参考文档

DocumentDescription
task-namespace-management.mdNamespace lifecycle operations
task-network-management.mdNetwork lifecycle operations
task-deployment-management.mdDeployment lifecycle operations
task-statefulset-management.mdStatefulSet lifecycle operations
task-pod-management.mdPod lifecycle operations
task-eippool-management.mdEIPPool operations
task-logs-and-status.mdStatus queries and log viewing
cci-operation-catalog.mdFull CCI operation quick reference
parameter-format.mdCCI parameter format rules and examples
common-workflows.mdComplete workflow sequences
credential-configuration.mdCredential setup (long-term AK/SK & temporary AK/SK+SecurityToken)
iam-policies.mdIAM permission policies
troubleshooting.mdError troubleshooting
verification-method.mdVerification steps
acceptance-criteria.mdCorrect/error pattern comparison
scripts/cci_network_helper.pyPython helper script for Network creation (bypasses hcloud CLI annotation limitations)
文档描述
task-namespace-management.mdNamespace生命周期操作
task-network-management.mdNetwork生命周期操作
task-deployment-management.mdDeployment生命周期操作
task-statefulset-management.mdStatefulSet生命周期操作
task-pod-management.mdPod生命周期操作
task-eippool-management.mdEIPPool操作
task-logs-and-status.md状态查询与日志查看
cci-operation-catalog.md完整CCI操作速查
parameter-format.mdCCI参数格式规则与示例
common-workflows.md完整流程序列
credential-configuration.md凭证配置（长期AK/SK & 临时AK/SK+SecurityToken）
iam-policies.mdIAM权限策略
troubleshooting.md故障排查
verification-method.md验证步骤
acceptance-criteria.md正确/错误模式对比
scripts/cci_network_helper.py用于创建Network的Python辅助脚本（绕过hcloud CLI的注解限制）