huawei-cloud-ucs-cluster-onboarding-manager

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=
export HUAWEI_CLOUD_SK=
export HUAWEI_CLOUD_REGION=cn-north-4

Mode B — Temporary AK/SK + SecurityToken (recommended for temporary or delegated access):

export HUAWEI_CLOUD_AK=
export HUAWEI_CLOUD_SK=
export HUAWEI_CLOUD_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= --spec.projectID= --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= --spec.projectID= --spec.region=cn-north-4 --spec.clusterGroupID= --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= --cli-region=cn-north-4

# Retry cluster activation (if registration stuck)
hcloud UCS RetryClusterActivation --clusterid= --cli-region=cn-north-4

# Remove a cluster from UCS
hcloud UCS DeleteCluster --clusterid= --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= --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= --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= --apiVersion=v1 --kind=Cluster --spec.city=Shanghai --spec.country=CN --cli-region=cn-north-4

# Show cluster access information
hcloud UCS ShowClusterAccessInfo --clusterid= --cli-region=cn-north-4

# Show cluster access information with optional filters
hcloud UCS ShowClusterAccessInfo --clusterid= --region=cn-north-4 --vpcendpoint= --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= --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= --cli-region=cn-north-4

# Update fleet group description
hcloud UCS UpdateClusterGroup --clustergroupid= --description="Updated fleet description" --cli-region=cn-north-4

# Add clusters to fleet group
hcloud UCS UpdateClusterGroupAssociatedClusters --clustergroupid= --clusterIds.1= --clusterIds.2= --cli-region=cn-north-4

# Add a single cluster to fleet group (join)
hcloud UCS JoinGroup --clusterid= --clusterGroupID= --cli-region=cn-north-4

# Remove a cluster from fleet group (leave)
hcloud UCS LeaveGroup --clusterid= --cli-region=cn-north-4

# Delete a fleet group
hcloud UCS DeleteClusterGroup --clustergroupid= --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= --cli-region=cn-north-4

# Create cluster configuration
hcloud UCS CreateClusterConf --clusterid= --cli-region=cn-north-4

# Download federation kubeconfig (for multi-cluster access)
hcloud UCS DownloadFederationKubeconfig --clustergroupid= --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= --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 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: