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:

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

• Valid Huawei Cloud credentials (AK/SK mode)

• Security Rules:

  • 🚫 Never expose AK/SK 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
  • ✅ Prefer IAM users over root account for cloud operations
  • ✅ Enable MFA for sensitive operations

Configuration Method (Environment Variables Only):

bash

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 ActionPermissionPurposeucs:cluster:createRegister clusterRegister cluster to UCSucs:cluster:deleteDelete clusterRemove cluster from UCSucs:cluster:getGet clusterView cluster detailsucs:cluster:listList clustersList all managed clustersucs:cluster:updateUpdate clusterModify cluster propertiesucs:clusterGroup:createCreate groupCreate fleet groupucs:clusterGroup:deleteDelete groupRemove fleet groupucs:clusterGroup:getGet groupView fleet group detailsucs:clusterGroup:updateUpdate groupUpdate fleet group descriptionucs:clusterAccess:getGet access infoObtain cluster access informationucs:quota:getGet quotaCheck UCS resource quotasucs:kubeconfig:createCreate kubeconfigObtain cluster kubeconfigucs:federationKubeconfig:getGet federationDownload federation kubeconfig

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

bash

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

bash

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

bash

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

bash

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

bash

# Show UCS resource quotas (domainid is required - account ID)
hcloud UCS ShowQuota --domainid=<account-id> --cli-region=cn-north-4

Parameter Reference#

Common Parameters#

ParameterRequired/OptionalDescriptionDefault--cli-regionRequiredHuawei Cloud region IDConfig value or HUAWEI_CLOUD_REGION``--clusteridContext-dependentUCS cluster IDN/A--clustergroupidContext-dependentFleet group IDN/A

Cluster Registration Parameters (K8s API Style)#

ParameterRequiredDescriptionConstraints--apiVersionYesAPI version (always v1)Must be v1``--kindYesResource kind (always Cluster)Must be Cluster``--metadata.nameYesCluster display name1-128 chars--spec.categoryYesCluster categoryself or onpremise``--spec.providerYesCluster providerhuaweicloud or self_managed``--spec.typeYesCluster typecce, baremetal, Kubernetes, etc.--spec.manageTypeYesManagement typegrouped or discrete``--spec.countryYesCountry codeCountry code (e.g., CN)--spec.cityYesCity codeCity code (e.g., 110000 for Beijing)--metadata.uidCCE onlyCCE cluster IDMust reference existing CCE cluster--spec.projectIDCCE onlyProject IDValid Huawei Cloud project ID--spec.regionCCE onlyCCE cluster regionMust match CCE cluster region--metadata.annotations.kubeconfigSelf-managed onlyKubeconfig contentValid Kubernetes kubeconfig YAML--spec.clusterGroupIDNoAssign to fleet at registrationValid fleet group ID--metadata.labels.*NoCustom labelsKey-value pairs

UpdateCluster Parameters (K8s API Style)#

ParameterRequiredDescriptionConstraints--clusteridYesUCS cluster ID (path param)Must be registered cluster--apiVersionYesAPI version (always v1)Must be v1``--kindYesResource kind (always Cluster)Must be Cluster``--spec.cityNoUpdate cityCity name--spec.countryNoUpdate countryCountry code--metadata.annotationsNoUpdate annotationsKey-value pairs--spec.workerConfig.replicasNoUpdate worker replicasInteger--spec.workerConfig.strategy.*NoUpdate worker strategyK8s deployment strategy fields

Fleet Group Parameters#

ParameterRequiredDescriptionConstraints--metadata.nameYes (create)Group display name1-128 chars--spec.descriptionNo (create)Group descriptionFree text--spec.clusterIds.NNo (create)Initial cluster IDsIndexed (1, 2, 3...)--clustergroupidYes (get/delete/update)Group IDUUID format--descriptionYes (UpdateClusterGroup)New descriptionFree text--clusterIds.NYes (UpdateClusterGroupAssociatedClusters)Cluster IDs to addIndexed

Join/Leave Group Parameters#

ParameterRequiredDescriptionConstraints--clusteridYesUCS cluster ID (path)Must be registered cluster--clusterGroupIDYes (JoinGroup)Fleet group ID (body)Valid fleet group ID

Kubeconfig Parameters#

ParameterRequiredDescriptionConstraints--clusteridYesUCS cluster IDMust be registered cluster--clustergroupidYes (DownloadFederationKubeconfig)Fleet group IDValid fleet group ID--durationYes (DownloadFederationKubeconfig)Token duration in secondsInteger

Quota Parameters#

ParameterRequiredDescriptionConstraints--domainidYesAccount IDHuawei Cloud account/domain ID

ShowClusterList Filter Parameters#

ParameterRequired/OptionalDescription--categoryOptionalFilter by cluster category--clustergroupidOptionalFilter by fleet group ID--clusteridsOptionalFilter by specific cluster IDs--enablestatusOptionalFilter by cluster status--managetypeOptionalFilter by manage type--limitOptionalPagination limit--offsetOptionalPagination offset--orderOptionalSort order (asc/desc)--order_byOptionalSort 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[] 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#

DocumentDescriptionUCS Cluster Onboarding API Guidehcloud UCS API referenceOutput FormatResponse format examples (verified)IAM Permission PoliciesRequired permissions and policy JSONVerification MethodStep-by-step verificationCommon PitfallsTroubleshooting guidesTask: Cluster RegistrationRegistration and deregistration workflowsTask: Fleet ManagementFleet group workflowsTask: Access ManagementKubeconfig 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 --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:

PitfallSymptomQuick FixInvalid kubeconfigRegistration failsVerify kubeconfig validity and API server reachabilityCluster already registered409 ConflictUse ShowCluster to check existing registrationCCE cluster not found404 Not FoundVerify CCE cluster ID via --metadata.uid in same regionQuota exceeded403 Quota limitCheck quotas with ShowQuota --domainid=<account-id>Fleet group already exists409 ConflictUse ShowClusterGroup to check firstDeregistration impactPolicies stop workingConsider disabling policies before deregistrationFederation kubeconfig expiredMulti-cluster access failsRe-download with DownloadFederationKubeconfig --clustergroupid=<id> --duration=NWrong parameter namesCommand fails or unrecognizedUse --clusterid (not --cluster_id), --clustergroupid (not --group_id)Using --name on ShowClusterListParameter not recognizedUse --category, --clustergroupid, --enablestatus filters insteadMissing domainid on ShowQuotaMissing required parameterProvide --domainid=<account-id>Missing duration on DownloadFederationKubeconfigMissing required parameterProvide --duration=<seconds>