huawei-cloud-ucs-cluster-onboarding-manager

Huawei Cloud UCS (Universal Cloud Service) cluster onboarding, lifecycle, and fleet grouping management skill using hcloud CLI. Use this skill when the user wants to: (1) register self-managed or CCE clusters to UCS - register/query/remove, (2) manage cluster lifecycle - update/query/list clusters, (3) manage fleet groups - create/delete/query cluster groups, (4) obtain cluster access information and kubeconfig, (5) download federation kubeconfig for multi-cluster access, (6) check UCS resource quotas. Trigger: user mentions "UCS cluster onboarding", "UCS 集群纳管", "UCS cluster registration", "UCS 注册集群", "UCS fleet", "UCS 舰队", "UCS 集群组", "cluster group", "fleet grouping", "UCS kubeconfig", "UCS 集群接入", "UCS federation", "UCS 联邦", "UCS 配额", "cluster lifecycle", "集群生命周期", "managed clusters", "纳管集群", "集群管理"

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

bash

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

bash

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

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:

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

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

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

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>