Querying the Cluster List

Function

This API is used to query the cluster list.

URI

GET /v1/clusters

**Table 1** Query Parameters
Parameter	Mandatory	Type	Description
category	No	String	Cluster category
enablestatus	No	Boolean	Whether to obtain the resource information of a cluster. If this parameter is left blank or set to true, the cluster resource summary is returned. If this parameter is set to false, the cluster status information is not returned. The default value is true.
clustergroupid	No	String	Fleet ID. If this parameter is not specified, all clusters are returned. If this parameter is specified, clusters that belong to the fleet are returned.
limit	No	Integer	The number of records allowed on each page when the list is queried by page. The default value is -1.
offset	No	Integer	Start offset when the list is queried by page. The default value is 0.
order_by	No	String	Sorting parameter when the list is queried by page. The value can be create_at or update_at.
order	No	String	Sorting order when the list is queried by page. The value can be desc or asc.
managetype	No	String	Cluster type for listing the clusters. The value can be all, grouped, or discrete. If this parameter is not specified, the default value is all. grouped: clusters added to a fleet discrete: clusters not in any fleet all: all clusters
clusterids	No	String	Cluster ID. If there are multiple IDs, separate them using commas (,).

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	No	String	Identity authentication information. 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.

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
items	Array of Cluster objects	List of cluster members
total	Integer	Total number of clusters

**Table 4** Cluster
Parameter	Type	Description
kind	String	API type. The value is fixed at Cluster and cannot be changed.
apiVersion	String	API version. The value is fixed at v1 and cannot be changed.
metadata	ObjectMeta object	Basic information about a cluster. Metadata is a collection of attributes.
spec	ClusterSpec object	Detailed description of a cluster. UCS creates or updates objects by defining or updating spec.
status	ClusterStatus object	Object status

**Table 5** ObjectMeta
Parameter	Type	Description
uid	String	Resource ID
name	String	Resource name
generateName	String	If no name is provided, the server uses the prefix to generate a unique name.
namespace	String	Namespace
labels	Map<String,String>	Label
annotations	Map<String,String>	Annotation
creationTimestamp	String	Creation time
updateTimestamp	String	Update time
resourceVersion	String	Internal version of a resource
generation	String	Generation of the desired resource state
managedFields	Array of ManagedFieldsEntry objects	Fields managed by workflows
ownerReferences	Array of OwnerReference objects	Ownership, dependencies, and garbage collection mechanism of objects. It supports resource management by the controller.

**Table 6** ManagedFieldsEntry
Parameter	Type	Description
manager	String	Manager name
operation	String	Operation type that causes this entry being created. The value can only be Apply or Update.
apiVersion	String	Resource API version used by a manager for defining fields
time	String	Timestamp when this entry was created or last updated
fieldsType	String	Field structure format. The value is fixed at "FieldsV1".
fieldsV1	Object	Information about the managed fields

**Table 7** OwnerReference
Parameter	Type	Description
apiVersion	String	API version of the referent
kind	String	Type of the referent
name	String	Name of the referent
uid	String	UID of the referent
controller	Boolean	If the value is true, this reference points to the controller that manages the resource.
blockOwnerDeletion	Boolean	If the value is true and the owner has a finalizer named foregroundDeletion, the owner cannot be deleted until this reference is removed.

**Table 8** ClusterSpec
Parameter	Type	Description
syncMode	String	Synchronization mode between the cluster and the Karmada control plane
clusterGroupID	String	Fleet ID
manageType	String	Cluster type. grouped: clusters added to a fleet discrete: clusters not in any fleet
ruleNamespaces	Array of RuleNamespace objects	List of namespaces associated with permission policies in a cluster
apiEndpoint	String	API server address
secretRef	LocalSecretReference object	Secret for accessing a cluster
insecureSkipTLSVerification	Boolean	Whether to skip HTTPS verification
proxyURL	String	Proxy URL
provider	String	Provider
type	String	Type
category	String	Category
enableDistMgt	Boolean	Whether CCE Turbo clusters can manage edge infrastructure
region	String	Region
country	String	Country
city	String	City
projectID	String	Project ID
projectName	String	Project name
zone	String	Region
taints	Array of Taint objects	Taint
IsDownloadedCert	Boolean	Whether the certificate has been downloaded
policyId	String	Policy ID
operatorNamespace	String	Domain ID of the cluster
connectProxyEndpoints	Array of ConnectEndpoint objects	ID list of VPC endpoint services for connecting to the proxy server. This field is returned only for non-Huawei Cloud clusters.

**Table 9** RuleNamespace
Parameter	Type	Description
rules	Array of RuleInfo objects	Permission policy list
namespaces	Array of strings	Namespace list

**Table 10** RuleInfo
Parameter	Type	Description
ruleID	String	Permission policy ID
ruleName	String	Permission policy name

**Table 11** LocalSecretReference
Parameter	Type	Description
namespace	String	Resource namespace
name	String	Resource name

**Table 12** Taint
Parameter	Type	Description
key	String	Key
value	String	Value
effect	String	Effect information
timeadded	String	Timestamp information

**Table 13** ConnectEndpoint
Parameter	Type	Description
type	String	Currently, only VPCEP is supported.
name	String	Resource name. When type is set to VPCEP, the value is the VPCEP service name.
id	String	Resource ID. When type is set to VPCEP, the value is the VPCEP service ID.
region	String	Region where the resource is located

**Table 14** ClusterStatus
Parameter	Type	Description
kubernetesVersion	String	Kubernetes version
conditions	Array of ConditionStatus objects	Cluster conditions
nodeSummary	NodeSummary object	Node statistics
resourceSummary	ResourceSummary object	Resource statistics
endpoints	Object	Endpoint
phase	String	Phase information
reason	String	Reason of the last change
message	String	Details about the last state transition
arrearFreeze	String	Frozen due to arrears
policeFreeze	String	Frozen for legal reasons
apiEnablements	Array of APIEnablement objects	List of enabled resources

**Table 15** ConditionStatus
Parameter	Type	Description
type	String	Status type
status	String	Status
observedgeneration	Integer	Version of a status object
lastTransitionTime	String	Last status update time
reason	String	Cause of status
message	String	Status information

**Table 16** NodeSummary
Parameter	Type	Description
totalNum	Integer	Number of all nodes in a cluster
readyNum	Integer	Number of ready nodes in a cluster

**Table 17** ResourceSummary
Parameter	Type	Description
allocatable	Map<String,Object>	Allocable resources
allocating	Map<String,Object>	Resources in allocation
allocated	Map<String,Object>	Allocated resources
capacity	Map<String,Object>	Total resources

**Table 18** APIEnablement
Parameter	Type	Description
groupVersion	String	Resource group version
resources	Array of APIResource objects	Resource type and name

**Table 19** APIResource
Parameter	Type	Description
name	String	Resource name
kind	String	Resource category

Status code: 400

**Table 20** Response body parameters
Parameter	Type	Description
-	String	-

Status code: 403

**Table 21** Response body parameters
Parameter	Type	Description
-	String	-

Status code: 500

**Table 22** Response body parameters
Parameter	Type	Description
-	String	-

Example Requests

None

Example Responses

Status code: 200

All clusters are queried.

{
  "items" : [ {
    "kind" : "Cluster",
    "apiVersion" : "v1",
    "metadata" : {
      "name" : "test-cluster",
      "uid" : "b0d1ecb5-7947-11ee-9467-0255ac1001bf",
      "creationTimestamp" : "2023-11-02T06:36:14Z",
      "labels" : {
        "FeatureGates" : "elbv3,SupportClientCertificateRevocation,xGPU"
      }
    },
    "spec" : {
      "syncMode" : "",
      "clusterGroupID" : "bffbb35b-7949-11ee-886c-0255ac100037",
      "manageType" : "grouped",
      "provider" : "huaweicloud",
      "type" : "cce",
      "category" : "self",
      "region" : "cn-north-4",
      "country" : "CN",
      "city" : "150900",
      "projectID" : "b6315dd3d0ff4be5b31a963256794989",
      "projectName" : "cn-north-4",
      "IsDownloadedCert" : false,
      "operatorNamespace" : "2cd7ebd02e4743eba4e6342c09e49344",
      "connectProxyEndpoints" : [ {
        "type" : "VPCEP",
        "name" : "cn-north-4.5fc05258-f125-48f5-8a0a-a724a37f5ff1",
        "id" : "5fc05258-f125-48f5-8a0a-a724a37f5ff1",
        "region" : "cn-north-4"
      } ]
    },
    "status" : {
      "kubernetesVersion" : "v1.25",
      "conditions" : [ {
        "type" : "Ready",
        "status" : "True",
        "lastTransitionTime" : "2023-11-27T11:05:09+08:00",
        "reason" : "ClusterAvailable"
      }, {
        "type" : "Cluster",
        "status" : "Available",
        "lastTransitionTime" : "2023-11-27T11:05:09+08:00",
        "reason" : "ClusterAvailable"
      }, {
        "type" : "Federation",
        "status" : "Federalized",
        "lastTransitionTime" : "2023-11-14T14:31:58.744215+08:00"
      } ],
      "endpoints" : [ {
        "url" : "https://192.168.1.251:5443",
        "type" : "Internal"
      } ],
      "phase" : "Available",
      "arrearFreeze" : "false",
      "policeFreeze" : "false"
    }
  } ],
  "total" : 1
}

Status Codes

Status Code	Description
200	All clusters are queried.
400	Client request error. The server could not execute the request.
403	The server refused the request.
500	Internal server error.