Function

This API is used to obtain the cluster list.

URI

GET /v1/clusters

**Table 1** Query parameters
Parameter	Mandatory	Type	Description
category	No	String	Used to obtain clusters of a specific category.
enablestatus	No	Boolean	Whether to obtain the resource information of a cluster. If this parameter is not specified or set to true, the cluster resource summary information is returned. If this parameter is set to false, the cluster status 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** Parameter in the request header
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	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** Parameters in the response body
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 the cluster. Metadata is a collection of attributes.
spec	ClusterSpec object	Details about the cluster. UCS creates or updates the cluster based on spec.
status	ClusterStatus object	Cluster 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>	Labels
annotations	Map<String,String>	Annotations
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 to be 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. The options are as follows: 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 information 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 (consistent with the country)
projectID	String	Project ID
projectName	String	Project name
zone	String	Zone
taints	Array of Taint objects	Taints
IsDownloadedCert	Boolean	Whether the certificate has been downloaded
policyId	String	Policy management ID

**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	Namespace that the resource belongs to
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** ClusterStatus
Parameter	Type	Description
kubernetesVersion	String	Kubernetes version
conditions	Array of ConditionStatus objects	Conditions
nodeSummary	NodeSummary object	Node statistics
resourceSummary	ResourceSummary object	Resource statistics
endpoints	Endpoint 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 14** ConditionStatus
Parameter	Type	Description
type	String	Status type
status	String	Status
observedgeneration	Integer	Version of a status object
lastTransitionTime	String	Time of the last transition
reason	String	Cause of status
message	String	Status information

**Table 15** NodeSummary
Parameter	Type	Description
totalNum	String	The number of all nodes in a cluster
readyNum	String	The number of ready nodes in a cluster

**Table 16** ResourceSummary
Parameter	Type	Description
allocatable	map<string, object>	Allocatable resources
allocating	map<string, object>	Resources in allocation
allocated	map<string, object>	Allocated resources
capacity	map<string, object>	Total resources

**Table 17** Endpoint
Parameter	Type	Description
internal	String	Internal network address.
external	String	External network address.
external_otc	String	Endpoint of the cluster to be accessed through API Gateway.

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

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

Example Requests

None

Example Responses

Status code: 200

Information about all clusters is obtained.

{
  "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"
      },
      "annotations" : {
        "vpcId" : "11c9fe72-5a90-4295-bcfe-774726fb9066"
      }
    },
    "spec" : {
      "syncMode" : "",
      "clusterGroupID" : "bffbb35b-7949-11ee-886c-0255ac100037",
      "manageType" : "grouped",
      "provider" : "cmccloud",
      "type" : "cce",
      "category" : "self",
      "region" : "cidc-rp-12",
      "country" : "CN",
      "city" : "150900",
      "projectID" : "b6315dd3d0ff4be5b31a963256794989",
      "projectName" : "cidc-rp-12",
      "IsDownloadedCert" : false,
      "operatorNamespace" : "2cd7ebd02e4743eba4e6342c09e49344"
    },
    "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	Information about all clusters is obtained.
400	Client request error. The server could not execute the request.
403	The server refused the request.
500	Internal server error.

Error Codes

See Error Codes.

Obtaining the Cluster List

Function

URI

Request Parameters

Response Parameters

Example Requests

Example Responses

Status Codes

Error Codes