Help Center/ MapReduce Service/ API Reference/ API V2/ Cluster Management APIs/ Querying the Cluster Node List - ListNodes

Updated on 2026-09-15 GMT+08:00

View PDF

Querying the Cluster Node List - ListNodes

Function

This API is used to query the node list information of a specified MRS cluster, including the node names, IP addresses, node types, and running statuses. It is used to understand the node composition of the cluster and the operational status of each node.

Constraints

None

Debugging

You can debug this API in API Explorer, which supports automatic authentication and authorization. API Explorer can automatically generate sample SDK code and supports sample SDK code debugging.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, no identity policy-based permissions are required for calling this API.

URI

GET /v2/{project_id}/clusters/{cluster_id}/nodes

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID. Constraints N/A Range The value can contain 1 to 64 characters. Only letters and digits are allowed. Default Value N/A
cluster_id	Yes	String	Definition Cluster ID Constraints N/A Range The value can contain 1 to 64 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. Default Value N/A

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
node_group	No	String	Definition Name of the node group to query. Constraints N/A Range Only letters, digits, and underscores (_) are allowed. Except for the default system node groups, custom node group names must contain 3 to 14 characters. Default Value N/A
limit	No	Integer	Definition Number of records displayed on each page in the returned result. Constraints N/A Range 1~1000 Default Value 10
offset	No	Integer	Definition Offset from which the node list query begins. This parameter is used in conjunction with limit. For example, if there are 30 nodes in total, setting offset to 1 and limit to 10 means the query starts from the 12th node, and a maximum of 10 nodes can be retrieved at a time. Constraints N/A Range Greater than or equal to 1, and less than the total number of nodes in the MRS cluster. Default Value 1
node_name	No	String	Definition Node name. Fuzzy search is supported. Constraints N/A Range N/A Default Value N/A
sort_key	No	String	Definition Sorting key. You can set node names as the key. Constraints N/A Range node_name: node name Default Value N/A
sort_dir	No	String	Definition Sorting order. desc indicates descending order, and asc indicates ascending order. Constraints N/A Range desc: Descending order. asc: Ascending order. Default Value N/A
query_node_detail	No	Boolean	Definition Whether to query node details. If this parameter is set to true, the interface performance may be affected. Constraints N/A Range true: Query node details. false: Do not query node details. Default Value false
query_ecs_detail	No	Boolean	Definition Whether to query ECS details. ECS APIs may be called. Constraints N/A Range true: Query ECS details. false: Do not query ECS details. Default Value false
internal_ip	No	String	Definition Private IP address of a specified node. Constraints N/A Range The value can contain 7 to 15 characters and must conform to the IP address format. Only digits and periods (.) are allowed. Default Value N/A

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
nodes	Array of ClusterNode objects	Definition Node list. For details, see Table 4. Each node returns its corresponding object structure, including detailed information such as node_name, resource_id, and more. Range N/A
node_total	Integer	Definition Number of nodes. Range N/A

**Table 4** ClusterNode
Parameter	Type	Description
node_name	String	Definition Node name, corresponding to the node name in Manager. Range N/A
resource_id	String	Definition Resource ID. Unique identity of a node. For yearly/monthly nodes, the ID can be used to query bills. Range N/A
node_group_name	String	Definition Node group name. Range N/A
node_type	String	Definition Node type. Available values include Task, Core, and Master. Range A cluster must contain Master nodes and may contain Core and Task nodes. Master: Master node Core: Core node Task: Task node
billing_type	String	Definition on-period: yearly/monthly; on-quantity: pay-per-use. Range on-period: Yearly/monthly. on-quantity: Pay-per-use.
deployment_type	String	Definition Deployment type. The Server hosts are supported. Range SERVER: Host type.
server_info	ServerInfo object	Definition If the deployment type is Server, this parameter cannot be empty. For details, see Table 5. This parameter contains information such as the disk information on the node and the node type. For detailed parameter descriptions, see the parameter details list. Range N/A
tags	Array of Tag objects	Definition Node tag. For details, see Table 7. Key-value pairs bound to the current node. For detailed parameter descriptions, see the parameter details list. Range N/A
node_detail	NodeDetail object	Definition Node monitoring information. This parameter is returned only after IAM synchronization. For details, see Table 8. Range N/A
node_status	String	Definition Node status. Status of operations on the corresponding page. Range error: The node is faulty. delete_fail: The node fails to be deleted. shutdown: The node is shut down. creating: The node is being created. starting: The node is being started. started: The node is running. deleting: The node is being deleted. powering-on: The node is being powered on. powering-off: The node is being powered off. stopping: The node is being stopped. attaching: The node is being unisolated. attached: The node is unisolated. detaching: The node is being isolated. detached: The node is isolated. detached_no_subscription: The node is unbound. detach_fail: The node fails to be isolated. destroyed: The node is deleted. lost: The node is disconnected. unknown: The node status is unknown. scaling-up: The node is being scaled up. decommissioning: The node is being decommissioned. decommissioned: The node is decommissioned. recommissioning: The node is being recommissioned. decommission_fail: The node fails to be decommissioned. restore_fail: The node fails to be restored.
component_infos	Array of ComponentInfo objects	Definition Component instance information array. For details, see Table 9. Range N/A

**Table 5** ServerInfo
Parameter	Type	Description
server_id	String	Definition Server ID. Range N/A
server_name	String	Definition Server name. Range N/A
server_type	String	Definition Server type. Available options are ECS and BMS. Range ECS: Elastic Cloud Server BMS: Bare Metal Server
data_volumes	Array of VolumeInfo objects	Definition Data disk. For details, see Table 6. Range N/A
root_volume	VolumeInfo object	Definition System disk. For details, see Table 6. Range N/A
cpu_type	String	Definition CPU type. Available options are x86 and Arm. Range x86: x86 architecture ARM: Arm architecture
cpu	String	Definition CPU size, in cores. Range N/A
mem	String	Definition Memory size, in MB. Range N/A
internal_ip	String	Definition Internal IP address. Range N/A

**Table 6** VolumeInfo
Parameter	Type	Description
type	String	Definition Disk type. Range SATA: common I/O disk SAS: high I/O disk SSD: ultra-high I/O disk GPSSD: general-purpose SSD disk
size	Integer	Definition Disk size. Unit: GB. Range N/A
count	Integer	Definition Disk quantity. Range N/A

**Table 7** Tag
Parameter	Type	Description
key	String	Definition Tag key Range N/A
value	String	Definition Tag value. Range N/A

**Table 8** NodeDetail
Parameter	Type	Description
running_status	String	Definition Running status. Range GOOD: The node is running properly. BAD: The node is faulty. UNKNOWN: The node status is unknown. CONCERNING: The node is being restored. ISOLATED: The node is isolated. SUSPENDED: The node is suspended.
cpu_usage	String	Definition CPU usage, in percentage. Range N/A
memory_usage	String	Definition Memory usage, in percentage. Range N/A
disk_usage	String	Definition Disk usage, in percentage. Range N/A
total_memory	String	Definition Total memory. Unit: MB. Range N/A
available_memory	String	Definition Available memory. Unit: MB. Range N/A
total_hard_disk_space	String	Definition Total hard disk space. Unit: GB Range N/A
available_hard_disk_space	String	Definition Available hard disk space. Unit: GB Range N/A
network_read	String	Definition Network read speed. Unit: Byte/s Range N/A
network_write	String	Definition Network write speed. Unit: Byte/s Range N/A

**Table 9** ComponentInfo
Parameter	Type	Description
id	String	Definition Component ID Range N/A
name	String	Definition Component name Range N/A
instance_group_name	String	Definition Name of the group to which the component belongs. Range N/A
running_status	String	Definition Running status. Range GOOD: The component is running properly. BAD: The component is faulty. UNKNOWN: The component status is unknown. CONCERNING: The component is being restored. ISOLATED: The component is isolated. SUSPENDED: The component is suspended.
ha_status	String	Definition HA status. Range ACTIVE: Active STANDBY: Standby OBSERVER: Secondary UNKNOWN: Unknown
config_status	String	Definition Configuration status. Range SYNCHRONIZED: Synchronized EXPIRED: Configuration expired FAILED: Configuration failed CONFIGURING: Configuration in progress UNKNOWN: Unknown
role_name	String	Definition Role name. Range N/A
role_short_name	String	Definition Abbreviation of a role name. Range N/A
role_type	String	Definition Role type. Range N/A
service_name	String	Definition Service name. Range N/A
pair_name	String	Definition Pair name. Range N/A
relation_pairs	String	Definition Associated pair Range N/A
support_decom	String	Definition Whether Decom is supported. Range N/A
support_reinstall	String	Definition Whether reinstallation is supported. Range N/A
support_collect_stack_info	String	Definition Whether stack information can be collected. Range N/A

Example Request

Query all nodes in a specified node group of a cluster.

https://mrs.cn-north-7.myhuaweicloud.com/v2/174ee662a7e24cc99bfc858c4558dbf6/clusters/f0a91b14-8884-4ba1-9e8d-0a21086c0ab4/nodes?node_group=master_node

Example Response

Status code: 200

List node information.

{
  "nodes" : [ {
    "node_name" : "node-master1QxCW",
    "resource_id" : "fc1ed6bb-e3d8-4dc8-8162-ef673bff6b7b",
    "node_group_name" : "master_node_default_group",
    "node_type" : "Master",
    "billing_type" : "on-quantity",
    "deployment_type" : "SERVER",
    "server_info" : {
      "server_id" : "3687f50a-cd4e-4c67-8858-5d6555c8834c",
      "server_name" : "f28fb043-ecbc-401e-936e-fb321ca8d40a_node_master1QxCW",
      "server_type" : "ECS",
      "data_volumes" : [ {
        "type" : "SATA",
        "size" : 200,
        "count" : 1
      } ],
      "root_volume" : {
        "type" : "SATA",
        "size" : 100,
        "count" : 1
      },
      "cpu_type" : "X86",
      "internal_ip" : "192.168.10.142"
    },
    "tags" : [ {
      "key" : "1",
      "value" : "2"
    } ],
    "node_status" : "started"
  } ],
  "node_total" : 1
}

SDK Sample Code

The SDK sample code is as follows.

     package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.mrs.v2.region.MrsRegion;
import com.huaweicloud.sdk.mrs.v2.*;
import com.huaweicloud.sdk.mrs.v2.model.*;


public class ListNodesSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");
        String projectId = "{project_id}";

        ICredential auth = new BasicCredentials()
                .withProjectId(projectId)
                .withAk(ak)
                .withSk(sk);

        MrsClient client = MrsClient.newBuilder()
                .withCredential(auth)
                .withRegion(MrsRegion.valueOf("<YOUR REGION>"))
                .build();
        ListNodesRequest request = new ListNodesRequest();
        request.withClusterId("{cluster_id}");
        try {
            ListNodesResponse response = client.listNodes(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}
 
 
  

     # coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkmrs.v2.region.mrs_region import MrsRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkmrs.v2 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]
    projectId = "{project_id}"

    credentials = BasicCredentials(ak, sk, projectId)

    client = MrsClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(MrsRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = ListNodesRequest()
        request.cluster_id = "{cluster_id}"
        response = client.list_nodes(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)
 
 
  

     package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    mrs "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/mrs/v2"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/mrs/v2/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/mrs/v2/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")
    projectId := "{project_id}"

    auth, err := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        SafeBuild()

    if err != nil {
        fmt.Println(err)
        return
    }

    hcClient, err := mrs.MrsClientBuilder().
         WithRegion(region.ValueOf("<YOUR REGION>")).
         WithCredential(auth).
         SafeBuild()


    if err != nil {
        fmt.Println(err)
        return
    }

    client := mrs.NewMrsClient(hcClient)

    request := &model.ListNodesRequest{}
	request.ClusterId = "{cluster_id}"
	response, err := client.ListNodes(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}
 
 
  

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Codes	Description
200	List of queried nodes.

Error Codes

See Error Codes.

Parent Topic: Cluster Management APIs

Previous topic: Adding Components to a Cluster - AddComponent

Next topic: Job Management APIs