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

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

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

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

Common Pitfalls & Solutions

This document contains detailed troubleshooting guides for common issues encountered when using the Huawei Cloud UCS Cluster Onboarding Manager skill.

Pitfall 1: Invalid Kubeconfig for Self-Managed Cluster Registration

Symptom: RegisterCluster fails with InvalidKubeconfig or validation error for self-managed cluster

Root Cause: The kubeconfig YAML is malformed or missing required fields

Required Kubeconfig Fields:

• apiVersion: Must be v1
• clusters: At least one cluster entry with server URL and certificate-authority-data
• users: At least one user entry with valid credentials (token or client-certificate/client-key)
• contexts: At least one context linking cluster and user
• current-context: Must be set to an existing context name

Common Mistakes:

• ❌ Missing certificate-authority-data — cluster CA must be provided
• ❌ Expired token in user credentials — ensure the token or certificate is still valid
• ❌ Empty server field — API server URL must be a valid HTTPS endpoint
• ❌ Kubeconfig with multiple contexts but no current-context

Solution: Validate kubeconfig before registration:

kubectl --kubeconfig=<path> cluster-info

Pitfall 2: CCE Cluster ID vs UCS Cluster ID Confusion

Symptom: ShowCluster, UpdateCluster, or DeleteCluster fails with ClusterNotFound

Root Cause: Using the CCE cluster ID instead of the UCS-assigned cluster ID

Solution: After registering a cluster, use the UCS-assigned id from the registration response, NOT the original CCE cluster ID:

hcloud UCS ShowCluster --clusterid=ucs-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --cli-region=cn-north-4

❌ WRONG — Using CCE cluster ID:

hcloud UCS ShowCluster --clusterid=cce-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --cli-region=cn-north-4

To find the UCS cluster ID, use ShowClusterList and match by metadata.

Pitfall 3: Cluster Already Registered (409 Conflict)

Symptom: RegisterCluster returns 409 Conflict error

Root Cause: The same cluster has already been registered to UCS

Solution: Check existing registrations before attempting to register:

hcloud UCS ShowClusterList --category=self --managetype=grouped --cli-region=cn-north-4

If the cluster exists, either use the existing registration or deregister first.

Pitfall 4: Self-Managed Cluster API Server Unreachable

Symptom: Cluster registration succeeds but status remains Unavailable or transitions to Unavailable

Root Cause: UCS management plane cannot reach the self-managed cluster's API server

Common Causes:

• API server is behind a firewall that blocks UCS access
• API server URL uses internal IP that is not externally reachable
• Network ACL or security group rules prevent inbound connections from UCS

Solution: Ensure the cluster API server is accessible:

• Use a publicly reachable API server endpoint in the kubeconfig
• Configure firewall rules to allow UCS management plane access
• For private clusters, set up VPN or direct network connectivity between UCS and the cluster

Pitfall 5: Deregistration Disables Policy Governance

Symptom: After deregistering a cluster, policy enforcement stops working on that cluster

Root Cause: UCS policy governance depends on the cluster being registered. Deregistration removes all management capabilities including policy enforcement.

Solution: Before deregistering a cluster: 1. Review active policy instances on the cluster (use huawei-cloud-ucs-policy-governor skill) 2. Document current policy configurations 3. Consider disabling specific policies rather than deregistering the entire cluster if only policy reduction is needed

Pitfall 6: Fleet Group Name Collision

Symptom: RegisterClusterGroup returns 409 Conflict

Root Cause: A fleet group with the same name already exists in the same region

Solution: Check existing groups before creating:

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

Pitfall 7: Quota Exceeded When Registering Clusters

Symptom: RegisterCluster returns 403 Quota limit exceeded

Root Cause: UCS has cluster registration limits

Solution: Check quotas before registering new clusters:

hcloud UCS ShowQuota --domainid=<account-id> --cli-region=cn-north-4

If quota is exceeded, consider: 1. Deregister unused clusters to free quota 2. Apply for quota increase through Huawei Cloud support

Pitfall 8: Federation Kubeconfig Requires Fleet Group

Symptom: DownloadFederationKubeconfig fails or returns incomplete config

Root Cause: Federation kubeconfig requires a fleet group with at least one cluster in Available status. Both --clustergroupid and --duration are required parameters.

Solution: Create a fleet group, register clusters, then download federation kubeconfig:

hcloud UCS DownloadFederationKubeconfig --clustergroupid=<group-id> --duration=86400 --cli-region=cn-north-4

Pitfall 9: Kubeconfig Validity Period

Symptom: Previously obtained kubeconfig no longer works for kubectl access

Root Cause: UCS kubeconfig tokens have expiration periods

Solution: Regenerate kubeconfig when access fails:

hcloud UCS CreateClusterKubeconfig --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

hcloud UCS DownloadFederationKubeconfig --clustergroupid=<group-id> --duration=86400 --cli-region=cn-north-4

Pitfall 10: Region Mismatch for CCE Cluster Registration

Symptom: CCE cluster registration fails with cluster not found error

Root Cause: The --cli-region must match the region where the CCE cluster resides. Registering a CCE cluster from a different region will fail.

Solution: Ensure the region matches the CCE cluster's actual region:

hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=my-cluster --spec.category=self --spec.provider=huaweicloud --spec.type=cce --spec.manageType=grouped --spec.country=CN --spec.city=110000 --metadata.uid=<cce-id> --spec.projectID=<project-id> --spec.region=cn-north-4 --cli-region=cn-north-4

Pitfall 11: RegisterCluster Uses Kubernetes-Style Parameters

Symptom: RegisterCluster fails with parameter validation errors (e.g., "missing required parameter")

Root Cause: RegisterCluster uses Kubernetes-style structured parameters (--apiVersion, --kind, --metadata.name, --spec.category, --spec.provider, etc.), NOT simple flat parameters like --name or --cluster_type.

Common Mistakes:

• ❌ Using --name=my-cluster instead of --metadata.name=my-cluster
• ❌ Using --cluster_type=CCE instead of --spec.category=self --spec.type=cce
• ❌ Using --cluster_id=<cce-id> instead of --metadata.uid=<cce-id>
• ❌ Using --kubeconfig_file=<content> instead of --metadata.annotations.kubeconfig=<content>
• ❌ Using --spec.category=CCE (uppercase) instead of --spec.category=self (verified correct value)
• ❌ Using --spec.provider=huawei_cloud (with underscore) instead of --spec.provider=huaweicloud (no underscore)
• ❌ Using --spec.type=CCE (uppercase) instead of --spec.type=cce (lowercase)
• ❌ Using --spec.city=Beijing (city name) instead of --spec.city=110000 (city code)
• ❌ Missing required --apiVersion=v1 and --kind=Cluster
• ❌ Missing required --spec.country and --spec.city

Correct CCE Example:

hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=prod-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

Correct Self-Managed Example:

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-content> --cli-region=cn-north-4

Pitfall 12: --clusterid vs --cluster_id Confusion

Symptom: Commands fail with "unknown parameter" or parameter validation errors

Root Cause: UCS hcloud CLI uses --clusterid (no underscore), NOT --cluster_id (with underscore)

Common Mistakes:

• ❌ Using --cluster_id=<id> (with underscore)
• ✅ Using --clusterid=<id> (no underscore)

Affected Operations: ShowCluster, DeleteCluster, UpdateCluster, ShowClusterAccessInfo, CreateClusterKubeconfig, CreateClusterConf, RetryClusterActivation, JoinGroup, LeaveGroup

Pitfall 13: --clustergroupid vs --group_id Confusion

Symptom: Fleet group operations fail with "unknown parameter" or parameter validation errors

Root Cause: UCS hcloud CLI uses --clustergroupid (no underscore, different name), NOT --group_id (with underscore)

Common Mistakes:

• ❌ Using --group_id=<id> (with underscore, wrong name)
• ✅ Using --clustergroupid=<id> (no underscore, correct name)

Affected Operations: ShowClusterGroup, DeleteClusterGroup, UpdateClusterGroup, UpdateClusterGroupAssociatedClusters, DownloadFederationKubeconfig, ShowClusterList (filter parameter)

Pitfall 14: ShowQuota Requires --domainid

Symptom: ShowQuota fails with missing required parameter error

Root Cause: ShowQuota requires --domainid (account ID) as a mandatory parameter. It cannot be called without it.

Solution: Always provide the account domain ID:

hcloud UCS ShowQuota --domainid=<account-id> --cli-region=cn-north-4

To find your account ID: Log in to Huawei Cloud console → My Credentials → Account ID.

Pitfall 15: DownloadFederationKubeconfig Requires --clustergroupid and --duration

Symptom: DownloadFederationKubeconfig fails with missing required parameter error

Root Cause: Both --clustergroupid and --duration are required parameters for DownloadFederationKubeconfig. It cannot be called with only --cli-region.

Common Mistakes:

• ❌ Using DownloadFederationKubeConfig (uppercase C) instead of DownloadFederationKubeconfig (lowercase c)
• ❌ Calling without --clustergroupid
• ❌ Calling without --duration

Solution:

hcloud UCS DownloadFederationKubeconfig --clustergroupid=<group-id> --duration=86400 --cli-region=cn-north-4

Pitfall 16: Invalid RegisterCluster Parameter Values (category/provider/type/city)

Symptom: RegisterCluster fails with UCS.01000012 - Invalid request body, reason: invalid category or similar validation error

Root Cause: The UCS API uses specific enum values for spec.category, spec.provider, spec.type, and spec.city that differ from common assumptions. These values were verified through ListManagedClusters and ShowClusterList API calls.

Verified Correct Values:

Common Mistakes:

• ❌ Using --spec.category=CCE → API returns "invalid category"
• ❌ Using --spec.category=AttachedCluster → API returns "invalid category"
• ❌ Using --spec.provider=huawei_cloud (with underscore) → causes registration failure
• ❌ Using --spec.type=CCE (uppercase) → causes registration failure
• ❌ Using --spec.city=Beijing (city name) → should use city code like 110000

How to Find Correct Values: Use ListManagedClusters to view unimported clusters with their correct parameter values before registration:

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

The response includes spec.category, spec.provider, spec.type, spec.city, and spec.projectID fields that should be used exactly as-is in the RegisterCluster command.

Solution: Always use the verified parameter values:

# CCE cluster registration (verified correct)
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=my-cce-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

# Self-managed cluster registration (verified category)
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-content> --cli-region=cn-north-4

Common City Codes (for --spec.city parameter):

Common Error Response Reference

IAM Permission Policies - UCS Cluster Onboarding Manager Skill

Overview

This document declares the IAM permissions required by the Huawei Cloud UCS Cluster Onboarding Manager skill. All permissions follow the principle of least privilege.

Read-Only Operations

Write Operations (Require Additional Authorization)

Minimum Read-Only Policy (JSON)

{
  "Version": "1.1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ucs:cluster:get",
        "ucs:cluster:list",
        "ucs:clusterGroup:get",
        "ucs:clusterGroup:list",
        "ucs:clusterAccess:get",
        "ucs:quota:get"
      ],
      "Resource": ["*"]
    }
  ]
}

Full Management Policy (JSON)

{
  "Version": "1.1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ucs:cluster:get",
        "ucs:cluster:list",
        "ucs:cluster:create",
        "ucs:cluster:delete",
        "ucs:cluster:update",
        "ucs:cluster:joinGroup",
        "ucs:cluster:leaveGroup",
        "ucs:cluster:retryActivation",
        "ucs:clusterGroup:get",
        "ucs:clusterGroup:list",
        "ucs:clusterGroup:create",
        "ucs:clusterGroup:delete",
        "ucs:clusterGroup:update",
        "ucs:clusterAccess:get",
        "ucs:quota:get",
        "ucs:kubeconfig:create",
        "ucs:federationKubeconfig:get",
        "ucs:clusterConf:create"
      ],
      "Resource": ["*"]
    }
  ]
}

Permission Assignment Steps

1. Log in to Huawei Cloud IAM console: https://console.huaweicloud.com/iam/ 2. Navigate to Policies → Create Custom Policy 3. Choose JSON mode and paste the policy JSON above 4. Navigate to Users / User Groups → Authorize 5. Select the custom policy and confirm

Permission Failure Handling

When a command fails with a permission error:

1. Read this document (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 4. Pause execution and wait for user confirmation that permissions have been granted 5. Retry the failed command

UCS Cluster Onboarding Manager — Output Format

ShowCluster (Verified)

{
  "kind": "Cluster",
  "apiVersion": "v1",
  "metadata": {
    "name": "test1",
    "uid": "b1c1e9b6-65e6-11ee-8d84-0255ac1000d3",
    "creationTimestamp": "2023-10-08T14:26:39Z",
    "annotations": {
      "vpcId": ""
    }
  },
  "spec": {
    "syncMode": "Push",
    "manageType": "discrete",
    "apiEndpoint": "https://kubernetes.default.svc.cluster.local",
    "provider": "huaweicloud",
    "type": "baremetal",
    "category": "onpremise",
    "country": "CN",
    "city": "110000",
    "IsDownloadedCert": false
  },
  "status": {
    "phase": "Failed",
    "conditions": [
      {
        "type": "Ready",
        "status": "False",
        "reason": "Failed",
        "message": "currently no agents available"
      }
    ]
  }
}

Key Fields:

• metadata.uid: UCS-assigned cluster UUID (k8s format)
• metadata.name: Cluster display name
• spec.category: Cluster category (onpremise, CCE, etc.)
• spec.provider: Cluster provider (huaweicloud, self_managed, etc.)
• spec.manageType: grouped or discrete
• status.phase: Cluster phase (Failed, Available, etc.)
• status.conditions[].type: Condition types (Ready, Cluster)

ShowClusterList (Verified)

{
  "items": [
    {
      "kind": "Cluster",
      "apiVersion": "v1",
      "metadata": {
        "name": "test1",
        "uid": "b1c1e9b6-65e6-11ee-8d84-0255ac1000d3",
        "creationTimestamp": "2023-10-08T14:26:39Z"
      },
      "spec": {
        "category": "onpremise",
        "provider": "huaweicloud",
        "manageType": "discrete"
      },
      "status": {
        "phase": "Failed"
      }
    }
  ],
  "total": 1
}

Key Fields:

• items[]: Array of cluster objects (k8s-style)
• total: Total number of clusters
• Each item has metadata.name, metadata.uid, spec.*, status.phase

ShowQuota (Verified)

{
  "quotas": {
    "resources": [
      {
        "type": "cluster",
        "quota": 50,
        "used": 1,
        "unit": "",
        "min": 20,
        "max": 100
      },
      {
        "type": "clustergroup",
        "quota": 50,
        "used": 0,
        "unit": "",
        "min": 20,
        "max": 100
      },
      {
        "type": "rule",
        "quota": 50,
        "used": 0,
        "unit": "",
        "min": 20,
        "max": 100
      },
      {
        "type": "federation",
        "quota": 1,
        "used": 0,
        "unit": "",
        "min": 1,
        "max": 50
      }
    ]
  }
}

Key Fields:

• type: Resource type (cluster, clustergroup, rule, federation)
• quota: Current quota limit
• used: Current usage count
• min/max: Quota adjustment range

Task: Access Management

Overview

UCS access management covers obtaining cluster kubeconfig, accessing cluster information, and managing federation kubeconfig for multi-cluster operations. This task covers creating kubeconfig, viewing access information, and downloading federation configurations.

Operations Catalog

Workflows

W1: View Cluster Access Information

hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

With optional parameters for specific access details:

hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --region=cn-north-4 --vpcendpoint=true --cli-region=cn-north-4

Response Example [to be verified — UCS responses follow k8s-style format based on verified ShowClusterList pattern]:

The exact response format for ShowClusterAccessInfo has not been verified. Based on the verified k8s-style pattern from ShowClusterList, access info may be returned as a structured object rather than a flat JSON object. The likely fields include:

• API server endpoint address (public and/or private)
• Access type (Public, Private, Both)
• Intranet endpoint (for CCE clusters)

Key Fields (expected, format to be verified):

• API server endpoint: Cluster API server public endpoint
• Access type: Network access type (Public, Private, Both)
• Intranet endpoint: Internal network endpoint (available for CCE clusters)

Use Cases:

• Verify cluster connectivity before deploying applications
• Determine which endpoint to use (public vs private) based on network setup
• Troubleshoot access issues by checking endpoint availability

W2: Create Cluster Kubeconfig

hcloud UCS CreateClusterKubeconfig --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Response: Returns a Kubernetes kubeconfig YAML content. Save this to a file for kubectl access:

hcloud UCS CreateClusterKubeconfig --clusterid=<ucs-cluster-id> --cli-region=cn-north-4 > cluster-kubeconfig.yaml

kubectl --kubeconfig=cluster-kubeconfig.yaml get nodes

Kubeconfig Security:

• ⚠️ Never store kubeconfig in public repositories or CI logs
• ⚠️ Kubeconfig tokens have expiration periods — regenerate when access fails
• ✅ Store kubeconfig in secure, encrypted storage (e.g., secrets management tools)
• ✅ Restrict file permissions: chmod 600 cluster-kubeconfig.yaml

W3: Create Cluster Configuration

hcloud UCS CreateClusterConf --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Use Cases:

• Alternative to CreateClusterKubeconfig for obtaining cluster access details
• Provides configuration information for integration with other tools

W4: Download Federation Kubeconfig

⚠️ Note: DownloadFederationKubeconfig requires both --clustergroupid and --duration as mandatory parameters. The --clustergroupid specifies which fleet group's federation kubeconfig to download, and --duration specifies the validity period.

hcloud UCS DownloadFederationKubeconfig --clustergroupid=<group-id> --duration=86400 --cli-region=cn-north-4

Parameters:

• --clustergroupid (required): Fleet group ID for the federation kubeconfig
• --duration (required): Kubeconfig validity duration in seconds
• --cli-region (required): Region ID

Response: Returns a federation kubeconfig YAML that provides unified kubectl access to all UCS-managed clusters in the fleet group.

Federation Kubeconfig Features:

• Contains context entries for each registered cluster in the fleet group
• Enables cross-cluster operations via kubectl
• Supports workload distribution across multiple clusters

Usage:

hcloud UCS DownloadFederationKubeconfig --clustergroupid=<group-id> --duration=86400 --cli-region=cn-north-4 > federation-kubeconfig.yaml

kubectl --kubeconfig=federation-kubeconfig.yaml config get-contexts

kubectl --kubeconfig=federation-kubeconfig.yaml config use-context <context-name>

kubectl --kubeconfig=federation-kubeconfig.yaml get nodes --all-contexts

Federation Requirements:

• At least one cluster must be registered and in Available status in the fleet group
• All clusters must have valid API server connectivity
• Kubeconfig tokens may expire — regenerate periodically

W5: Validate Kubeconfig Access

After obtaining kubeconfig, verify access works:

kubectl --kubeconfig=cluster-kubeconfig.yaml cluster-info

kubectl --kubeconfig=federation-kubeconfig.yaml cluster-info

kubectl --kubeconfig=cluster-kubeconfig.yaml get nodes

Expected: Returns cluster information and node list without errors.

Common Scenarios

S1: Obtain Kubeconfig for New Cluster

hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=my-cluster --spec.category=self --spec.provider=huaweicloud --spec.type=cce --spec.manageType=grouped --spec.country=CN --spec.city=110000 --metadata.uid=<cce-id> --spec.projectID=<project-id> --spec.region=cn-north-4 --cli-region=cn-north-4

hcloud UCS ShowCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

hcloud UCS CreateClusterKubeconfig --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

kubectl --kubeconfig=<saved-kubeconfig> cluster-info

S2: Refresh Expired Kubeconfig

hcloud UCS CreateClusterKubeconfig --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

hcloud UCS DownloadFederationKubeconfig --clustergroupid=<group-id> --duration=86400 --cli-region=cn-north-4

S3: Multi-Cluster Operations with Federation Kubeconfig

hcloud UCS DownloadFederationKubeconfig --clustergroupid=<group-id> --duration=86400 --cli-region=cn-north-4 > federation.yaml

kubectl --kubeconfig=federation.yaml config get-contexts

kubectl --kubeconfig=federation.yaml --context=<cluster-context> get pods -A

for ctx in $(kubectl --kubeconfig=federation.yaml config get-contexts -o name); do
  echo "=== $ctx ==="
  kubectl --kubeconfig=federation.yaml --context=$ctx get nodes
done

S4: Secure Kubeconfig Storage for CI/CD

hcloud UCS CreateClusterKubeconfig --clusterid=<ucs-cluster-id> --cli-region=cn-north-4 > ci-kubeconfig.yaml

chmod 600 ci-kubeconfig.yaml

Task: Cluster Registration & Deregistration

Overview

UCS cluster registration (纳管) enables unified management of Kubernetes clusters — both Huawei Cloud CCE clusters and self-managed Kubernetes clusters — through the UCS platform. This task covers registering and deregistering clusters.

Operations Catalog

Workflows

W1: Register a CCE Cluster to UCS

Pre-registration Checklist: 1. Verify CCE cluster exists and is in Available status in the same region 2. Check UCS quota availability: hcloud UCS ShowQuota --domainid=<account-id> --cli-region=cn-north-4 3. Verify the cluster is not already registered: hcloud UCS ShowClusterList --category=self --managetype=grouped --cli-region=cn-north-4

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

Post-registration Verification:

hcloud UCS ShowClusterList --category=self --managetype=grouped --cli-region=cn-north-4

hcloud UCS ShowCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Expected: Cluster status transitions from Registering to Available.

W2: Register a Self-Managed Kubernetes Cluster

Pre-registration Checklist: 1. Verify kubeconfig is valid: kubectl --kubeconfig=<path> cluster-info 2. Ensure API server is reachable from UCS management plane 3. Check UCS quota availability 4. Verify kubeconfig user has sufficient RBAC permissions

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-content> --cli-region=cn-north-4

Self-Managed Cluster Requirements:

• Kubeconfig must contain valid API server URL (HTTPS, publicly reachable)
• Certificate-authority-data must be base64-encoded
• User credentials (token or client certificates) must be valid and not expired
• The cluster must be running Kubernetes version 1.19 or later

Post-registration Verification:

hcloud UCS ShowCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Expected: Cluster status transitions to Available after UCS validates connectivity.

W3: Verify Cluster Registration Status

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

hcloud UCS ShowCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Cluster Status Values:

• Registering: Cluster is being registered (initial state)
• Available: Cluster is registered and operational
• Unavailable: Cluster API server is unreachable
• Deleting: Cluster is being deregistered

W4: Retry Cluster Activation

If a cluster remains in Registering or Unavailable status after registration, retry activation:

hcloud UCS RetryClusterActivation --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Expected: Cluster status transitions from stalled state toward Available.

W5: Deregister (Remove) a Cluster from UCS

⚠️ CAUTION: Deregistration is irreversible. The cluster will lose all UCS management capabilities, including policy governance, fleet grouping, and federation access. You must re-register to restore management.

Pre-deregistration Checklist: 1. Verify no active policy instances depend on this cluster (use huawei-cloud-ucs-policy-governor skill) 2. Remove the cluster from any fleet groups 3. Confirm with the user that deregistration is intended

hcloud UCS DeleteCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Post-deregistration Verification:

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

Expected: Cluster no longer appears in the list.

W6: Bulk Registration of Multiple CCE Clusters

Register multiple CCE clusters in sequence:

hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=prod-cluster-1 --spec.category=self --spec.provider=huaweicloud --spec.type=cce --spec.manageType=grouped --spec.country=CN --spec.city=110000 --metadata.uid=<cce-id-1> --spec.projectID=<project-id> --spec.region=cn-north-4 --cli-region=cn-north-4
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=prod-cluster-2 --spec.category=self --spec.provider=huaweicloud --spec.type=cce --spec.manageType=grouped --spec.country=CN --spec.city=110000 --metadata.uid=<cce-id-2> --spec.projectID=<project-id> --spec.region=cn-north-4 --cli-region=cn-north-4
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=staging-cluster --spec.category=self --spec.provider=huaweicloud --spec.type=cce --spec.manageType=grouped --spec.country=CN --spec.city=110000 --metadata.uid=<cce-id-3> --spec.projectID=<project-id> --spec.region=cn-north-4 --cli-region=cn-north-4

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

Note: For bulk operations, check quota before starting to ensure sufficient capacity.

Common Scenarios

S1: Migrate Cluster from One UCS Instance to Another

When reorganizing UCS management, deregister from one instance and register to another:

hcloud UCS DeleteCluster --clusterid=<current-ucs-id> --cli-region=cn-north-4

hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=my-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

hcloud UCS ShowCluster --clusterid=<new-ucs-id> --cli-region=cn-north-4

S2: Re-register a Previously Deregistered Cluster

hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=re-registered-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

Note: The UCS cluster ID will be different from the previous registration. Previous policy configurations will need to be re-applied.

S3: Troubleshoot Unavailable Self-Managed Cluster

hcloud UCS ShowCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

hcloud UCS RetryClusterActivation --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

hcloud UCS DeleteCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4
hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=my-cluster --spec.category=onpremise --spec.provider=self_managed --spec.type=Kubernetes --spec.manageType=discrete --spec.country=CN --spec.city=110000 --metadata.annotations.kubeconfig=<updated-kubeconfig> --cli-region=cn-north-4

Task: Fleet Management

Overview

UCS fleet groups (集群组/舰队) provide organizational grouping for managed clusters, enabling unified policy governance and management across multiple clusters. This task covers creating, querying, and managing fleet groups.

Operations Catalog

Workflows

W1: Create a Fleet Group

Pre-creation Checklist: 1. Check UCS quota for fleet groups: hcloud UCS ShowQuota --domainid=<account-id> --cli-region=cn-north-4 2. Plan group naming and description

hcloud UCS RegisterClusterGroup --metadata.name=production-fleet --spec.description="All production clusters for unified governance" --cli-region=cn-north-4

hcloud UCS RegisterClusterGroup --metadata.name=staging-env --spec.description="Staging environment clusters" --cli-region=cn-north-4

hcloud UCS RegisterClusterGroup --metadata.name=payment-services --spec.description="Payment processing service clusters" --cli-region=cn-north-4

Post-creation Verification:

hcloud UCS ShowClusterGroup --clustergroupid=<group-id-from-response> --cli-region=cn-north-4

Expected: Returns group details with cluster_count: 0 (no clusters assigned yet).

W2: View Fleet Group Details

hcloud UCS ShowClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4

Response Fields:

• id: Fleet group UUID
• name: Group display name
• description: Group description
• cluster_count: Number of clusters in this group
• created_at/updated_at: Timestamps

W3: List Fleet Groups

hcloud UCS ListClusterGroup --limit=20 --offset=0 --cli-region=cn-north-4

Parameters:

• --limit (optional): Page size, default 20, max 100
• --offset (optional): Page offset
• --order (optional): Sort order (asc, desc)
• --order_by (optional): Sort field

W4: Add Clusters to Fleet Group

hcloud UCS JoinGroup --clusterid=<ucs-cluster-id> --clusterGroupID=<group-id> --cli-region=cn-north-4

Or add multiple clusters at once:

hcloud UCS UpdateClusterGroupAssociatedClusters --clustergroupid=<group-id> --clusterIds.1=<cluster-id-1> --clusterIds.2=<cluster-id-2> --cli-region=cn-north-4

Note: Clusters must be registered and in Available status before joining a fleet group. For grouped management, clusters should be registered with --spec.manageType=grouped.

W5: Remove a Cluster from Fleet Group

hcloud UCS LeaveGroup --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Post-removal Verification:

hcloud UCS ShowClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4

Expected: cluster_count decreases by 1.

W6: Update Fleet Group Description

hcloud UCS UpdateClusterGroup --clustergroupid=<group-id> --description="Updated description for the fleet group" --cli-region=cn-north-4

W7: Delete a Fleet Group

⚠️ CAUTION: Deleting a fleet group removes the organizational grouping. Clusters that were part of the group remain individually managed by UCS but lose the group-level policy governance association.

Pre-deletion Checklist: 1. Verify no policy instances are bound to this group (use huawei-cloud-ucs-policy-governor skill) 2. Confirm with the user that deletion is intended

hcloud UCS DeleteClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4

Post-deletion Verification:

hcloud UCS ShowClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4

Expected: Group not found error (404).

W8: Organize Clusters into Fleet Groups

Fleet groups are used for organizational grouping. Policy instances in the huawei-cloud-ucs-policy-governor skill can be bound to fleet groups for unified governance across all member clusters.

Best Practices for Fleet Group Design:

Common Scenarios

S1: Create Environment-Based Fleet Groups

hcloud UCS RegisterClusterGroup --metadata.name=production-fleet --spec.description="Production environment - strict compliance" --cli-region=cn-north-4
hcloud UCS RegisterClusterGroup --metadata.name=staging-fleet --spec.description="Staging environment - moderate compliance" --cli-region=cn-north-4
hcloud UCS RegisterClusterGroup --metadata.name=development-fleet --spec.description="Development environment - relaxed compliance" --cli-region=cn-north-4

S2: Create Business-Domain Fleet Groups

hcloud UCS RegisterClusterGroup --metadata.name=core-banking --spec.description="Core banking service clusters" --cli-region=cn-north-4
hcloud UCS RegisterClusterGroup --metadata.name=user-services --spec.description="User authentication and profile services" --cli-region=cn-north-4
hcloud UCS RegisterClusterGroup --metadata.name=data-platform --spec.description="Data analytics and ML clusters" --cli-region=cn-north-4

S3: Reorganize Fleet Groups

When organizational structure changes, restructure fleet groups:

hcloud UCS RegisterClusterGroup --metadata.name=new-prod-fleet --spec.description="Reorganized production fleet" --cli-region=cn-north-4

hcloud UCS DeleteClusterGroup --clustergroupid=<old-group-id> --cli-region=cn-north-4

S4: Audit Fleet Groups

Review all fleet groups and their associated clusters:

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

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

hcloud UCS ShowClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4

Fleet Group & Policy Governance Integration

Fleet groups serve as the organizational foundation for UCS policy governance. When creating policy instances (see huawei-cloud-ucs-policy-governor skill), you can bind them to fleet groups for consistent enforcement across all member clusters.

Typical Workflow: 1. Create fleet groups for organizational grouping 2. Register clusters and assign them to fleet groups 3. Create policy instances bound to fleet groups (via huawei-cloud-ucs-policy-governor) 4. Monitor compliance across all member clusters

UCS Cluster Onboarding API Reference Guide

Overview

This document provides API reference information for Huawei Cloud UCS (Universal Cloud Service) cluster onboarding operations using hcloud CLI. All commands follow the standard format: hcloud UCS <Operation> --param=value --cli-region=<region>.

Authentication

Environment Variables

export HUAWEI_CLOUD_AK=<your-ak>
export HUAWEI_CLOUD_SK=<your-sk>

hcloud CLI Configuration

hcloud configure

hcloud configure list

✅ Correct: Use hcloud configure list to verify credentials ❌ Incorrect: Never use echo $HUAWEI_CLOUD_AK to check credentials

RegisterCluster — Kubernetes-Style Parameters

⚠️ Important: RegisterCluster uses Kubernetes-style (structured) parameters, NOT simple flat parameters. The command follows the pattern of a Kubernetes resource manifest with --apiVersion, --kind, --metadata.*, and --spec.* parameters.

Required Parameters (All Cluster Types)

CCE Cluster-Specific Parameters

Self-Managed Cluster-Specific Parameters

Optional Parameters

Cluster Registration Operations

1. Register a CCE Cluster

hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=my-cce-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

Response Example (verified):

UCS API returns a simple JSON response with the cluster UID:

{
  "uid": "aabe1df4-5c1c-11f1-a7f6-0255ac10026a"
}

Key Fields:

• metadata.uid: UCS-assigned cluster UUID (different from CCE cluster ID, not flat id)
• status.phase: Initial phase is Registering, transitions to Available upon successful registration (not flat status)
• spec.category: Registered cluster category

2. Register a Self-Managed 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-content> --cli-region=cn-north-4

Self-Managed Cluster Requirements:

• The kubeconfig must be valid YAML in standard Kubernetes format
• The cluster API server must be reachable from UCS management plane
• Ensure the kubeconfig user has sufficient RBAC permissions
• Recommended: use a dedicated service account with cluster-admin or admin privileges

3. Delete (Deregister) a Cluster

hcloud UCS DeleteCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Parameters:

• --clusterid (required): UCS cluster ID (not CCE cluster ID)
• --cli-region (required): Region ID

⚠️ Warning: Deregistration removes the cluster from UCS management. All policy governance, fleet grouping, and federation access for this cluster will be disabled. This is irreversible — you must re-register to restore UCS management.

4. Retry Cluster Activation

hcloud UCS RetryClusterActivation --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Parameters:

• --clusterid (required): UCS cluster ID
• --cli-region (required): Region ID

Use Case: Retry activation when cluster status is stuck in Registering or Unavailable.

Cluster Query Operations

1. Show Cluster Details

hcloud UCS ShowCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Parameters:

• --clusterid (required): UCS cluster ID
• --cli-region (required): Region ID

Response Example [to be verified — UCS responses follow k8s-style format based on verified ShowClusterList pattern]:

UCS API returns Kubernetes-style objects, not flat JSON. Based on the verified ShowClusterList response, ShowCluster likely returns a single k8s-style Cluster object:

{
  "kind": "Cluster",
  "apiVersion": "v1",
  "metadata": {
    "name": "my-cluster",
    "uid": "b1c1e9b6-65e6-11ee-8d84-0255ac1000d3",
    "creationTimestamp": "2026-03-15T10:30:00Z",
    "annotations": {
      "vpcId": ""
    }
  },
  "spec": {
    "category": "self",
    "provider": "huaweicloud",
    "type": "cce",
    "manageType": "grouped",
    "country": "CN",
    "city": "110000",
    "syncMode": "Push",
    "apiEndpoint": "https://kubernetes.default.svc.cluster.local"
  },
  "status": {
    "phase": "Available",
    "conditions": [
      {
        "type": "Ready",
        "status": "True",
        "lastTransitionTime": "2026-05-20T14:20:00Z",
        "reason": "Available",
        "message": "Cluster is available"
      }
    ]
  }
}

2. List Managed Clusters

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

hcloud UCS ShowClusterList --limit=20 --offset=0 --cli-region=cn-north-4

hcloud UCS ShowClusterList --category=self --managetype=grouped --cli-region=cn-north-4

hcloud UCS ShowClusterList --clustergroupid=<group-id> --cli-region=cn-north-4

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

hcloud UCS ListManagedClusters --unimported --cli-region=cn-north-4

ShowClusterList Parameters:

• --cli-region (required): Region ID
• --limit (optional): Page size, default 20, max 100
• --offset (optional): Page offset
• --category (optional): Filter by cluster category (self, onpremise)
• --managetype (optional): Filter by management type (grouped, discrete)
• --clustergroupid (optional): Filter by fleet group ID
• --clusterids (optional): Filter by specific cluster IDs
• --enablestatus (optional): Filter by enable status
• --order (optional): Sort order (asc, desc)
• --order_by (optional): Sort field

⚠️ Note: ShowClusterList does NOT support --name as a filter parameter. Use --category, --managetype, or --clustergroupid for filtering.

Response Example (verified):

{
  "items": [
    {
      "kind": "Cluster",
      "apiVersion": "v1",
      "metadata": {
        "name": "test1",
        "uid": "b1c1e9b6-65e6-11ee-8d84-0255ac1000d3",
        "creationTimestamp": "2023-10-08T14:26:39Z",
        "annotations": {
          "vpcId": ""
        }
      },
      "spec": {
        "syncMode": "Push",
        "manageType": "discrete",
        "apiEndpoint": "https://kubernetes.default.svc.cluster.local",
        "provider": "huaweicloud",
        "type": "baremetal",
        "category": "onpremise",
        "country": "CN",
        "city": "110000",
        "IsDownloadedCert": false,
        "operatorNamespace": "05949eb4190010e40f36c017b62fafa0"
      },
      "status": {
        "conditions": [
          {
            "type": "Ready",
            "status": "False",
            "lastTransitionTime": "2023-10-09T22:27:05.907728+08:00",
            "reason": "Failed",
            "message": "currently no agents available"
          }
        ],
        "phase": "Failed"
      }
    }
  ],
  "total": 1
}

Key Fields:

• items: Array of k8s-style Cluster objects (not flat objects)
• total: Total count of clusters (not total_count)
• metadata.uid: Cluster UUID (not flat id)
• metadata.name: Cluster display name
• spec.category: Cluster category (not flat cluster_type)
• spec.provider: Cluster provider
• spec.type: Cluster type
• spec.manageType: Management type
• status.phase: Cluster phase (Available, Failed, etc.) (not flat status)
• status.conditions: Array of status conditions with type, status, reason, message

ListManagedClusters Parameters:

• --unimported (optional): Boolean flag to list only unimported clusters

3. Update Cluster

hcloud UCS UpdateCluster --clusterid=<ucs-cluster-id> --apiVersion=v1 --kind=Cluster --spec.city=Shanghai --spec.country=CN --cli-region=cn-north-4

Parameters (Kubernetes-style):

• --clusterid (required, path): UCS cluster ID
• --apiVersion (required): Must be v1
• --kind (required): Must be Cluster
• --metadata.annotations (optional): Updated annotations
• --spec.city (optional): Updated city
• --spec.country (optional): Updated country
• --spec.workerConfig.replicas (optional): Updated worker config replicas
• --spec.workerConfig.strategy.* (optional): Updated worker config strategy
• --cli-region (required): Region ID

4. Show Cluster Access Information

hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

With optional parameters:

hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --region=cn-north-4 --vpcendpoint=true --cli-region=cn-north-4

Parameters:

• --clusterid (required): UCS cluster ID
• --region (optional): Region
• --vpcendpoint (optional): VPC endpoint flag
• --cli-region (required): Region ID

Response Example [to be verified — UCS responses follow k8s-style format based on verified ShowClusterList pattern]:

The exact response format for ShowClusterAccessInfo has not been verified. Based on the verified k8s-style pattern from ShowClusterList, access info may be returned as a structured object rather than a flat JSON object. The likely fields include:

• API server endpoint address (public and/or private)
• Access type (Public, Private, Both)
• Intranet endpoint (for CCE clusters)

Key Fields (expected, format to be verified):

• API server endpoint: Cluster API server address (field name TBD)
• Access type: Network access type (Public, Private, Both)
• Intranet endpoint: Internal network endpoint

Fleet Group Operations

1. Register Fleet Group

hcloud UCS RegisterClusterGroup --metadata.name=production-group --spec.description="All production clusters" --cli-region=cn-north-4

With initial cluster association:

hcloud UCS RegisterClusterGroup --metadata.name=production-group --spec.description="All production clusters" --spec.clusterIds.1=<cluster-id-1> --cli-region=cn-north-4

Parameters:

• --metadata.name (required): Fleet group display name (1-128 chars)
• --spec.description (optional): Group description
• --spec.clusterIds.1 (optional): Initial cluster ID to associate
• --cli-region (required): Region ID

Response Example [to be verified — UCS responses follow k8s-style format based on verified ShowClusterList pattern]:

UCS API returns Kubernetes-style objects, not flat JSON. Based on the verified k8s-style pattern from ShowClusterList, RegisterClusterGroup likely returns a k8s-style ClusterGroup object with kind, apiVersion, metadata, spec, and status fields rather than flat fields like id, name, cluster_count.

### 2. List Fleet Groups

hcloud UCS ListClusterGroup --limit=20 --offset=0 --cli-region=cn-north-4

**Parameters**:
- `--limit` (optional): Page size
- `--offset` (optional): Page offset
- `--order` (optional): Sort order
- `--order_by` (optional): Sort field
- `--cli-region` (required): Region ID

### 3. Show Fleet Group Details

hcloud UCS ShowClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4

**Parameters**:
- `--clustergroupid` (required): Fleet group ID
- `--cli-region` (required): Region ID

### 4. Update Fleet Group Description

hcloud UCS UpdateClusterGroup --clustergroupid=<group-id> --description="Updated description" --cli-region=cn-north-4

**Parameters**:
- `--clustergroupid` (required): Fleet group ID
- `--description` (optional): New description
- `--cli-region` (required): Region ID

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

Or add a single cluster:

hcloud UCS JoinGroup --clusterid=<cluster-id> --clusterGroupID=<group-id> --cli-region=cn-north-4

### 6. Remove Cluster from Fleet Group

hcloud UCS LeaveGroup --clusterid=<cluster-id> --cli-region=cn-north-4

### 7. Delete Fleet Group

hcloud UCS DeleteClusterGroup --clustergroupid=<group-id> --cli-region=cn-north-4

**Parameters**:
- `--clustergroupid` (required): Fleet group ID
- `--cli-region` (required): Region ID

⚠️ **Warning**: Deleting a fleet group removes the organizational grouping but does not deregister the clusters within it. Clusters remain individually managed by UCS.

## Kubeconfig Operations

### 1. Create Cluster Kubeconfig

hcloud UCS CreateClusterKubeconfig --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

**Parameters**:
- `--clusterid` (required): UCS cluster ID
- `--cli-region` (required): Region ID

**Response**: Returns a Kubernetes kubeconfig YAML content that can be saved to a file for `kubectl` access.

### 2. Create Cluster Configuration

hcloud UCS CreateClusterConf --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

**Parameters**:
- `--clusterid` (required): UCS cluster ID
- `--cli-region` (required): Region ID

### 3. Download Federation Kubeconfig

hcloud UCS DownloadFederationKubeconfig --clustergroupid=<group-id> --duration=86400 --cli-region=cn-north-4

**Parameters**:
- `--clustergroupid` (required): Fleet group ID
- `--duration` (required): Kubeconfig validity duration in seconds
- `--cli-region` (required): Region ID

**Response**: Returns a federation kubeconfig YAML that provides unified access to all clusters in the fleet group.

**Use Cases**:
- Multi-cluster workload distribution
- Cross-cluster resource queries
- Federation-level kubectl operations

## Quota Operations

### 1. Show UCS Quotas

hcloud UCS ShowQuota --domainid=<account-id> --cli-region=cn-north-4

**Parameters**:
- `--domainid` (required): Account ID (domain ID)
- `--cli-region` (required): Region ID

**Response Example** (verified):

{ "quotas": { "resources": [ { "type": "cluster", "quota": 50, "used": 1, "unit": "", "min": 20, "max": 100 }, { "type": "clustergroup", "quota": 50, "used": 0, "unit": "", "min": 20, "max": 100 }, { "type": "rule", "quota": 50, "used": 0, "unit": "", "min": 20, "max": 100 }, { "type": "federation", "quota": 1, "used": 0, "unit": "", "min": 1, "max": 50 } ] } }

**Key Fields**:
- `type`: Resource type (`cluster`, `clustergroup`, `rule`, `federation`) — note lowercase `clustergroup`, not `clusterGroup`
- `quota`: Maximum allowed count (not `quota_limit`)
- `used`: Current usage count
- `unit`: Unit of measurement
- `min`: Minimum quota value
- `max`: Maximum quota value

## Common Region IDs

| Region Name                    | Region ID        |
| ------------------------------ | ---------------- |
| North China - Beijing 4        | `cn-north-4`     |
| North China - Beijing 1        | `cn-north-1`     |
| East China - Shanghai 1        | `cn-east-3`      |
| East China - Shanghai 2        | `cn-east-2`      |
| South China - Guangzhou        | `cn-south-1`     |
| South China - Shenzhen         | `cn-south-4`     |
| Southwest China - Guiyang 1    | `cn-southwest-2` |
| Asia Pacific - Bangkok         | `ap-southeast-2` |
| Asia Pacific - Singapore       | `ap-southeast-1` |
| Asia Pacific - Hong Kong       | `ap-southeast-3` |
| Europe - Paris                 | `eu-west-0`      |

## Common Errors

| Error                   | Cause                       | Solution                                        |
| ----------------------- | --------------------------- | ------------------------------------------------ |
| `InvalidAccessKeyId`    | Invalid AK/SK               | Check credential configuration via `hcloud configure list` |
| `ClusterNotFound`       | Cluster does not exist      | Verify cluster ID with `ShowCluster --clusterid=<id>` |
| `ClusterAlreadyRegistered` | Cluster already in UCS  | Use `ShowClusterList` to check existing registration |
| `QuotaExceeded`         | Resource quota limit        | Check quotas with `ShowQuota --domainid=<account-id>` |
| `InvalidKubeconfig`     | Invalid kubeconfig format   | Verify kubeconfig is valid YAML with correct structure |
| `GroupNotFound`         | Fleet group does not exist  | Verify group ID with `ShowClusterGroup --clustergroupid=<id>` |
| `GroupAlreadyExists`    | Fleet group name conflict   | Check with `ListClusterGroup` first             |
| `RequestLimitExceeded`  | Too many requests           | Add delay between batch requests                 |
| `MissingDomainId`       | ShowQuota missing domainid  | Provide `--domainid=<account-id>` parameter     |
| `MissingRequiredParams` | Missing required k8s-style params | Provide all required `--apiVersion`, `--kind`, `--metadata.name`, `--spec.*` parameters; note `spec.category` uses `self`/`onpremise` (not `CCE`/`AttachedCluster`) |
| `InvalidCategory`       | Invalid spec.category value         | Use `self` for CCE clusters, `onpremise` for self-managed clusters (not `CCE`/`AttachedCluster`) |
| `InvalidProvider`       | Invalid spec.provider value         | Use `huaweicloud` for CCE clusters (not `huawei_cloud`) |
| `InvalidType`           | Invalid spec.type value             | Use lowercase `cce` for CCE clusters (not uppercase `CCE`) |
| `InvalidCity`           | Invalid spec.city value             | Use city codes like `110000` (not city names like `Beijing`) |

## Related Documentation

- [Huawei Cloud UCS Documentation](https://support.huaweicloud.com/ucs/index.html)
- [hcloud CLI Documentation](https://support.huaweicloud.com/cli/index.html)
- [Huawei Cloud API Explorer](https://apiexplorer.developer.huaweicloud.com/)

Verification Method - UCS Cluster Onboarding Manager Skill

Overview

This document defines the verification steps for the UCS Cluster Onboarding Manager skill. Verification is divided into three levels: installation verification, configuration verification, and functional verification.

Level 1: Installation Verification

1.1 hcloud CLI Installation

1.2 hcloud CLI First Run

printf "y\n" | hcloud version

Expected: Version number displayed without error.

Level 2: Configuration Verification

2.1 Credential Configuration

✅ Correct: Use hcloud configure list to verify ❌ Incorrect: Do NOT use echo $HUAWEI_CLOUD_AK to check credentials

2.2 Connectivity Test

hcloud UCS ShowQuota --domainid=<account-id> --cli-region=cn-north-4

Expected: Returns HTTP 200 and quota information.

Level 3: Functional Verification

3.1 Cluster Listing

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

Expected: Displays list of UCS-managed clusters (may be empty).

3.2 Cluster Registration (CCE)

hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=test-verify-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

Expected: Cluster registered successfully, returns UCS cluster ID.

hcloud UCS ShowCluster --clusterid=<ucs-cluster-id-from-response> --cli-region=cn-north-4

Expected: Returns cluster details with status transitioning to Available.

3.3 Cluster Registration (Self-Managed)

hcloud UCS RegisterCluster --apiVersion=v1 --kind=Cluster --metadata.name=test-self-managed --spec.category=onpremise --spec.provider=self_managed --spec.type=Kubernetes --spec.manageType=discrete --spec.country=CN --spec.city=110000 --metadata.annotations.kubeconfig=<kubeconfig-content> --cli-region=cn-north-4

Expected: Cluster registered successfully.

3.4 Cluster Update

hcloud UCS UpdateCluster --clusterid=<ucs-cluster-id> --apiVersion=v1 --kind=Cluster --spec.city=Shanghai --cli-region=cn-north-4

Expected: Cluster updated successfully.

3.5 Fleet Group Management

hcloud UCS RegisterClusterGroup --metadata.name=test-verify-group --spec.description="Verification test group" --cli-region=cn-north-4

Expected: Fleet group created successfully, returns group ID.

hcloud UCS ShowClusterGroup --clustergroupid=<group-id-from-response> --cli-region=cn-north-4

Expected: Returns group details.

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

Expected: Returns list of fleet groups including the test group.

hcloud UCS DeleteClusterGroup --clustergroupid=<group-id-from-response> --cli-region=cn-north-4

Expected: Fleet group deleted successfully.

3.6 Kubeconfig & Access

hcloud UCS ShowClusterAccessInfo --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Expected: Returns cluster access information with API server endpoint.

hcloud UCS CreateClusterKubeconfig --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Expected: Returns kubeconfig content.

3.7 Quota Check

hcloud UCS ShowQuota --domainid=<account-id> --cli-region=cn-north-4

Expected: Returns quota information with limits and current usage.

3.8 Clean Up

hcloud UCS DeleteCluster --clusterid=<ucs-cluster-id> --cli-region=cn-north-4

Expected: Cluster deregistered successfully.

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

Expected: Test cluster no longer appears in list.

Verification Checklist