Obtaining Clusters in a Project

Function

This API is used to obtain details about all clusters in a project.

Calling Method

For details, see Calling APIs.

URI

GET /autopilot/v3/projects/{project_id}/clusters

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the value, see How to Obtain Parameters in the API URI.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
detail	No	String	Obtains details about a cluster. If this parameter is set to true, the add-on name (addonTemplateName), version (version), and status (status) from the list of installed add-ons in the cluster are obtained and added to the annotation.
status	No	String	Cluster status. Options: Available: The cluster is running properly. Unavailable: The cluster is exhibiting unexpected behavior and needs to be manually deleted. ScalingUp: Nodes are being added to the cluster. ScalingDown: The cluster is being downsized to fewer nodes. Creating: The cluster is being created. Deleting: The cluster is being deleted. Upgrading: The cluster is being upgraded. Resizing: Cluster specifications are being changed. ResizeFailed: Cluster specification changing is abnormal. RollingBack: The cluster is being rolled back. RollbackFailed: The cluster rollback is abnormal. Hibernating: The cluster is being hibernated. Hibernation: The cluster is in hibernation. Freezing: The cluster is being frozen. Frozen: The cluster has been frozen. UnFreezing: The cluster is being unfrozen. Awaking: The cluster is being woken up from hibernation. Empty: The cluster does not have any resources. This field is discarded. Error: Resources in the cluster are abnormal. You can manually delete the cluster.
type	No	String	Cluster type. Options: VirtualMachine: CCE cluster
version	No	String	Obtains the version of a cluster.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	Message body type (format).
X-Auth-Token	Yes	String	Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token. For details, see Obtaining a User Token.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
kind	String	Api type
apiVersion	String	API version
items	Array of AutopilotCluster objects	A list of details for all clusters in the current project. You can find the corresponding clusters based on the value of items.metadata.name.

**Table 5** AutopilotCluster
Parameter	Type	Description
kind	String	API type. The value is fixed at Cluster or cluster and cannot be changed.
apiVersion	String	API version. The value is fixed at v3 and cannot be changed.
metadata	AutopilotClusterMetadata object	Basic information about a cluster. Metadata is a collection of attributes.
spec	AutopilotClusterSpec object	Element type of the collection class. The main part of a cluster object to be managed is in spec. CCE creates or updates objects by defining or updating spec.
status	AutopilotClusterStatus object	Element type of the collection class, which is used to record the statuses of an object in the system, including the cluster status and the ID of the cluster creation job

**Table 6** AutopilotClusterMetadata
Parameter	Type	Description
name	String	Cluster name. Enter 4 to 128 characters starting with a lowercase letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed.
uid	String	Cluster ID, which uniquely identifies a resource. The value is automatically generated after the object is created. A custom value will not take effect. When you create a yearly/monthly cluster, no cluster ID will be returned in the response body.
alias	String	Alias of a cluster name displayed on the CCE console, and the name can be changed. Enter 4 to 128 characters starting with a lowercase letter and not ending with a hyphen (-). Only lowercase letters, digits, and hyphens (-) are allowed. A cluster alias must be unique. In the request body for creating or updating a cluster, if the cluster alias is not specified or is left blank, the alias of the cluster is the same as the cluster name. In the response body for creating a cluster, if the cluster alias is not configured, the cluster alias will not be returned.
annotations	Map<String,String>	Cluster annotations in the format of key-value pairs. "annotations": { "key1" : "value1", "key2" : "value2" } NOTE: Annotations are not used to label or select objects. The metadata in annotations may be small or large, structured or unstructured, and may include characters that are not allowed in labels. This field is not stored in the database and is used only to specify the add-ons to be installed in the cluster.
labels	Map<String,String>	Cluster labels in the format of key-value pairs. NOTE: The value of this field is automatically generated by the system and is used by the frontend to identify the features supported by a cluster during the upgrade. Customized values are invalid.
creationTimestamp	String	Time when a cluster was created
updateTimestamp	String	Time when a cluster was updated

**Table 7** AutopilotClusterSpec
Parameter	Type	Description
category	String	Cluster type. Only Turbo is supported.
type	String	Master node architecture. VirtualMachine: The master node is an x86 server.
flavor	String	Cluster specifications: cce.autopilot.cluster
version	String	Version of a cluster, which mirrors the baseline version of the Kubernetes community. The latest version is recommended. You can create clusters of the latest three versions on the CCE console. To learn which cluster versions are available, log in to the CCE console, create a cluster, and check supported cluster versions. You can call APIs to create clusters of other versions. However, these cluster versions will be gradually terminated. For details about the support policy, see the CCE announcement. NOTE: If not specified, a cluster of the latest version will be created.
platformVersion	String	CCE cluster platform version, which is an internal version under the cluster version (version). Platform versions are used to trace iterations in a major cluster version. They are unique within a major cluster version and recounted when the major cluster version changes. This parameter cannot be customized, and when you create a cluster, the latest corresponding platform version is selected automatically. The format of platformVersion is cce.X.Y. X: internal feature version, which indicates changes in features, patches, or OS support in the cluster version. The value starts from 1 and increases monotonically. Y: patch version of an internal feature version. It is used only for software package update after the feature version is released. No other modification is involved. The value starts from 0 and increases monotonically.
description	String	Cluster description, for example, which purpose the cluster is intended to serve. By default, this field is left blank. To modify cluster description after a cluster is created, call the API for updating a specified cluster or go to the cluster details page on the CCE console. Only UTF-8 encoding is supported.
customSan	AutopilotCustomSan object	The custom SAN field in the API server certificate of a cluster. It complies with the format specifications defined by the SSL standard X509. It is not supported by Autopilot clusters. Duplicate names are not allowed. The format must comply with the IP address and domain name formats. Example: SAN 1: DNS Name=example.com SAN 2: DNS Name=www.example.com SAN 3: DNS Name=example.net SAN 4: IP Address=93.184.216.34
enableSnat	Boolean	Whether SNAT is configured for a cluster. This parameter is used and returned only by the Autopilot cluster creation API. After this function is enabled, the cluster can access the Internet through a NAT gateway. By default, the existing NAT gateway in the selected VPC is used. Otherwise, the system automatically creates a NAT gateway of the default specifications, binds an EIP to the NAT gateway, and configures SNAT rules.
enableSWRImageAccess	Boolean	Whether a cluster is interconnected with SWR. This parameter is used and returned only by the Autopilot cluster creation API. To ensure that your cluster nodes can pull images from SWR, the existing SWR and OBS endpoints in the selected VPC are used by default. If not, new SWR and OBS endpoints will be automatically created.
enableAutopilot	Boolean	Whether the cluster is an Autopilot cluster
ipv6enable	Boolean	Whether a cluster uses the IPv6 mode. This parameter is not supported by Autopilot clusters.
hostNetwork	AutopilotHostNetwork object	Node networking parameters, including VPC and subnet ID. This field is mandatory because nodes in a cluster communicate with each other using a VPC.
containerNetwork	AutopilotContainerNetwork object	Container networking parameters, including the container network model and container CIDR block
eniNetwork	AutopilotEniNetwork object	Cloud Native 2.0 network settings
serviceNetwork	AutopilotServiceNetwork object	Service CIDR block, including IPv4 CIDR block
authentication	AutopilotAuthentication object	Configurations of the cluster authentication mode
billingMode	Integer	Cluster billing mode 0: pay-per-use This parameter defaults to pay-per-use.
kubernetesSvcIpRange	String	Service CIDR block or the IP address range which the kubernetes clusterIP must fall within. If this parameter is not specified during cluster creation, the default value 10.247.0.0/16 is used. This parameter is being deprecated, so you can use serviceNetwork instead. The new field contains the IPv4 CIDR blocks.
clusterTags	Array of AutopilotResourceTag objects	Cluster resource tags
kubeProxyMode	String	Service forwarding mode. iptables: Traditional kube-proxy uses iptables rules to implement Service load balancing. In this mode, too many iptables rules will be generated when many Services are deployed. In addition, non-incremental updates will cause latency and even tangible performance issues in the case of service traffic spikes. NOTE: iptables is used by default.
az	String	AZ. This field is returned only for a query. For details about AZs supported by CCE, see Regions and Endpoints.
extendParam	AutopilotClusterExtendParam object	Extended field to decide whether a cluster will span across AZs or belong to a specified enterprise project, or whether a dedicated CCE cluster is to be created
configurationsOverride	Array of AutopilotPackageConfiguration objects	Overrides the default component configurations in a cluster. It is not supported in CCE Autopilot clusters.

**Table 8** AutopilotCustomSan
Parameter	Type	Description
[items]	Array of strings	The custom SAN field in the API server certificate of a cluster. It complies with the format specifications defined by the SSL standard X509. It is not supported by Autopilot clusters. Duplicate names are not allowed. The format must comply with the IP address and domain name formats. Example: SAN 1: DNS Name=example.com SAN 2: DNS Name=www.example.com SAN 3: DNS Name=example.net SAN 4: IP Address=93.184.216.34

**Table 9** AutopilotHostNetwork
Parameter	Type	Description
vpc	String	ID of the VPC used to create a master node. Obtain the value using either of the following methods: Method 1: Log in to the VPC console and view the VPC ID on the VPC details page. Method 2: Use the VPC API. For details, see Querying VPCs.
subnet	String	Network ID of the subnet used to create a master node. Obtain the value using either of the following methods: Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page. Method 2: Use the VPC API to obtain subnets. For details, see Querying Subnets.

**Table 10** AutopilotContainerNetwork
Parameter	Type	Description
mode	String	Container network type eni*: specifies the Cloud Native 2.0 network model. This model has integrated cloud native elastic network interfaces (ENIs), uses VPC CIDR blocks to allocate container IP addresses, and supports ELB passthrough networking for high network performance. Use this model when creating a cluster.

**Table 11** AutopilotEniNetwork
Parameter	Type	Description
subnets	Array of AutopilotNetworkSubnet objects	IPv4 subnet ID list of the subnet where an ENI resides. Obtain the value using either of the following methods: Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the IPv4 subnet ID on the displayed page. Method 2: Use the VPC API to obtain subnets. For details, see Querying Subnets.

**Table 12** AutopilotNetworkSubnet
Parameter	Type	Description
subnetID	String	Specifies the IPv4 subnet ID of the subnet used to create control nodes and containers. (IPv6 is not supported.) To obtain the subnet ID, use either of the following methods: Method 1: Log in to the VPC console and click a subnet in the VPC. On the subnet details page, search for the IPv4 subnet ID. Method 2: Use the VPC API for obtaining subnets. For details, see Querying Subnets.

**Table 13** AutopilotServiceNetwork
Parameter	Type	Description
IPv4CIDR	String	Value range of the Kubernetes clusterIP IPv4 CIDR block. If this parameter is not specified during cluster creation, the default value 10.247.0.0/16 is used.

**Table 14** AutopilotAuthentication
Parameter	Type	Description
mode	String	Cluster authentication mode. The default value is rbac.

**Table 15** AutopilotResourceTag
Parameter	Type	Description
key	String	Key. Cannot be null. Max characters: 128. Use letters, digits, and spaces in UTF-8 format. Can contain the following special characters: _.:/=+-@. Cannot start with _sys_.
value	String	Value. Can be null but not the default. Max characters: 255. Use letters, digits, and spaces in UTF-8 format. Can contain the following special characters: _.:/=+-@.

**Table 16** AutopilotClusterExtendParam
Parameter	Type	Description
enterpriseProjectId	String	ID of the enterprise project that a cluster belongs to NOTE: An enterprise project can be configured only after the enterprise project function is enabled.
upgradefrom	String	Records of how a cluster is upgraded to its current version

**Table 17** AutopilotPackageConfiguration
Parameter	Type	Description
name	String	Component name
configurations	Array of AutopilotConfigurationItem objects	Component configuration items

**Table 18** AutopilotConfigurationItem
Parameter	Type	Description
name	String	Component configuration item name
value	Object	Component configuration item value

**Table 19** AutopilotClusterStatus
Parameter	Type	Description
phase	String	Cluster status. Options: Available: The cluster is running properly. Unavailable: The cluster is exhibiting unexpected behavior and needs to be manually deleted. ScalingUp: Nodes are being added to the cluster. ScalingDown: The cluster is being downsized to fewer nodes. Creating: The cluster is being created. Deleting: The cluster is being deleted. Upgrading: The cluster is being upgraded. Resizing: Cluster specifications are being changed. ResizeFailed: Cluster specification changing is abnormal. RollingBack: The cluster is being rolled back. RollbackFailed: The cluster rollback is abnormal. Hibernating: The cluster is being hibernated. Hibernation: The cluster is in hibernation. Freezing: The cluster is being frozen. Frozen: The cluster has been frozen. UnFreezing: The cluster is being unfrozen. Awaking: The cluster is being woken up from hibernation. Empty: The cluster does not have any resources. This field is discarded. Error: Resources in the cluster are abnormal. You can manually delete the cluster.
jobID	String	ID of the task associated with the current cluster status. Options: ID of the associated task returned when creating a cluster. You can use it to obtain the auxiliary tasks for creating a cluster. ID of the associated task returned when a cluster fails to be deleted or is being deleted. If this parameter is not empty, you can use the task ID to obtain the auxiliary tasks for deleting a cluster. NOTE: Tasks are short-lived. Do not use task information in scenarios such as cluster status determination.
reason	String	Why a cluster changes to the current state. This parameter is returned if the cluster is not in the Available state.
message	String	Detailed information about why a cluster changes to the current state. This parameter is returned if the cluster is not in the Available state.
endpoints	Array of AutopilotClusterEndpoints objects	Access address of kube-apiserver in a cluster
isLocked	Boolean	CBC resource locked
lockScene	String	Scenario where the CBC resource is locked
lockSource	String	Resource locked
lockSourceId	String	ID of a locked resource
deleteOption	Object	Status of the configuration to be deleted. This parameter is contained only in the response to the deletion request.
deleteStatus	Object	Information of the status to be deleted. This parameter is contained only in the response to the deletion request.

**Table 20** AutopilotClusterEndpoints
Parameter	Type	Description
url	String	Access address of kube-apiserver in a cluster
type	String	Type of the cluster access address Internal: address for internal network access External: address for external network access

Example Requests

None

Example Responses

Status code: 200

The cluster list is obtained.

{
  "kind" : "Cluster",
  "apiVersion" : "v3",
  "items" : [ {
    "kind" : "Cluster",
    "apiVersion" : "v3",
    "metadata" : {
      "name" : "test",
      "uid" : "de63df79-1de1-11ef-95a4-0255ac1007fa",
      "creationTimestamp" : "2024-05-29 17:35:40.770923 +0000 UTC",
      "updateTimestamp" : "2024-06-04 08:14:13.881756 +0000 UTC",
      "labels" : {
        "FeatureGates" : "arpOptimization,elbv3,xGPU"
      },
      "alias" : "s00648239-b003-v127"
    },
    "spec" : {
      "category" : "Turbo",
      "type" : "VirtualMachine",
      "flavor" : "cce.autopilot.cluster",
      "version" : "v1.27",
      "hostNetwork" : {
        "vpc" : "26958bf6-9ce3-4184-9e19-d793880a162b",
        "subnet" : "df93b82f-5196-43a9-a3f1-78deeab504eb"
      },
      "containerNetwork" : {
        "mode" : "eni"
      },
      "eniNetwork" : {
        "subnets" : [ {
          "subnetID" : "97205694-3537-45b6-9459-c98e9704574a"
        } ]
      },
      "serviceNetwork" : {
        "IPv4CIDR" : "10.247.0.0/16"
      },
      "authentication" : {
        "mode" : "rbac"
      },
      "billingMode" : 0,
      "kubernetesSvcIpRange" : "10.247.0.0/16",
      "kubeProxyMode" : "iptables",
      "az" : "cn-north-7c",
      "extendParam" : {
        "enterpriseProjectId" : "0",
        "upgradefrom" : ""
      }
    },
    "status" : {
      "phase" : "Available",
      "endpoints" : [ {
        "url" : "https://de63df79-1de1-11ef-95a4-0255ac1007fa.cluster.cce.cn-north-7.myhuaweicloud.com:5443",
        "type" : "Internal"
      } ]
    }
  } ]
}

SDK Sample Code

The SDK sample code is as follows.

      
       
         
         
           package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.cce.v3.region.CceRegion;
import com.huaweicloud.sdk.cce.v3.*;
import com.huaweicloud.sdk.cce.v3.model.*;


public class ListAutopilotClustersSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");
        String projectId = "{project_id}";

        ICredential auth = new BasicCredentials()
                .withProjectId(projectId)
                .withAk(ak)
                .withSk(sk);

        CceClient client = CceClient.newBuilder()
                .withCredential(auth)
                .withRegion(CceRegion.valueOf("<YOUR REGION>"))
                .build();
        ListAutopilotClustersRequest request = new ListAutopilotClustersRequest();
        try {
            ListAutopilotClustersResponse response = client.listAutopilotClusters(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}

          

        

      
     

      
       
         
         
           # coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkcce.v3.region.cce_region import CceRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkcce.v3 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]
    projectId = "{project_id}"

    credentials = BasicCredentials(ak, sk, projectId)

    client = CceClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(CceRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = ListAutopilotClustersRequest()
        response = client.list_autopilot_clusters(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)

          

        

      
     

      
       
         
         
           package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    cce "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/cce/v3"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/cce/v3/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/cce/v3/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")
    projectId := "{project_id}"

    auth := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        Build()

    client := cce.NewCceClient(
        cce.CceClientBuilder().
            WithRegion(region.ValueOf("<YOUR REGION>")).
            WithCredential(auth).
            Build())

    request := &model.ListAutopilotClustersRequest{}
	response, err := client.ListAutopilotClusters(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}

          

        

      
     