Ucs Cluster Onboarding Manager

Other

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", "纳管集群", "集群管理"

Install

openclaw skills install 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:

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

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

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

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