huawei-cloud-cci-instance-management

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

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

1. hcloud CLI Requirements (MANDATORY)

• 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

2. Credential Configuration

hcloud CLI supports two credential modes. See references/credential-configuration.md for full details.

Quick setup (choose one):

# Mode A — Long-term AK/SK
export

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

3. Validation Check

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

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

Command Format Standard

CCI follows the standard hcloud format with Kubernetes-style nested parameters:

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

Core Commands

Namespace

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.

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

StatefulSet

Pod

EIPPool

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

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

Resource Quota and Limits

CCI enforces resource quotas per namespace. Common defaults:

Query current quotas:

Output Format

JSON (recommended)

Table (for manual viewing)

JMESPath Filtering

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

Parameter Confirmation

Before executing any CCI operation, confirm these parameters:

Run hcloud CCI <Operation> --help before any CCI command to verify parameter names, then cross-reference the table above.

Precautions

See references/troubleshooting.md for detailed troubleshooting.

Quick reference:

Verification Method

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

Quick checklist:

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.

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.

References