Huawei Cloud UCS Cluster Onboarding Manager

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:

• huawei-cloud-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 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 via environment variables, automatically detected at runtime:

Mode A — Long-term AK/SK (permanent access):

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 (recommended for temporary or delegated access):

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

When HUAWEI_CLOUD_SECURITY_TOKEN is present, hcloud CLI automatically uses temporary credential authentication. When only AK/SK are set, it uses long-term credential authentication.

• Security Rules:
  • 🚫 Never expose AK/SK/SecurityToken values in code, conversation, or commands
  • 🚫 Never use echo $HUAWEI_CLOUD_AK or echo $HUAWEI_CLOUD_SK to check credentials
  • ✅ Use environment variables: HUAWEI_CLOUD_AK, HUAWEI_CLOUD_SK, HUAWEI_CLOUD_REGION, HUAWEI_CLOUD_SECURITY_TOKEN
  • ✅ Prefer IAM users over root account for cloud operations
  • ✅ Enable MFA for sensitive operations

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

See IAM Permission Policies for complete policy JSON.

Permission Failure Handling:

1. When any command fails due to permission errors, read references/iam-policies.md
2. Display the required permission list and policy JSON to the user
3. Guide the user to create a custom policy in the IAM console and grant authorization
4. 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 cluster
• onpremise: Self-managed or third-party Kubernetes cluster

Cluster Providers (spec.provider):

• huaweicloud: Huawei Cloud managed CCE cluster
• self_managed: Self-managed Kubernetes cluster

Manage Types (spec.manageType):

• grouped: Cluster managed within a fleet group
• discrete: 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

Cluster Registration Parameters (K8s API Style)

UpdateCluster Parameters (K8s API Style)

Fleet Group Parameters

Join/Leave Group Parameters

Kubeconfig Parameters

Quota Parameters

ShowClusterList Filter Parameters

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[] with type/quota/used/min/max

Verification

See Verification Method for step-by-step verification.

Best Practices

1. Cluster Naming: Use descriptive names that reflect cluster purpose and environment (e.g., prod-app-backend, staging-data-pipeline) via --metadata.name
2. Fleet Grouping: Organize clusters by environment (production/staging/development) or business domain for unified governance
3. Kubeconfig Security: Store kubeconfig files securely; never expose them in public repositories or CI logs
4. Deregistration Caution: Removing a cluster from UCS disables all policy governance and federation access for that cluster
5. Self-Managed Registration: Ensure the self-managed cluster kubeconfig is valid and the cluster API server is reachable; pass it via --metadata.annotations.kubeconfig
6. Quota Monitoring: Check quotas before registering new clusters to avoid hitting limits
7. Federation Kubeconfig Duration: Choose appropriate --duration for federation kubeconfig tokens based on usage patterns

Reference Documents

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 --clustergroupid and --duration are required
• RegisterCluster uses K8s API-style parameters — not flat params like --name/--cluster_type; note: spec.category uses self/onpremise (not CCE/AttachedCluster), spec.provider uses huaweicloud (not huawei_cloud), spec.type uses lowercase cce (not CCE), spec.city uses city codes like 110000 (not city names like Beijing)
• ShowQuota requires domainid — the account/domain ID is a required path parameter

Common Pitfalls

See Common Pitfalls & Solutions for detailed troubleshooting guides.

Quick Reference: