Huawei Cloud CCI Container Instance Lifecycle Management#

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

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.

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.

hcloud CLI Constraints#

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

Standard Workflow#

text

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

Prerequisites#

Prerequisite check: hcloud (KooCLI) >= 7.2.2 required Run hcloud version to verify version >= 7.2.2, and hcloud configure list to check profile exists. If not installed or version is too low, refer to the huawei-cloud-cli-guidance skill for installation guide.

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

Operations Requiring Confirmation

OperationRisk LevelDescriptionDelete Namespace🔴 CriticalCascades — deletes ALL resources under this namespace (Network, Pods, Deployments, etc.)Delete Network🟠 HighDisconnects namespace from VPC; running pods lose networkDelete Deployment🟠 HighTerminates all replicas of the workloadDelete StatefulSet🟠 HighTerminates all replicas; PVC data may be lostDelete Pod🟠 HighTerminates the container instanceDelete EIPPool🟡 MediumReleases public IPs allocated to pods

Credential Security#

• Never expose AK/SK values in conversation, commands, or output
• Never ask user to input AK/SK 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

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-Specific Parameter Rules#

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.

Parameter Format Details#

See references/parameter-format.md for complete CCI parameter format rules and examples.

Scenario Routing#

User IntentReference DocumentCreate/query/delete Namespacereferences/task-namespace-management.mdCreate/query/delete Networkreferences/task-network-management.mdCreate/query/update/delete/scale Deploymentreferences/task-deployment-management.mdCreate/query/update/delete StatefulSetreferences/task-statefulset-management.mdCreate/query/delete Podreferences/task-pod-management.mdCreate/query/delete EIPPoolreferences/task-eippool-management.mdQuery status, view logs, eventsreferences/task-logs-and-status.mdFull workflow (create→run→cleanup)references/common-workflows.mdAll CCI operations quick referencereferences/cci-operation-catalog.mdTroubleshootingreferences/troubleshooting.mdIAM permissionsreferences/iam-policies.mdVerification stepsreferences/verification-method.mdCorrect/error pattern comparisonreferences/acceptance-criteria.md

Core Commands#

Namespace#

bash

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

bash

# 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

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.

Deployment#

bash

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

bash

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

bash

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

bash

# 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 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>).

VPC/Subnet Prerequisites#

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

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

Namespace Flavor Types#

Flavor ValueDescriptionUse Casegeneral-computingGeneral computing typeStandard workloads, web services, microservicesgpu-acceleratedGPU accelerated typeAI, ML, high-performance computing

This annotation is mandatory when creating a namespace. Without it, namespace creation will fail.

Resource Quota and Limits#

CCI enforces resource quotas per namespace. Common defaults:

ResourceDefault LimitPodsvaries by regionCPU per Pod0.25 - 8 coresMemory per Pod0.5Gi - 32GiPVCsvaries

Query current quotas:

bash

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

Output Format#

JSON (recommended)#

bash

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

Table (for manual viewing)#

bash

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

JMESPath Filtering#

bash

# Filter deployment replicas and status
hcloud CCI readAppsV1NamespacedDeploymentStatus \
  --name=<deploy-name> --namespace=<ns-name> \
  --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-name> --namespace=<ns-name> \
  --cli-region=<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>

Parameter Confirmation#

Before executing any CCI operation, confirm the following parameters:

ParameterRequiredDescriptionSource--namespaceYesCCI namespace nameExisting or newly created--cli-regionYesHuawei Cloud region IDHUAWEI_CLOUD_REGION or config--metadata.nameYesResource name (Pod/Deployment/Network etc.)User specified--metadata.annotations.namespace-kubernetes-io/flavorYes (Namespace)Flavor type: general-computing or gpu-acceleratedUser choiceVPC/Subnet IDYes (Network)From VPC ListVpcs / VPC ShowSubnetQuery existing resourcesneutron_network_idYes (Network)From VPC ShowSubnet response neutron_network_id fieldQuery result

⚠️ Recommended: run hcloud CCI <Operation> --help before any CCI command to verify parameter names, then cross-reference the table above to confirm parameter value sources.

Precautions#

See references/troubleshooting.md for detailed troubleshooting.

Quick reference:

IssueCauseQuick FixNamespace creation failsMissing flavor annotationAdd --metadata.annotations.namespace-kubernetes-io/flavor=general-computingNetwork creation failsMissing VPC/subnet, CIDR conflict, or missing annotation/networkIDVerify subnet ID, neutron network ID, security group ID; ensure CIDR != 10.247.0.0/16; use Python helper scriptPod stays PendingNo Network in namespaceCreate Network first403 permission errorInsufficient IAMCheck references/iam-policies.mdDeep nested param errorsWrong dot notationUse --help to verify exact parameter pathAnnotation with dots not passedhcloud CLI treats dots as nested levelsUse Python helper script for Network creationEIPPool creation fails (400/422)Missing --apiVersion=crd.yangtse.cni/v1 or --kind=EIPPool or networkTypeAdd all required fields (see EIPPool section)Deployment "limit and request doesn't equal" errorCCI requires limits == requestsSet requests to same values as limits (e.g., both 500m/1Gi)

Verification Method#

See references/verification-method.md for complete verification steps.

Quick verification checklist:

StepCommandExpected ResultNamespace creationhcloud CCI readCoreV1Namespace --name=<ns> --cli-region=<region>status.phase=ActiveNetwork creationhcloud CCI readNetworkingCciIoV1beta1NamespacedNetworkStatus --name=<net> --namespace=<ns>status.phase=ActiveDeployment creationhcloud CCI readAppsV1NamespacedDeploymentStatus --name=<deploy> --namespace=<ns>readyReplicas >= 1Pod creationhcloud 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

hcloud CLI Limitations#

⚠️ Critical: hcloud CLI has known limitations that affect CCI operations. Understanding these is essential for successful Network creation.

LimitationImpactWorkaroundCannot 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 keyUse Python helper script ( scripts/cci_network_helper.py) for Network creation**--cli-jsonInput doesn't properly transmit annotationshcloud bug: annotations appear in --dryrun output but are not transmitted in actual API requestsUse 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 backThis 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 auto-normalize hyphen-replaced keys for Network resources. The Python helper script ( scripts/cci_network_helper.py) constructs the correct API request body directly, bypassing these hcloud CLI limitations.

References#

DocumentDescriptiontask-namespace-management.mdNamespace lifecycle operationstask-network-management.mdNetwork lifecycle operationstask-deployment-management.mdDeployment lifecycle operationstask-statefulset-management.mdStatefulSet lifecycle operationstask-pod-management.mdPod lifecycle operationstask-eippool-management.mdEIPPool operationstask-logs-and-status.mdStatus queries and log viewingcci-operation-catalog.mdFull CCI operation quick referenceparameter-format.mdCCI parameter format rules and examplescommon-workflows.mdComplete workflow sequencesiam-policies.mdIAM permission policiestroubleshooting.mdError troubleshootingverification-method.mdVerification stepsacceptance-criteria.mdCorrect/error pattern comparisonscripts/cci_network_helper.pyPython helper script for Network creation (bypasses hcloud CLI annotation limitations)