Querying the Cluster List

Updated on 2025-01-23 GMT+08:00

View PDF

Function

This API is used to query and display the cluster list and cluster status.

Debugging

You can debug this API through automatic authentication in API Explorer.

URI

GET /v1.0/{project_id}/clusters

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Parameter description: The project ID. For details about how to obtain the project ID and name, see Obtaining the Project ID and Name. Constraints: N/A Options: For details about how to obtain the project ID and name, see Obtaining the Project ID and Name. Default value: N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
start	No	Integer	Parameter description: The start value of the query. The default value is 1, indicating that the query starts from the first cluster. Constraints: N/A Options: 1-1000 Default value: 1
limit	No	Integer	Parameter description: Number of clusters to be queried. The default value is 10, indicating that the information about 10 clusters is queried at a time. Constraints: N/A Options: 1-1000 Default value: 10
datastoreType	No	String	Parameter description: Cluster engine type. Constraints: N/A Options: elasticsearch, logstash, or opensearch. Default value: This parameter has no default value. When this parameter is left blank, all types of clusters are queried.

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
totalSize	Integer	Parameter description: Number of clusters.
clusters	Array of ClusterList objects	Parameter description: List of cluster objects.

**Table 4** ClusterList
Parameter	Type	Description
datastore	ClusterListDatastore object	Parameter description: Search engine.
instances	Array of ClusterListInstances objects	Parameter description: List of node objects.
publicKibanaResp	publicKibanaRespBody object	Parameter description: Kibana public network access information.
elbWhiteList	elbWhiteListResp object	Parameter description: Public network access control information.
updated	String	Parameter description: Last modification time of a cluster. The format is ISO8601: CCYY-MM-DDThh:mm:ss.
name	String	Parameter description: Cluster name.
publicIp	String	Parameter description: Public IP address information.
created	String	Parameter description: Cluster creation time. The format is ISO8601: CCYY-MM-DDThh:mm:ss. The returned cluster list is sorted by creation time in descending order. The latest cluster is displayed at the top.
id	String	Parameter description: Cluster ID.
status	String	Parameter description: Cluster status. Options: 100: creating 200: Available 303: Unavailable, for example, due to a creation failure.
endpoint	String	Parameter description: IPv4 address and port number accessed from the cluster's private network. [If the cluster type is KooSearch, this field indicates the internal address and port number for accessing the knowledge management service.] (tag:white)
vpcId	String	Parameter description: VPC ID.
subnetId	String	Parameter description: Subnet ID
securityGroupId	String	Parameter description: Security group ID.
bandwidthSize	Integer	Parameter description: Public network bandwidth. Unit: Mbit/s
httpsEnable	Boolean	Parameter description: Communication encryption status. Options: false: Communication encryption is not enabled. true: Communication encryption is enabled.
authorityEnable	Boolean	Parameter description: Whether to enable authentication. Options: true: Authentication is enabled for the cluster. false: Authentication is disabled for the cluster.
diskEncrypted	Boolean	Parameter description: Whether disks are encrypted. Options: true: Disks are encrypted. false: Disk are not encrypted.
backupAvailable	Boolean	Parameter description: Whether the snapshot function is enabled. Options: true: The snapshot function is enabled. false: The snapshot function is disabled.
actionProgress	Object	Parameter description: Cluster behavior progress, which shows the progress of cluster creation and scaling in percentage. CREATING indicates the progress of creation.
actions	Array of strings	Parameter description: Current behavior of a cluster. REBOOTING indicates that the cluster is being restarted. GROWING indicates that the cluster is being scaled. RESTORING indicates that the cluster is being restored. SNAPSHOTTING indicates that the snapshot is being created.
enterpriseProjectId	String	Parameter description: ID of the enterprise project that a cluster belongs. If the user of the cluster has not enabled the enterprise project, the setting of this parameter is not returned.
tags	Array of ClusterListTags objects	Parameter description: Cluster tags.
failedReason	ClusterListFailedReasons object	Parameter description: Failure cause. If the cluster is in the available status, this parameter is not returned.
period	Boolean	Parameter description: Whether a cluster is billed on the yearly/monthly mode. true: The cluster is billed on the yearly/monthly mode. false: The cluster is billed on the pay-per-use mode.
bandwidthResourceId	String	Parameter description: ID of the resource accessed from the ES public network
ipv6Endpoint	String	Parameter description: IPv6 address and port number accessed from the cluster's private network.

**Table 5** ClusterListDatastore
Parameter	Type	Description
type	String	Parameter description: Cluster engine type. Options: elasticsearch, logstash, or opensearch.
version	String	Parameter description: Version of the CSS cluster engine. Options: For details, see the supported versions in Before You Start.
supportSecuritymode	Boolean	Parameter description: Whether the security mode is supported. Options: The value can be true (supported) or false (not supported).
subVersion	String	Parameter description: Cluster image version.
isEosCluster	Boolean	Parameter description: Whether the cluster image version has reached EOS. Options: true indicates that the image version has reached EOS; false indicates that the image version has not reached EOS.

**Table 6** ClusterListInstances
Parameter	Type	Description
status	String	Parameter description: Node status. Options: 100: creating 200: Available 303: Unavailable, for example, due to a creation failure.
type	String	Parameter description: Type of the current node.
id	String	Parameter description: Instance ID.
name	String	Parameter description: Instance name.
specCode	String	Parameter description: Node flavor name.
azCode	String	Parameter description: AZ of a node.
ip	String	Parameter description: Instance IP address.
volume	ClusterVolumeRsp object	Parameter description: Instance disk information.
resourceId	String	Parameter description: Instance resource ID.

**Table 7** ClusterVolumeRsp
Parameter	Type	Description
type	String	Parameter description: Instance disk type.
size	Integer	Parameter description: Instance disk size.
resourceIds	Array of strings	Parameter description: Instance disk resource ID.

**Table 8** publicKibanaRespBody
Parameter	Type	Description
eipSize	Integer	Bandwidth range. Unit: Mbit/s
elbWhiteListResp	kibanaElbWhiteListResp object	Parameter description: Kibana public network access control information.
publicKibanaIp	String	Parameter description: Specifies the IP address for accessing Kibana.
bandwidthResourceId	String	Parameter description: Resource ID corresponding to the Kibana public network

**Table 9** kibanaElbWhiteListResp
Parameter	Type	Description
enableWhiteList	Boolean	Whether to enable Kibana access control. Options: true: Access control is enabled. false: Access control is disabled.
whiteList	String	Parameter description: Whitelist for Kibana public network access.

**Table 10** elbWhiteListResp
Parameter	Type	Description
enableWhiteList	Boolean	Parameter description: Whether to enable public network access control. Options: true: Public network access control is enabled. false: Public network access control is disabled.
whiteList	String	Parameter description: Whitelist for public network access.

**Table 11** ClusterListTags
Parameter	Type	Description
key	String	Parameter description: Tag key.
value	String	Parameter description: Tag value.

**Table 12** ClusterListFailedReasons
Parameter	Type	Description
errorCode	String	Parameter description: Error code. Options: CSS.6000: A cluster fails to be created. CSS.6001: A cluster fails to be scaled out. CSS.6002: A cluster fails to be restarted. CSS.6004: A node fails to be created in a cluster. CSS.6005: A service fails to be initialized.
errorMsg	String	Parameter description: Error details.

Example Requests

Query the first two clusters.

- Method 1: GET https://{Endpoint}/v1.0/6204a5bd270343b5885144cf9c8c158d/clusters?start=1&limit=2- Method 2: GET https://{Endpoint}/v1.0/6204a5bd270343b5885144cf9c8c158d/clusters?limit=2

Query the first ten clusters.

- Method 1: GET https://{Endpoint}/v1.0/6204a5bd270343b5885144cf9c8c158d/clusters?start=1&limit=10- Method 2: GET https://{Endpoint}/v1.0/6204a5bd270343b5885144cf9c8c158d/clusters?limit=10

Example Responses

Status code: 200

Request succeeded.

{
  "totalSize" : 1,
  "clusters" : [ {
    "datastore" : {
      "type" : "elasticsearch",
      "version" : "7.10.2",
      "subVersion" : "7.10.2_24.3.0_0827",
      "isEosCluster" : false,
      "supportSecuritymode" : false
    },
    "instances" : [ {
      "status" : "200",
      "type" : "ess",
      "id" : "{INSTANCE_ID}",
      "name" : "css-8bc5-ess-esn-1-1",
      "specCode" : "ess.spec-4u8g",
      "azCode" : "{AZ_CODE}",
      "volume" : {
        "type" : "ULTRAHIGH",
        "size" : 40,
        "resourceIds" : [ "{RESOURCE_ID}" ]
      },
      "ip" : "192.168.0.122",
      "resourceId" : "{RESOURCE_ID}"
    } ],
    "publicKibanaResp" : {
      "eipSize" : 10,
      "publicKibanaIp" : "100.95.152.28:9200",
      "elbWhiteListResp" : null,
      "bandwidthResourceId" : "18bec13f-5cc1-4631-867f-33505d15be12"
    },
    "elbWhiteList" : {
      "whiteList" : "",
      "enableWhiteList" : false
    },
    "updated" : "2023-10-09T02:07:13",
    "name" : "css-8bc5",
    "publicIp" : "100.85.222.202",
    "created" : "2023-10-09T02:07:13",
    "id" : "{CLUSTER_ID}",
    "status" : "200",
    "endpoint" : "192.168.0.122:9200",
    "vpcId" : "{VPC_ID}",
    "subnetId" : "{SUBNET_ID}",
    "securityGroupId" : "{SECURITY_GROUP_ID}",
    "bandwidthResourceId" : "{BANDWIDTH_RESOURCE_ID}",
    "bandwidthSize" : 3,
    "httpsEnable" : true,
    "authorityEnable" : true,
    "diskEncrypted" : false,
    "backupAvailable" : false,
    "actionProgress" : { },
    "actions" : [ ],
    "enterpriseProjectId" : "0",
    "tags" : [ ],
    "period" : true
  } ]
}

Status Codes

Status Code	Description
200	Request succeeded.
400	Invalid request. Modify the request before retry.
404	The requested resource could not be found. Modify the request before retry.

Status Code

Description

200

Request succeeded.

400

Invalid request.

Modify the request before retry.

404

The requested resource could not be found.

Modify the request before retry.