Updated on 2023-10-24 GMT+08:00

Querying a Cluster List

Function

This API is used to query a list of clusters created by a user. This API is incompatible with Sahara.

Constraints

None

Debugging

You can debug this API in API Explorer. Automatic authentication is supported. API Explorer can automatically generate sample SDK code and provide the sample SDK code debugging.

URI

  • Format

    GET /v1.1/{project_id}/cluster_infos

  • Parameter description
    Table 1 URI parameters

    Parameter

    Mandatory

    Type

    Description

    project_id

    Yes

    String

    The project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

    Table 2 Query parameters

    Parameter

    Mandatory

    Type

    Description

    pageSize

    No

    String

    Maximum number of clusters displayed on a page

    The default value is 10. The value range is [1, 2147483646].

    currentPage

    No

    String

    Current page number. The default value is 1.

    clusterName

    No

    String

    The cluster name.

    clusterState

    No

    String

    Query clusters by status.

    • existing: Query existing clusters, including all clusters except those in the Deleted state and the yearly/monthly clusters in the Order processing or Preparing state.
    • history: Quer historical clusters, including all the deleted clusters, clusters that fail to delete, clusters whose VMs fail to delete, and clusters whose database updates fail to delete.
    • starting: Query a list of clusters that are being started.
    • running: Query a list of running clusters.
    • terminated: Query a list of terminated clusters.
    • failed: Query a list of failed clusters.
    • abnormal: Query a list of abnormal clusters.
    • terminating: Query a list of clusters that are being terminated.
    • frozen: Query a list of frozen clusters.
    • scaling-out: Query a list of clusters that are being scaled out.
    • scaling-in: Query a list of clusters that are being scaled in.

    tags

    No

    String

    You can search for a cluster by its tag. If you specify multiple tags, the relationship between them is AND.

    • The format of the tags parameter is tags=k1*v1,k2*v2,k3*v3.
    • When the values of some tags are null, the format is tags=k1,k2,k3*v3.

    enterpriseProjectId

    No

    String

    The enterprise project ID used to query clusters in a specified enterprise project.

    The default value is 0, indicating the default enterprise project.

    To obtain the enterprise project ID, see the id value in the enterprise_project field data structure table in "Querying the Enterprise Project List" in Enterprise Management API Reference.

Request Parameters

None

Response Parameters

Table 3 Response parameters

Parameter

Type

Description

clusterTotal

Integer

Total number of clusters in a list

clusters

Array of Cluster objects

Cluster parameters. For details, see Table 4.

Table 4 cluster parameters

Parameter

Type

Description

clusterId

String

Cluster ID.

clusterName

String

Cluster name.

masterNodeNum

String

Number of Master nodes deployed in a cluster.

coreNodeNum

String

Number of Core nodes deployed in a cluster.

totalNodeNum

String

Total number of nodes deployed in a cluster.

clusterState

String

Cluster status. Valid values include:
  • starting: The cluster is being started.
  • running: The cluster is running.
  • terminated: The cluster has been terminated.
  • failed: The cluster fails.
  • abnormal: The cluster is abnormal.
  • terminating: The cluster is being terminated.
  • frozen: The cluster has been frozen.
  • scaling-out: The cluster is being scaled out.
  • scaling-in: The cluster is being scaled in.

createAt

String

Cluster creation time, which is a 10-bit timestamp.

updateAt

String

Cluster update time, which is a 10-bit timestamp.

billingType

String

Cluster billing mode. The options are as follows:

  • 11: Yearly/Monthly
  • 12: Pay-per-use

dataCenter

String

Cluster work region.

vpc

String

VPC name.

vpcId

String

VPC ID.

duration

String

Cluster subscription duration.

fee

String

Cluster creation fee, which is automatically calculated.

hadoopVersion

String

Hadoop version.

masterNodeSize

String

Instance specifications of a Master node.

coreNodeSize

String

Instance specifications of a Core node.

componentList

Array

Component list. For details, see Table 5.

externalIp

String

External IP address.

externalAlternateIp

String

Backup external IP address.

internalIp

String

Internal IP address.

deploymentId

String

Cluster deployment ID.

remark

String

Cluster remarks.

orderId

String

Cluster creation order ID.

azId

String

AZ ID.

masterNodeProductId

String

Product ID of a Master node.

masterNodeSpecId

String

Specification ID of a Master node.

coreNodeProductId

String

Product ID of a Core node.

coreNodeSpecId

String

Specification ID of a Core node.

azName

String

AZ name.

azCode

String

AZ name (en).

availabilityZoneId

String

The AZ.

instanceId

String

Instance ID.

vnc

String

URI for remotely logging in to an ECS.

tenantId

String

Project ID.

volumeSize

Integer

Disk storage space.

volumeType

String

Disk type.

subnetId

String

Subnet ID.

enterpriseProjectId

String

Enterprise project ID.

clusterType

Integer

Cluster type. The options are as follows:

  • 0: analysis cluster
  • 1: streaming cluster
  • 2: hybrid cluster
  • 3: custom cluster
  • 4: Offline cluster

subnetName

String

Subnet name.

securityGroupsId

String

Security group ID.

slaveSecurityGroupsId

String

Security group ID of a non-Master node. Currently, one MRS cluster uses only one security group. Therefore, this field has been discarded.

bootstrapScripts

Array of BootstrapScript objects

The bootstrap action script information.

For details about this parameter, see Table 6.

stageDesc

String

Cluster progress description. (The description is in English by default. When the X-Language request header is set to zh-cn, this field returns Chinese.) The cluster installation progress includes:
  • Verifying cluster parameters: Cluster parameters are being verified.
  • Applying for cluster resources: Cluster resources are being applied for.
  • Creating VMs: The VMs are being created.
  • Initializing VMs: The VMs are being initialized.
  • Installing MRS Manager: MRS Manager is being installed.
  • Deploying the cluster: The cluster is being deployed.
  • Cluster installation failed: Failed to install the cluster.
The cluster scale-out progress includes:
  • Preparing for scale-out: Cluster scale-out is being prepared.
  • Creating VMs: The VMs are being created.
  • Initializing VMs: The VMs are being initialized.
  • Adding nodes to the cluster: The nodes are being added to the cluster.
  • Scale-out failed: Failed to scale out the cluster.
The cluster scale-in progress includes:
  • Preparing for scale-in: Cluster scale-in is being prepared.
  • Decommissioning instance: The instance is being decommissioned.
  • Deleting VMs: The VMs are being deleted.
  • Deleting nodes from the cluster: The nodes are being deleted from the cluster.
  • Scale-in failed: Failed to scale in the cluster.

    If the cluster installation, scale-out, or scale-in fails, stageDesc will display the failure cause.

isMrsManagerFinish

Boolean

Whether MRS Manager installation is finished during cluster creation.

  • true: MRS Manager installation is finished.
  • false: MRS Manager installation is not finished.

safeMode

Integer

Running mode of an MRS cluster.

  • 0: Normal cluster
  • 1: Security cluster

clusterVersion

String

Cluster version.

nodePublicCertName

String

Name of the key file.

masterNodeIp

String

IP address of a Master node.

privateIpFirst

String

Preferred private IP address.

errorInfo

String

Error message.

tags

String

The tag information.

chargingStartTime

String

Start time of billing.

logCollection

Integer

Whether to collect logs when cluster installation fails.

  • 0: Do not collect logs.
  • 1: Collect logs.

taskNodeGroups

List<NodeGroup>

List of Task nodes. For more parameter description, see Table 7.

nodeGroups

List<NodeGroup>

List of Master, Core and Task nodes. For more parameter description, see Table 7.

masterDataVolumeType

String

Data disk storage type of the Master node. Currently, SATA, SAS, and SSD are supported.

masterDataVolumeSize

Integer

Data disk storage space of the Master node To increase data storage capacity, you can add disks at the same time when creating a cluster.

Value range: 100 GB to 32,000 GB

masterDataVolumeCount

Integer

Number of data disks of the Master node

The value can be set to 1 only.

coreDataVolumeType

String

Data disk storage type of the Core node. Currently, SATA, SAS, and SSD are supported.

coreDataVolumeSize

Integer

Data disk storage space of the Core node. To increase data storage capacity, you can add disks at the same time when creating a cluster.

Value range: 100 GB to 32,000 GB

coreDataVolumeCount

Integer

Number of data disks of the Core node.

Value range: 1 to 10

periodType

Integer

Whether the subscription type is yearly or monthly.

  • 0: monthly subscription
  • 1: yearly subscription

scale

String

Status of node changes If this parameter is left blank, no change operation is performed on a cluster node. (The status is in English by default. When the X-Language request header is set to zh-cn, this field returns Chinese text.) The options are as follows:

  • Scaling-out: The cluster is being scaled out.
  • Scaling-in: The cluster is being scaled in.
  • scaling-error: The cluster is in the running state and fails to be scaled in or out or the specifications fail to be scaled up for the last time.
  • scaling-up: The master node specifications are being scaled up.
  • scaling_up_first: The standby master node specifications are being scaled up.
  • scaled_up_first: The standby master node specifications have been scaled up.
  • scaled-up-success: The master node specifications have been scaled up.

eipId

String

Unique ID of the cluster EIP

eipAddress

String

IPv4 address of the cluster EIP

eipv6Address

String

IPv6 address of the cluster EIP. This parameter is not returned when an IPv4 address is used.

Table 5 componentAmb

Parameter

Type

Description

componentId

String

Component ID

For example, the component_id of Hadoop is MRS 3.0.2_001, MRS 2.1.0_001, MRS 1.9.2_001, MRS 1.8.10_001.

componentName

String

Component name

componentVersion

String

Component version

componentDesc

String

Component description

Table 6 bootstrapScripts

Parameter

Type

Description

name

String

The name of a bootstrap action script, which must be unique in a cluster.

The value can contain only numbers, letters, spaces, hyphens (-), and underscores (_) and cannot start with a space.

The value can contain 1 to 64 characters.

uri

String

The path of a bootstrap action script. Set this parameter to an OBS bucket path or a local VM path.

  • OBS bucket path: Enter a script path. For example, enter the path of the public sample script provided by MRS. Example: s3a://bootstrap/presto/presto-install.sh. If dualroles is installed, the parameter of the presto-install.sh script is dualroles. If worker is installed, the parameter of the presto-install.sh script is worker. Based on the Presto usage habit, you are advised to install dualroles on the active master nodes and worker on the core nodes.
  • Local VM path: Enter a script path. The script path must start with a slash (/) and end with .sh.

parameters

String

The bootstrap action script parameters.

nodes

Array of strings

Type of a node where the Bootstrap action script is executed. The value can be master, core, or task. The node type must be represented in lowercase letters.

active_master

Boolean

Whether the bootstrap action script runs only on active master nodes. The default value is false, indicating that the bootstrap action script can run on all master nodes.

fail_action

String

Whether to continue executing subsequent scripts and creating a cluster after the bootstrap action script fails to execute.

The default value is errorout, indicating that the action is stopped.

Note: You are advised to set this parameter to continue in the commissioning phase so that the cluster can continue to be installed and started no matter whether the bootstrap action is successful.

Enumerated values:

  • continue: Continue to execute subsequent scripts.
  • errorout: Stop the action.

before_component_start

Boolean

Time when the bootstrap action script is executed. Currently, the following two options are available: Before component start and After component start. The default value is false, indicating that the bootstrap action script is executed after the component is started.

start_time

Long

The execution time of one bootstrap action script.

state

String

The running status of one bootstrap action script.

  • PENDING
  • IN_PROGRESS
  • SUCCESS
  • FAILURE

action_stages

Array of strings

Select the time when the bootstrap action script is executed.

  • BEFORE_COMPONENT_FIRST_START: before initial component starts
  • AFTER_COMPONENT_FIRST_START: after initial component starts
  • BEFORE_SCALE_IN: before scale-in
  • AFTER_SCALE_IN: after scale-in
  • BEFORE_SCALE_OUT: before scale-out
  • AFTER_SCALE_OUT: after scale-out
Table 7 NodeGroupV10

Parameter

Type

Description

GroupName

String

Node group name.

NodeNum

Integer

Number of nodes. The value ranges from 0 to 500. The minimum number of Master and Core nodes is 1 and the total number of Core and Task nodes cannot exceed 500.

NodeSize

String

Instance specifications of a node.

NodeSpecId

String

Instance specification ID of a node

NodeProductId

String

Instance product ID of a node

VmProductId

String

VM product ID of a node

VmSpecCode

String

VM specifications of a node

RootVolumeSize

Integer

System disk size of a node. This parameter is not configurable and its default value is 40 GB.

RootVolumeProductId

String

System disk product ID of a node

RootVolumeType

String

System disk type of a node

RootVolumeResourceSpecCode

String

System disk product specifications of a node

RootVolumeResourceType

String

System disk product type of a node

DataVolumeType

String

Data disk storage type of a node. Currently, SATA, SAS, and SSD are supported.

  • SATA: common I/O
  • SAS: high I/O
  • SSD: ultra-high I/O

DataVolumeCount

Integer

Number of data disks of a node.

DataVolumeSize

Integer

Data disk storage space of a node.

DataVolumeProductId

String

Data disk product ID of a node

DataVolumeResourceSpecCode

String

Data disk product specifications of a node

DataVolumeResourceType

String

Data disk product type of a node

Example Response

Status code: 200

Querying the cluster list is successful.

{
  "clusterTotal" : "1",
  "clusters" : [ {
    "clusterId" : "bc134369-294c-42b7-a707-b2036ba38524",
    "clusterName" : "mrs_D0zW",
    "masterNodeNum" : "2",
    "coreNodeNum" : "3",
    "clusterState" : "terminated",
    "createAt" : "1498272043",
    "updateAt" : "1498636753",
    "chargingStartTime" : "1498273733",
    "logCollection" : "1",
    "billingType" : "Metered",
    "dataCenter" : "cn-hk1",
    "vpc" : null,
    "duration" : "0",
    "fee" : null,
    "hadoopVersion" : null,
    "masterNodeSize" : null,
    "coreNodeSize" : null,
    "componentList" : [ {
      "componentId" : "MRS 3.1.0_001",
      "componentName" : "Hadoop",
      "componentVersion" : "3.1.1",
      "componentDesc" : "A framework that allows for the distributed processing of large data sets across clusters."
    }, {
      "componentId" : "MRS 3.1.0_003",
      "componentName" : "HBase",
      "componentVersion" : "2.1.1",
      "componentDesc" : "A scalable, distributed database that supports structured data storage for large tables."
    }, {
      "componentId" : "MRS 3.1.0_002",
      "componentName" : "Spark",
      "componentVersion" : "2.3.2",
      "componentDesc" : "A fast and general engine for large-scale data processing."
    }, {
      "componentId" : "MRS 3.1.0_004",
      "componentName" : "Hive",
      "componentVersion" : "3.1.0",
      "componentDesc" : "A data warehouse infrastructure that provides data summarization and ad hoc querying."
    } ],
    "externalIp" : null,
    "externalAlternateIp" : null,
    "internalIp" : null,
    "deploymentId" : null,
    "remark" : "",
    "orderId" : null,
    "azId" : null,
    "azCode" : null,
    "masterNodeProductId" : null,
    "masterNodeSpecId" : null,
    "coreNodeProductId" : null,
    "coreNodeSpecId" : null,
    "azName" : "AZ1",
    "instanceId" : null,
    "vnc" : "v2/5a3314075bfa49b9ae360f4ecd333695/servers/e2cda891-232e-4703-995e-3b1406add01d/action",
    "tenantId" : null,
    "volumeSize" : "0",
    "volumeType" : null,
    "subnetId" : null,
    "subnetName" : null,
    "securityGroupsId" : null,
    "slaveSecurityGroupsId" : null,
    "bootstrapScripts" : [ {
      "name" : "test1-success",
      "uri" : "s3a://bootscript/script/simple/basic_success.sh",
      "parameters" : "",
      "nodes" : [ "master", "core" ],
      "active_master" : true,
      "fail_action" : "errorout",
      "before_component_start" : true,
      "state" : "SUCCESS",
      "start_time" : 1527681083,
      "action_stages" : [ "AFTER_SCALE_IN", "AFTER_SCALE_OUT" ]
    } ],
    "isMrsManagerFinish" : false,
    "stageDesc" : "Installing MRS Manager",
    "safeMode" : "0",
    "clusterVersion" : null,
    "nodePublicCertName" : null,
    "masterNodeIp" : "unknown",
    "privateIpFirst" : null,
    "errorInfo" : "",
    "clusterType" : "0",
    "nodeGroups" : [ {
      "GroupName" : "master_node_default_group",
      "NodeNum" : "1",
      "NodeSize" : "s3.xlarge.2.linux.bigdata",
      "NodeSpecId" : "cdc6035a249a40249312f5ef72a23cd7",
      "VmProductId" : "",
      "VmSpecCode" : null,
      "NodeProductId" : "dc970349d128460e960a0c2b826c427c",
      "RootVolumeSize" : "40",
      "RootVolumeProductId" : "16c1dcf0897249758b1ec276d06e0572",
      "RootVolumeType" : "SATA",
      "RootVolumeResourceSpecCode" : "",
      "RootVolumeResourceType" : "",
      "DataVolumeType" : "SATA",
      "DataVolumeCount" : "1",
      "DataVolumeSize" : "100",
      "DataVolumeProductId" : "16c1dcf0897249758b1ec276d06e0572",
      "DataVolumeResourceSpecCode" : "",
      "DataVolumeResourceType" : ""
    }, {
      "GroupName" : "core_node_analysis_group",
      "NodeNum" : "1",
      "NodeSize" : "s3.xlarge.2.linux.bigdata",
      "NodeSpecId" : "cdc6035a249a40249312f5ef72a23cd7",
      "VmProductId" : "",
      "VmSpecCode" : null,
      "NodeProductId" : "dc970349d128460e960a0c2b826c427c",
      "RootVolumeSize" : "40",
      "RootVolumeProductId" : "16c1dcf0897249758b1ec276d06e0572",
      "RootVolumeType" : "SATA",
      "RootVolumeResourceSpecCode" : "",
      "RootVolumeResourceType" : "",
      "DataVolumeType" : "SATA",
      "DataVolumeCount" : "1",
      "DataVolumeSize" : "100",
      "DataVolumeProductId" : "16c1dcf0897249758b1ec276d06e0572",
      "DataVolumeResourceSpecCode" : "",
      "DataVolumeResourceType" : ""
    }, {
      "GroupName" : "task_node_analysis_group",
      "NodeNum" : "1",
      "NodeSize" : "s3.xlarge.2.linux.bigdata",
      "NodeSpecId" : "cdc6035a249a40249312f5ef72a23cd7",
      "VmProductId" : "",
      "VmSpecCode" : null,
      "NodeProductId" : "dc970349d128460e960a0c2b826c427c",
      "RootVolumeSize" : "40",
      "RootVolumeProductId" : "16c1dcf0897249758b1ec276d06e0572",
      "RootVolumeType" : "SATA",
      "RootVolumeResourceSpecCode" : "",
      "RootVolumeResourceType" : "",
      "DataVolumeType" : "SATA",
      "DataVolumeCount" : "1",
      "DataVolumeSize" : "100",
      "DataVolumeProductId" : "16c1dcf0897249758b1ec276d06e0572",
      "DataVolumeResourceSpecCode" : "",
      "DataVolumeResourceType" : ""
    } ],
    "taskNodeGroups" : [ {
      "GroupName" : "task_node_default_group",
      "NodeNum" : "1",
      "NodeSize" : "s3.xlarge.2.linux.bigdata",
      "NodeSpecId" : "cdc6035a249a40249312f5ef72a23cd7",
      "VmProductId" : "",
      "VmSpecCode" : null,
      "NodeProductId" : "dc970349d128460e960a0c2b826c427c",
      "RootVolumeSize" : "40",
      "RootVolumeProductId" : "16c1dcf0897249758b1ec276d06e0572",
      "RootVolumeType" : "SATA",
      "RootVolumeResourceSpecCode" : "",
      "RootVolumeResourceType" : "",
      "DataVolumeType" : "SATA",
      "DataVolumeCount" : "1",
      "DataVolumeSize" : "100",
      "DataVolumeProductId" : "16c1dcf0897249758b1ec276d06e0572",
      "DataVolumeResourceSpecCode" : "",
      "DataVolumeResourceType" : ""
    } ],
    "masterDataVolumeType" : "SATA",
    "masterDataVolumeSize" : "200",
    "masterDataVolumeCount" : "1",
    "coreDataVolumeType" : "SATA",
    "coreDataVolumeSize" : "100",
    "coreDataVolumeCount" : "1",
    "periodType" : "0"
  } ]
}

Status Codes

Table 8 describes the status code.

Table 8 Status code

Status Code

Description

200

The cluster list information has been queried.

See Status Codes.

Error Codes

See Error Codes.