Updated on 2024-11-29 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.

URI

  • Format

    GET /v1.1/{project_id}/cluster_infos

  • Parameter description
    Table 1 URI parameters

    Parameter

    Mandatory

    Type

    Description

    project_id

    Yes

    String

    Explanation

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

    Constraints

    N/A

    Value range

    The value must consist of 1 to 64 characters. Only letters and digits are allowed.

    Default value

    N/A

    Table 2 Query parameters

    Parameter

    Mandatory

    Type

    Description

    pageSize

    No

    String

    Explanation

    Maximum number of clusters displayed on a page

    Constraints

    N/A

    Value range

    1-2147483646

    Default value

    10

    currentPage

    No

    String

    Explanation

    Current page number

    Constraints

    N/A

    Value range

    N/A

    Default value

    1

    clusterName

    No

    String

    Explanation

    The cluster name.

    Constraints

    N/A

    Value range

    N/A

    Default value

    N/A

    clusterState

    No

    String

    Explanation

    Query clusters by status.

    Constraints

    N/A

    Value range

    • 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.

    Default value

    N/A

    tags

    No

    String

    Explanation

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

    Constraints

    N/A

    Value range

    • 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.

    Default value

    N/A

    enterpriseProjectId

    No

    String

    Explanation

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

    Constraints

    N/A

    Value range

    N/A

    Default value

    0

Request Parameters

None

Response Parameters

Table 3 Response parameters

Parameter

Type

Description

clusterTotal

Integer

Explanation

Total number of clusters in a list

Value range

N/A

clusters

Array of Cluster objects

Explanation

Cluster parameters. For details, see Table 4.

Table 4 clusters parameters

Parameter

Type

Description

clusterId

String

Explanation

Cluster ID.

Value range

N/A

clusterName

String

Explanation

Cluster name.

Value range

N/A

masterNodeNum

String

Explanation

Number of Master nodes deployed in a cluster.

Value range

N/A

coreNodeNum

String

Explanation

Number of Core nodes deployed in a cluster.

Value range

N/A

totalNodeNum

String

Explanation

Total number of nodes deployed in a cluster.

Value range

N/A

clusterState

String

Explanation

Cluster status.

Value range

  • 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

Explanation

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

Value range

N/A

updateAt

String

Explanation

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

Value range

N/A

dataCenter

String

Explanation

Cluster work region.

Value range

N/A

vpc

String

Explanation

VPC name.

Value range

N/A

vpcId

String

Explanation

VPC ID.

Value range

N/A

hadoopVersion

String

Explanation

Hadoop version

Value range

N/A

masterNodeSize

String

Explanation

Instance specifications of a Master node.

Value range

N/A

coreNodeSize

String

Explanation

Instance specifications of a Core node.

Value range

N/A

componentList

Array

Explanation

Component list. For details, see Table 5.

externalIp

String

Explanation

External IP address. This IP address is opened to the outside of the cluster as access to the active Master process.

Value range

N/A

externalAlternateIp

String

Explanation

Backup external IP address. This IP address is used outside the cluster as access to the standby Master process.

Value range

N/A

internalIp

String

Explanation

Internal IP address. This IP address is used within the cluster as access to Master processes.

Value range

N/A

deploymentId

String

Explanation

Cluster deployment ID. The ID is used by cloud services to query details about cluster deployment tasks.

Value range

N/A

remark

String

Explanation

Cluster remarks. By default, this parameter is left blank.

Value range

N/A

orderId

String

Explanation

Cluster creation order ID.

Value range

N/A

azId

String

Explanation

AZ ID.

Value range

N/A

masterNodeProductId

String

Explanation

Product ID of a Master node.

Value range

N/A

masterNodeSpecId

String

Explanation

Specification ID of a Master node.

Value range

N/A

coreNodeProductId

String

Explanation

Product ID of a Core node.

Value range

N/A

coreNodeSpecId

String

Explanation

Specification ID of a Core node

Value range

N/A

azName

String

Explanation

AZ name.

Value range

N/A

azCode

String

Explanation

AZ name (en).

Value range

N/A

availabilityZoneId

String

Explanation

Availability zone.

Value range

N/A

instanceId

String

Explanation

Instance ID.

Value range

N/A

vnc

String

Explanation

URI for remotely logging in to an ECS.

Value range

N/A

tenantId

String

Explanation

Project ID.

Value range

N/A

volumeSize

Integer

Explanation

Disk storage space.

Value range

N/A

volumeType

String

Explanation

Disk type.

Value range

N/A

subnetId

String

Explanation

Subnet ID.

Value range

N/A

clusterType

Integer

Explanation

Cluster type.

Value range

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

subnetName

String

Explanation

Subnet name.

Value range

N/A

securityGroupsId

String

Explanation

Security group ID.

Value range

N/A

slaveSecurityGroupsId

String

Explanation

Security group ID of a non-master node. Currently, one MRS cluster uses only one security group. Therefore, this field has been discarded. This field returns the same value as securityGroupsId does for compatibility consideration.

Value range

N/A

bootstrapScripts

Array of BootstrapScript objects

Explanation

Bootstrap action script. For details, see Table 6.

stageDesc

String

Explanation

Cluster process.

Value range

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

Explanation

Whether MRS Manager installation is finished during cluster creation.

Value range

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

safeMode

Integer

Explanation

Run mode of an MRS cluster.

Value range

  • 0: Normal cluster
  • 1: Security cluster

clusterVersion

String

Explanation

Cluster version.

Value range

N/A

nodePublicCertName

String

Explanation

Name of the key file.

Value range

N/A

masterNodeIp

String

Explanation

IP address of a Master node.

Value range

N/A

privateIpFirst

String

Explanation

Preferred private IP address.

Value range

N/A

errorInfo

String

Explanation

Error message.

Value range

N/A

tags

String

Explanation

Tag information.

Value range

N/A

logCollection

Integer

Explanation

Whether to collect logs when cluster installation fails.

Value range

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

taskNodeGroups

List<NodeGroup>

Explanation

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

nodeGroups

List<NodeGroup>

Explanation

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

masterDataVolumeType

String

Explanation

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

Value range

N/A

masterDataVolumeSize

Integer

Explanation

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

Value range

100-32000

masterDataVolumeCount

Integer

Explanation

Number of data disks of the Master node

Value range

The value can only be 1.

coreDataVolumeType

String

Explanation

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

Value range

N/A

coreDataVolumeSize

Integer

Explanation

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

Value range

100-32000

coreDataVolumeCount

Integer

Explanation

Number of data disks of the Core node.

Value range

1-10

scale

String

Explanation

Status of node changes If this parameter is left blank, no change operation is performed on a cluster node.

Value range

  • 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

Explanation

Unique ID of the cluster EIP

Value range

N/A

eipAddress

String

Explanation

IPv4 address of the cluster EIP

Value range

N/A

eipv6Address

String

Explanation

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

Value range

N/A

Table 5 componentAmb

Parameter

Type

Description

componentId

String

Explanation

Component ID

Value range

For example, the component_id of Hadoop is MRS 3.3.1-LTS_001.

componentName

String

Explanation

Component name.

Value range

N/A

componentVersion

String

Explanation

Component version.

Value range

N/A

componentDesc

String

Explanation

Component description.

Value range

N/A

Table 6 bootstrapScripts

Parameter

Type

Description

name

String

Explanation

Name of a bootstrap action script.

Constraints

N/A

Value range

The names of bootstrap action scripts in the same cluster must be unique. The value can contain 1 to 64 characters, including only digits, letters, spaces, hyphens (-), and underscores (_), and cannot start with a space.

Default value

N/A

uri

String

Explanation

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.

Constraints

N/A

Value range

N/A

Default value

N/A

parameters

String

Explanation

The bootstrap action script parameters.

Constraints

N/A

Value range

N/A

Default value

N/A

nodes

Array of strings

Explanation

Type of a node where the bootstrap action script is executed. The value can be Master, Core, or Task.

Constraints

The node type must be represented in lowercase letters.

active_master

Boolean

Explanation

Whether the bootstrap action script runs only on active master nodes.

Constraints

N/A

Value range

  • true: The bootstrap action script runs only on active Master nodes.
  • false: The bootstrap action script can run on all Master nodes.

Default value

false

fail_action

String

Explanation

Whether to continue executing subsequent scripts and creating a cluster after the bootstrap action script fails to execute. 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.

Constraints

N/A

Value range

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

Default value

errorout

before_component_start

Boolean

Explanation

Time when the bootstrap action script is executed. Currently, the following two options are available: Before component start and After component start.

Constraints

N/A

Value range

  • true: The bootstrap action script is executed before the component starts.
  • false: The bootstrap action script is executed after the component starts.

Default value

false

start_time

Long

Explanation

The execution time of one bootstrap action script.

Constraints

N/A

Value range

N/A

Default value

N/A

state

String

Explanation

The running status of one bootstrap action script.

Constraints

N/A

Value range

  • PENDING: The script is suspended.
  • IN_PROGRESS: The script is being processed.
  • SUCCESS
  • FAILURE: The script fails to be executed.

action_stages

Array of strings

Explanation

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

Constraints

N/A

Table 7 NodeGroupV10

Parameter

Type

Description

GroupName

String

Explanation

Node group name.

Value range

N/A

NodeNum

Integer

Explanation

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.

Value range

0-500

NodeSize

String

Explanation

Instance specifications of a node.

Value range

N/A

NodeSpecId

String

Explanation

Instance specification ID of a node.

Value range

N/A

NodeProductId

String

Explanation

Instance product ID of a node.

Value range

N/A

VmProductId

String

Explanation

VM specifications of a node.

Value range

N/A

VmSpecCode

String

Explanation

VM specifications of a node.

Value range

N/A

RootVolumeSize

Integer

Explanation

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

Value range

N/A

RootVolumeProductId

String

Explanation

System disk product ID of a node.

Value range

N/A

RootVolumeType

String

Explanation

System disk type of a node.

Value range

N/A

RootVolumeResourceSpecCode

String

Explanation

System disk product specifications of a node.

Value range

N/A

RootVolumeResourceType

String

Explanation

System disk product type of a node.

Value range

N/A

DataVolumeType

String

Explanation

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

Value range

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

DataVolumeCount

Integer

Explanation

Number of data disks of a node.

Value range

N/A

DataVolumeSize

Integer

Explanation

Data disk storage space of a node.

Value range

N/A

DataVolumeProductId

String

Explanation

Data disk product ID of a node.

Value range

N/A

DataVolumeResourceSpecCode

String

Explanation

Data disk specifications of a node.

Value range

N/A

DataVolumeResourceType

String

Explanation

Data disk type of a node.

Value range

N/A

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" : ,
    "vpc" : null,
    "duration" : "0",
    "fee" : null,
    "hadoopVersion" : null,
    "masterNodeSize" : null,
    "coreNodeSize" : null,
    "componentList" : [ {
      "componentId" : "MRS 3.3.1-LTS_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.3.1-LTS_003",
      "componentName" : "HBase",
      "componentVersion" : "2.1.1",
      "componentDesc" : "A scalable, distributed database that supports structured data storage for large tables."
    }, {
      "componentId" : "MRS 3.3.1-LTS_002",
      "componentName" : "Spark",
      "componentVersion" : "2.3.2",
      "componentDesc" : "A fast and general engine for large-scale data processing."
    }, {
      "componentId" : "MRS 3.3.1-LTS_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.cn-fcs-1a",
    "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" : "c3.2xlarge.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" : "c3.2xlarge.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" : "c3.2xlarge.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" : "c3.2xlarge.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",
  } ]
}

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.