Huawei Cloud UCS Cluster Onboarding Manager

Overview

This skill provides cluster onboarding, lifecycle, and fleet grouping management capabilities for Huawei Cloud UCS (Ubiquitous Cloud Native 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. K8s Version Compatibility (CRITICAL)

⚠️ UCS has a maximum supported Kubernetes version limit. CCE clusters created with default settings may use a version that exceeds UCS support range. Registering an unsupported version will fail with error

UCS.01030012: Register cce cluster error - cce cluster version not support in UCS service

(verified: CCE default creates v1.35, UCS supports up to v1.34 as of 2025-07). Always query the supported versions dynamically — do not hardcode version numbers, as UCS updates its support range over time:

bash

hcloud UCS ListRegisteredClusterVersions --cli-region=cn-north-4

Pre-registration Version Check:

bash

# List unimported CCE clusters to check their versions
hcloud UCS ListManagedClusters --unimported=true --cli-region=cn-north-4

# Or check specific CCE cluster version via CCE API
hcloud CCE ShowCluster --clusterid=<cce-cluster-id> --cli-region=cn-north-4

If the cluster K8s version exceeds UCS support range, either:

Downgrade the CCE cluster K8s version to within UCS support range, OR
Wait for UCS to support the newer version

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

bash

# Register a CCE cluster to UCS (⚠️ paid service: requires user confirmation)
# **Confirm with user before executing** — UCS cluster onboarding is a paid service, costs will be incurred
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=prod-backend-cluster --spec.category=self --spec.provider=huaweicloud --spec.type=turbo --spec.manageType=discrete --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=turbo --spec.manageType=discrete --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 (⚠️ destructive: requires user confirmation)
# **Confirm with user before executing** — deregistration is irreversible
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
- UCS directly accesses CCE API via internal network — no proxy-agent needed
- Use CCE API
```
CreateKubernetesClusterCert
```
  to obtain kubeconfig (NOT UCS
```
CreateClusterKubeconfig
```
  )
- ```
ShowClusterAccessInfo
```
  returns
```
UCS.01030011
```
  — NOT supported for this category
- ```
RetryClusterActivation
```
  returns
```
UCS.01000011
```
  — NOT supported for this category
- Note: CCE cluster
```
spec.category
```
  is
```
Turbo
```
  , but UCS
```
ListManagedClusters
```
  returns
```
category=self
```
  ,
```
type=turbo
```
```
onpremise
```
: Self-managed or third-party Kubernetes cluster
- Requires deploying proxy-agent to establish tunnel between cluster and UCS
- Use
```
ShowClusterAccessInfo
```
  to obtain proxy-agent configuration, then deploy proxy-agent
- Use
```
CreateClusterKubeconfig
```
  to obtain kubeconfig after proxy-agent is running

Kubeconfig Retrieval Decision Tree (verified via API testing):

Need cluster kubeconfig?
├── category=self (CCE cluster)
│   └── CCE CreateKubernetesClusterCert --cluster_id=<cce-cluster-id> --duration=30
│       (CCE API, NOT UCS CreateClusterKubeconfig which returns internal error)
└── category=onpremise (self-managed cluster)
    ├── Step 1: ShowClusterAccessInfo --clusterid=<ucs-cluster-id>
    │   (obtain proxy-agent configuration — only for onpremise, returns UCS.01030011 for CCE)
    ├── Step 2: Deploy proxy-agent in the cluster
    └── Step 3: CreateClusterKubeconfig --clusterid=<ucs-cluster-id>
        (obtain kubeconfig after tunnel established)

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)
# ⚠️ Prerequisite: ListManagedClusters requires IAM agency delegation configured at account level.
# If not configured, returns UCS.01010005: get IAM agency's token error.
# See references/common-pitfalls.md Pitfall 20 for IAM agency setup instructions.
hcloud UCS ListManagedClusters --cli-region=cn-north-4
hcloud UCS ListManagedClusters --unimported=true --cli-region=cn-north-4

# Update cluster properties (K8s API-style params) (⚠️ modification: requires user confirmation)
# **Confirm with user before executing**
hcloud UCS UpdateCluster --clusterid=<ucs-cluster-id> --apiVersion=v1 --kind=Cluster --spec.city=310000 --spec.country=CN --cli-region=cn-north-4

# Show cluster access information (only for category=onpremise clusters)
hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

# Show cluster access information with optional filters (only for category=onpremise clusters)
hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --region=cn-north-4 --vpcendpoint=<vpc-id> --cli-region=cn-north-4

⚠️ ShowClusterAccessInfo only applies to
category=onpremise
clusters. For
category=self
(CCE) clusters, it returns
UCS.01030011: Cluster category not supported
(verified). For CCE cluster kubeconfig, use CCE API
CreateKubernetesClusterCert
instead of UCS
CreateClusterKubeconfig
.

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

⚠️ --name
filter is NOT supported by ShowClusterList API. To find a cluster by name, call
ShowClusterList
without name filter and match by
metadata.name
in the response locally.

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 (⚠️ modification: requires user confirmation)
# **Confirm with user before executing**
hcloud UCS UpdateClusterGroup --clustergroupid=<group-id> --description="Updated fleet description" --cli-region=cn-north-4

# Add clusters to fleet group (⚠️ modification: requires user confirmation)
# **Confirm with user before executing**
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 (⚠️ destructive: requires user confirmation)
# **Confirm with user before executing** — deletion removes the group but clusters remain registered
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 (⚠️ only for category=onpremise clusters)
# For category=self (CCE) clusters, use: hcloud CCE CreateKubernetesClusterCert --cluster_id=<cce-id> --duration=30 --cli-region=cn-north-4
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

参数确认

⚠️ Cost Notice: UCS cluster onboarding is a paid service. Registering a cluster to UCS incurs costs. Before executing
RegisterCluster
or other onboarding operations, you must confirm with the user whether they agree to incur costs and obtain explicit consent before proceeding.

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
`--spec.category`	Yes	Cluster category	`self` (CCE) or `onpremise` (self-managed)
`--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`
`--metadata.uid`	CCE only	CCE cluster ID	Must reference existing CCE cluster
`--spec.projectID`	CCE only	Project ID	Obtain via `ListManagedClusters` response
`--spec.clusterGroupID`	No	Assign to fleet at registration	Valid fleet group ID

Write Operations (User Confirmation Required)

Operation	CLI Command	Risk Level	Confirmation Required
`RegisterCluster`	`hcloud UCS RegisterCluster`	High	UCS onboarding is a paid service; after registration, the cluster will be subject to UCS policy governance constraints. Confirm cluster name, category, and billing consent.
`DeleteCluster`	`hcloud UCS DeleteCluster`	High	Deregistration is irreversible; the cluster loses all UCS management capabilities, policy governance, and fleet association. Confirm cluster ID before proceeding.
`UpdateCluster`	`hcloud UCS UpdateCluster`	Medium	Modifies cluster properties (e.g., location, labels). Confirm the changes before proceeding.
`RegisterClusterGroup`	`hcloud UCS RegisterClusterGroup`	Medium	Creates a new fleet group for cluster organization. Confirm group name and description.
`DeleteClusterGroup`	`hcloud UCS DeleteClusterGroup`	High	Deletes the fleet group; clusters remain registered but lose group-level governance and federation access. Confirm group ID before proceeding.
`UpdateClusterGroup`	`hcloud UCS UpdateClusterGroup`	Medium	Modifies fleet group description. Confirm the new description.
`JoinGroup`	`hcloud UCS JoinGroup`	Medium	Joining a fleet group affects the cluster's governance scope and policy execution. Confirm cluster ID and target group ID.
`LeaveGroup`	`hcloud UCS LeaveGroup`	Medium	Leaving a fleet group affects the cluster's governance scope and policy execution; the cluster will no longer be governed by group-level policies. Confirm cluster ID.

See Parameter Reference for complete parameter tables.

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

Workflow

The skill workflow is as follows:

Environment Check — Verify hcloud CLI is installed and AK/SK credentials are configured (see CLI Installation Guide)
Version Compatibility Check — Call
```
ListRegisteredClusterVersions
```
to get the list of K8s versions supported by UCS, and confirm the target cluster version is in the list
Cluster Registration — Choose registration method based on cluster type:
- CCE cluster:
```
--spec.category=self --spec.provider=huaweicloud --spec.type=turbo
```
- Self-managed cluster:
```
--spec.category=onpremise --spec.provider=self_managed
```
  (requires kubeconfig)
Registration Verification — Call
```
ShowCluster
```
or
```
ShowClusterList
```
to confirm cluster status is
```
Available
```
Cluster Management (optional):
- Fleet grouping:
```
RegisterClusterGroup
```
  /
```
JoinGroup
```
  /
```
LeaveGroup
```
- Access management: CCE clusters use
```
CreateKubernetesClusterCert
```
  , third-party clusters use
```
ShowClusterAccessInfo
```
  + proxy-agent
- Property update:
```
UpdateCluster
```
  (requires user confirmation)
Deregister Cluster (optional) —
```
DeleteCluster
```
(⚠️ irreversible operation, requires user confirmation)

KooCLI Command Format Standard

All operations use

hcloud UCS <Operation> --<param>=<value> --cli-region=<region>

format. See KooCLI Command Format for detailed examples and parameter naming rules.

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
CLI Installation Guide	hcloud CLI installation and configuration
Parameter Reference	Complete parameter tables for all operations
KooCLI Command Format	Command format standard and examples
Acceptance Criteria	Skill acceptance criteria and test checklist

Notes

K8s version compatibility — UCS has a maximum supported K8s version that updates over time. CCE default cluster version may exceed this limit. Query supported versions with
```
hcloud UCS ListRegisteredClusterVersions
```
and verify cluster version is in the list before registration.
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.

huawei-cloud-ucs-cluster-onboarding-manager

NPX Install

Tags

SKILL.md Content

Huawei Cloud UCS Cluster Onboarding Manager

Overview

Prerequisites

1. hcloud CLI Requirements (MANDATORY)

2. Credential Configuration

3. K8s Version Compatibility (CRITICAL)

4. IAM Permission Requirements

Core Commands

1. Cluster Registration & Deregistration

2. Cluster Query & Lifecycle

3. Fleet Group Management

4. Kubeconfig & Access Management

5. Quota Management

参数确认

Common Parameters

Cluster Registration Parameters (K8s API Style)

Write Operations (User Confirmation Required)

Output Format

Verification

Best Practices

Workflow

KooCLI Command Format Standard

Reference Documents

Notes

Common Pitfalls