Updated on 2024-04-30 GMT+08:00

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.

Error Codes

See Error Codes.