Overview
This skill provides cluster onboarding, lifecycle, and fleet grouping management capabilities for Huawei Cloud UCS (Universal Cloud Service) using the hcloud CLI.
Architecture: hcloud CLI → UCS Service API → Cluster/ClusterGroup/AccessConfig/KubeConfig resources
Related Skills:
ucs-policy-governor- UCS policy governance, compliance, and audit management
Capabilities:
- Register self-managed or CCE clusters to UCS for unified management
- Remove clusters from UCS management (deregistration)
- Query cluster details, list managed clusters
- Update cluster properties and metadata
- Create, delete, update, and query fleet groups for cluster organization
- Add/remove clusters from fleet groups (join/leave)
- Retry cluster activation
- Obtain cluster access information and kubeconfig credentials
- Download federation kubeconfig for multi-cluster access
- Check UCS resource quotas
Typical Use Cases:
- "Register my CCE cluster to UCS"
- "List all clusters managed by UCS"
- "Remove a cluster from UCS management"
- "Create a fleet group for production clusters"
- "Get kubeconfig for my UCS-managed cluster"
- "Download federation kubeconfig for multi-cluster access"
- "Check my UCS quota usage"
- "Update cluster metadata"
- "Query cluster access information"
- "Add a cluster to a fleet group"
- "Remove a cluster from a fleet group"
- "Retry cluster activation"
Prerequisites
1. hcloud CLI Requirements (MANDATORY)
- hcloud CLI installed (version >= 7.2.2)
- Run
hcloud versionto verify installation - First-time usage:
printf "y\n" | hcloud versionto accept privacy statement
2. Credential Configuration
- Valid Huawei Cloud credentials (AK/SK mode)
- Security Rules:
- 🚫 Never expose AK/SK values in code, conversation, or commands
- 🚫 Never use
echo $HUAWEI_CLOUD_AKorecho $HUAWEI_CLOUD_SKto check credentials - ✅ Use environment variables:
HUAWEI_CLOUD_AK,HUAWEI_CLOUD_SK,HUAWEI_CLOUD_REGION - ✅ Prefer IAM users over root account for cloud operations
- ✅ Enable MFA for sensitive operations
Configuration Method (Environment Variables Only):
export HUAWEI_CLOUD_AK=<your-ak>
export HUAWEI_CLOUD_SK=<your-sk>
export HUAWEI_CLOUD_REGION=cn-north-4
⚠️ Important Security Notes:
- Never commit credentials to version control
- Use IAM users with minimal required permissions
- Enable MFA for sensitive operations
- Rotate AK/SK regularly
3. IAM Permission Requirements
| API Action | Permission | Purpose |
|---|---|---|
ucs:cluster:create |
Register cluster | Register cluster to UCS |
ucs:cluster:delete |
Delete cluster | Remove cluster from UCS |
ucs:cluster:get |
Get cluster | View cluster details |
ucs:cluster:list |
List clusters | List all managed clusters |
ucs:cluster:update |
Update cluster | Modify cluster properties |
ucs:clusterGroup:create |
Create group | Create fleet group |
ucs:clusterGroup:delete |
Delete group | Remove fleet group |
ucs:clusterGroup:get |
Get group | View fleet group details |
ucs:clusterGroup:update |
Update group | Update fleet group description |
ucs:clusterAccess:get |
Get access info | Obtain cluster access information |
ucs:quota:get |
Get quota | Check UCS resource quotas |
ucs:kubeconfig:create |
Create kubeconfig | Obtain cluster kubeconfig |
ucs:federationKubeconfig:get |
Get federation | Download federation kubeconfig |
See IAM Permission Policies for complete policy JSON.
Permission Failure Handling:
- When any command fails due to permission errors, read
references/iam-policies.md - Display the required permission list and policy JSON to the user
- Guide the user to create a custom policy in the IAM console and grant authorization
- Pause execution and wait for user confirmation that permissions have been granted
Core Commands
1. Cluster Registration & Deregistration
See Task: Cluster Registration for detailed workflows.
RegisterCluster uses Kubernetes API-style parameters (apiVersion, kind, metadata., spec.).
# Register a CCE cluster to UCS
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=prod-backend-cluster --spec.category=self --spec.provider=huaweicloud --spec.type=cce --spec.manageType=grouped --spec.country=CN --spec.city=110000 --metadata.uid=<cce-cluster-id> --spec.projectID=<project-id> --spec.region=cn-north-4 --cli-region=cn-north-4
# Register a CCE cluster and assign to fleet group at registration
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=prod-backend-cluster --spec.category=self --spec.provider=huaweicloud --spec.type=cce --spec.manageType=grouped --spec.country=CN --spec.city=110000 --metadata.uid=<cce-cluster-id> --spec.projectID=<project-id> --spec.region=cn-north-4 --spec.clusterGroupID=<group-id> --cli-region=cn-north-4
# Register a self-managed/attached cluster
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=datacenter-k8s --spec.category=onpremise --spec.provider=self_managed --spec.type=Kubernetes --spec.manageType=discrete --spec.country=CN --spec.city=110000 --metadata.annotations.kubeconfig=<kubeconfig-yaml-content> --cli-region=cn-north-4
# Retry cluster activation (if registration stuck)
hcloud UCS RetryClusterActivation --clusterid=<ucs-cluster-id> --cli-region=cn-north-4
# Remove a cluster from UCS
hcloud UCS DeleteCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4
Cluster Categories (spec.category):
self: Huawei Cloud CCE (Cloud Container Engine) managed clusteronpremise: Self-managed or third-party Kubernetes cluster
Cluster Providers (spec.provider):
huaweicloud: Huawei Cloud managed CCE clusterself_managed: Self-managed Kubernetes cluster
Manage Types (spec.manageType):
grouped: Cluster managed within a fleet groupdiscrete: Cluster managed independently
2. Cluster Query & Lifecycle
# Show cluster details
hcloud UCS ShowCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4
# List managed clusters (with pagination)
hcloud UCS ShowClusterList --limit=20 --offset=0 --cli-region=cn-north-4
# List managed clusters with filters
hcloud UCS ShowClusterList --category=CCE --enablestatus=Available --clustergroupid=<group-id> --cli-region=cn-north-4
# List all managed clusters (with optional unimported flag)
hcloud UCS ListManagedClusters --cli-region=cn-north-4
hcloud UCS ListManagedClusters --unimported --cli-region=cn-north-4
# Update cluster properties (K8s API-style params)
hcloud UCS UpdateCluster --clusterid=<ucs-cluster-id> --apiVersion=v1 --kind=Cluster --spec.city=Shanghai --spec.country=CN --cli-region=cn-north-4
# Show cluster access information
hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --cli-region=cn-north-4
# Show cluster access information with optional filters
hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --region=cn-north-4 --vpcendpoint=<vpc-id> --cli-region=cn-north-4
ShowClusterList Valid Filter Parameters:
--category: Filter by cluster category (self, onpremise)--clustergroupid: Filter by fleet group ID--clusterids: Filter by specific cluster IDs--enablestatus: Filter by cluster status (Available, Unavailable)--managetype: Filter by manage type (grouped, discrete)--limit: Pagination limit--offset: Pagination offset--order: Sort order (asc, desc)--order_by: Sort field
3. Fleet Group Management
See Task: Fleet Management for detailed workflows.
# Create a fleet group
hcloud UCS RegisterClusterGroup --metadata.name=production-fleet --spec.description="All production clusters" --spec.clusterIds.1=<cluster-id-1> --cli-region=cn-north-4
# List all fleet groups
hcloud UCS ListClusterGroup --limit=20 --offset=0 --cli-region=cn-north-4
# Show fleet group details
hcloud UCS ShowClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4
# Update fleet group description
hcloud UCS UpdateClusterGroup --clustergroupid=<group-id> --description="Updated fleet description" --cli-region=cn-north-4
# Add clusters to fleet group
hcloud UCS UpdateClusterGroupAssociatedClusters --clustergroupid=<group-id> --clusterIds.1=<cluster-id-1> --clusterIds.2=<cluster-id-2> --cli-region=cn-north-4
# Add a single cluster to fleet group (join)
hcloud UCS JoinGroup --clusterid=<ucs-cluster-id> --clusterGroupID=<group-id> --cli-region=cn-north-4
# Remove a cluster from fleet group (leave)
hcloud UCS LeaveGroup --clusterid=<ucs-cluster-id> --cli-region=cn-north-4
# Delete a fleet group
hcloud UCS DeleteClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4
4. Kubeconfig & Access Management
See Task: Access Management for detailed workflows.
# Get kubeconfig for a specific cluster
hcloud UCS CreateClusterKubeconfig --clusterid=<ucs-cluster-id> --cli-region=cn-north-4
# Create cluster configuration
hcloud UCS CreateClusterConf --clusterid=<ucs-cluster-id> --cli-region=cn-north-4
# Download federation kubeconfig (for multi-cluster access)
hcloud UCS DownloadFederationKubeconfig --clustergroupid=<group-id> --duration=3600 --cli-region=cn-north-4
DownloadFederationKubeconfig Required Parameters:
--clustergroupid: Fleet group ID (required path parameter)--duration: Token validity duration in seconds (required integer body parameter)
5. Quota Management
# Show UCS resource quotas (domainid is required - account ID)
hcloud UCS ShowQuota --domainid=<account-id> --cli-region=cn-north-4
Parameter Reference
Common Parameters
| Parameter | Required/Optional | Description | Default |
|---|---|---|---|
--cli-region |
Required | Huawei Cloud region ID | Config value or HUAWEI_CLOUD_REGION |
--clusterid |
Context-dependent | UCS cluster ID | N/A |
--clustergroupid |
Context-dependent | Fleet group ID | N/A |
Cluster Registration Parameters (K8s API Style)
| Parameter | Required | Description | Constraints |
|---|---|---|---|
--apiVersion |
Yes | API version (always v1) |
Must be v1 |
--kind |
Yes | Resource kind (always Cluster) |
Must be Cluster |
--metadata.name |
Yes | Cluster display name | 1-128 chars |
--spec.category |
Yes | Cluster category | self or onpremise |
--spec.provider |
Yes | Cluster provider | huaweicloud or self_managed |
--spec.type |
Yes | Cluster type | cce, baremetal, Kubernetes, etc. |
--spec.manageType |
Yes | Management type | grouped or discrete |
--spec.country |
Yes | Country code | Country code (e.g., CN) |
--spec.city |
Yes | City code | City code (e.g., 110000 for Beijing) |
--metadata.uid |
CCE only | CCE cluster ID | Must reference existing CCE cluster |
--spec.projectID |
CCE only | Project ID | Valid Huawei Cloud project ID |
--spec.region |
CCE only | CCE cluster region | Must match CCE cluster region |
--metadata.annotations.kubeconfig |
Self-managed only | Kubeconfig content | Valid Kubernetes kubeconfig YAML |
--spec.clusterGroupID |
No | Assign to fleet at registration | Valid fleet group ID |
--metadata.labels.* |
No | Custom labels | Key-value pairs |
UpdateCluster Parameters (K8s API Style)
| Parameter | Required | Description | Constraints |
|---|---|---|---|
--clusterid |
Yes | UCS cluster ID (path param) | Must be registered cluster |
--apiVersion |
Yes | API version (always v1) |
Must be v1 |
--kind |
Yes | Resource kind (always Cluster) |
Must be Cluster |
--spec.city |
No | Update city | City name |
--spec.country |
No | Update country | Country code |
--metadata.annotations |
No | Update annotations | Key-value pairs |
--spec.workerConfig.replicas |
No | Update worker replicas | Integer |
--spec.workerConfig.strategy.* |
No | Update worker strategy | K8s deployment strategy fields |
Fleet Group Parameters
| Parameter | Required | Description | Constraints |
|---|---|---|---|
--metadata.name |
Yes (create) | Group display name | 1-128 chars |
--spec.description |
No (create) | Group description | Free text |
--spec.clusterIds.N |
No (create) | Initial cluster IDs | Indexed (1, 2, 3...) |
--clustergroupid |
Yes (get/delete/update) | Group ID | UUID format |
--description |
Yes (UpdateClusterGroup) | New description | Free text |
--clusterIds.N |
Yes (UpdateClusterGroupAssociatedClusters) | Cluster IDs to add | Indexed |
Join/Leave Group Parameters
| Parameter | Required | Description | Constraints |
|---|---|---|---|
--clusterid |
Yes | UCS cluster ID (path) | Must be registered cluster |
--clusterGroupID |
Yes (JoinGroup) | Fleet group ID (body) | Valid fleet group ID |
Kubeconfig Parameters
| Parameter | Required | Description | Constraints |
|---|---|---|---|
--clusterid |
Yes | UCS cluster ID | Must be registered cluster |
--clustergroupid |
Yes (DownloadFederationKubeconfig) | Fleet group ID | Valid fleet group ID |
--duration |
Yes (DownloadFederationKubeconfig) | Token duration in seconds | Integer |
Quota Parameters
| Parameter | Required | Description | Constraints |
|---|---|---|---|
--domainid |
Yes | Account ID | Huawei Cloud account/domain ID |
ShowClusterList Filter Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
--category |
Optional | Filter by cluster category |
--clustergroupid |
Optional | Filter by fleet group ID |
--clusterids |
Optional | Filter by specific cluster IDs |
--enablestatus |
Optional | Filter by cluster status |
--managetype |
Optional | Filter by manage type |
--limit |
Optional | Pagination limit |
--offset |
Optional | Pagination offset |
--order |
Optional | Sort order (asc/desc) |
--order_by |
Optional | Sort field |
Output Format
See Output Format for detailed response format examples (ShowCluster, ShowClusterList, ShowQuota).
Key Fields Summary:
- ShowCluster:
metadata.uid(UUID),spec.category(onpremise/self),status.phase(Failed/Available) - ShowClusterList:
items[](k8s-style array),total(count) - ShowQuota:
quotas.resources[]withtype/quota/used/min/max
Verification
See Verification Method for step-by-step verification.
Best Practices
- Cluster Naming: Use descriptive names that reflect cluster purpose and environment (e.g.,
prod-app-backend,staging-data-pipeline) via--metadata.name - Fleet Grouping: Organize clusters by environment (production/staging/development) or business domain for unified governance
- Kubeconfig Security: Store kubeconfig files securely; never expose them in public repositories or CI logs
- Deregistration Caution: Removing a cluster from UCS disables all policy governance and federation access for that cluster
- Self-Managed Registration: Ensure the self-managed cluster kubeconfig is valid and the cluster API server is reachable; pass it via
--metadata.annotations.kubeconfig - Quota Monitoring: Check quotas before registering new clusters to avoid hitting limits
- Federation Kubeconfig Duration: Choose appropriate
--durationfor federation kubeconfig tokens based on usage patterns
Reference Documents
| Document | Description |
|---|---|
| UCS Cluster Onboarding API Guide | hcloud UCS API reference |
| Output Format | Response format examples (verified) |
| IAM Permission Policies | Required permissions and policy JSON |
| Verification Method | Step-by-step verification |
| Common Pitfalls | Troubleshooting guides |
| Task: Cluster Registration | Registration and deregistration workflows |
| Task: Fleet Management | Fleet group workflows |
| Task: Access Management | Kubeconfig and access control workflows |
Notes
- Cluster deregistration is irreversible — the cluster loses all UCS management capabilities
- Self-managed cluster kubeconfig must be valid — invalid kubeconfig will cause registration failure; pass via
--metadata.annotations.kubeconfig - AK/SK must never be hardcoded — credentials should only be obtained via environment variables
- hcloud CLI is the only supported method — all operations use
hcloud UCS <Operation>format - Federation kubeconfig requires fleet group ID and duration — both
--clustergroupidand--durationare required - RegisterCluster uses K8s API-style parameters — not flat params like --name/--cluster_type; note:
spec.categoryusesself/onpremise(notCCE/AttachedCluster),spec.provideruseshuaweicloud(nothuawei_cloud),spec.typeuses lowercasecce(notCCE),spec.cityuses city codes like110000(not city names likeBeijing) - ShowQuota requires domainid — the account/domain ID is a required path parameter
Common Pitfalls
See Common Pitfalls & Solutions for detailed troubleshooting guides.
Quick Reference:
| Pitfall | Symptom | Quick Fix |
|---|---|---|
| Invalid kubeconfig | Registration fails | Verify kubeconfig validity and API server reachability |
| Cluster already registered | 409 Conflict | Use ShowCluster to check existing registration |
| CCE cluster not found | 404 Not Found | Verify CCE cluster ID via --metadata.uid in same region |
| Quota exceeded | 403 Quota limit | Check quotas with ShowQuota --domainid=<account-id> |
| Fleet group already exists | 409 Conflict | Use ShowClusterGroup to check first |
| Deregistration impact | Policies stop working | Consider disabling policies before deregistration |
| Federation kubeconfig expired | Multi-cluster access fails | Re-download with DownloadFederationKubeconfig --clustergroupid=<id> --duration=N |
| Wrong parameter names | Command fails or unrecognized | Use --clusterid (not --cluster_id), --clustergroupid (not --group_id) |
| Using --name on ShowClusterList | Parameter not recognized | Use --category, --clustergroupid, --enablestatus filters instead |
| Missing domainid on ShowQuota | Missing required parameter | Provide --domainid=<account-id> |
| Missing duration on DownloadFederationKubeconfig | Missing required parameter | Provide --duration=<seconds> |