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	Yes	String	Identity authentication information Minimum: 1 Maximum: 16384

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	Cluster ID
name	String	Cluster name
labels	Map<String,String>	Label
creationTimestamp	String	Creation time. It is a UTC time in the RFC 3339 format.
updateTimestamp	String	Update timestamp

**Table 6** 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

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

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

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

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

**Table 11** 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	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 12** 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 13** NodeSummary
Parameter	Type	Description
totalNum	String	Number of all nodes in a cluster
readyNum	String	Number of ready nodes in a cluster

**Table 14** 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 15** Endpoint
Parameter	Type	Description
url	String	URL
type	String	Port type
status	String	Port status

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

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

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"
      },
      "annotations" : {
        "vpcId" : "11c9fe72-5a90-4295-bcfe-774726fb9066"
      }
    },
    "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"
    },
    "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.