All Products
Search

This Product

    Container Service for Kubernetes:DescribeClusterNodes

    Document Center

    Container Service for Kubernetes:DescribeClusterNodes

    Last Updated:Jun 23, 2026

    Queries the list of nodes that meet the specified conditions in a cluster.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    cs:DescribeClusterNodes

    get

    *Cluster

    acs:cs:{#regionId}:{#accountId}:cluster/{#ClusterId}

    		 None None

    Request syntax

    GET /clusters/{ClusterId}/nodes HTTP/1.1

    Path Parameters

    Parameter

    Type

    Required

    Description

    Example
    ClusterId

    string

    Yes

    The cluster ID.

    c82e6987e2961451182edacd74faf****

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    instanceIds

    string

    No

    The list of node instance IDs. Separate multiple IDs with commas (,).

    "i-bp11xjhwkj8k966u****,i-bp1dmhc2bu5igkyq****"
    nodepool_id

    string

    No

    The node pool ID.

    npe25633140a7d4fbea56cd0479c******
    state

    string

    No

    The cluster node status. Filters nodes by their running status. Valid values:

    • all: does not filter by running status. Queries nodes in all states.

    • running: running nodes.

    • removing: nodes being removed.

    • initial: nodes being initialized.

    • failed: nodes that failed to be created.

    Default value: all.

    running
    pageSize

    string

    No

    The maximum number of records that can be displayed per page. Valid values: [1,100].

    Default value: 10.

    10
    pageNumber

    string

    No

    The page number of the current query.

    Default value: 1.

    1

    Response elements

    Element

    Type

    Description

    Example

    object

    The response body.

    nodes

    array<object>

    The list of node details.

    object

    The node details.

    creation_time

    string

    The time when the node was created.

    2025-04-16T07:28:00Z
    error_message

    string

    The error message generated when the node was created.

    error***
    expired_time

    string

    The time when the node expires.

    2099-12-31T15:59:00Z
    host_name

    string

    The hostname of the node.

    iZ2vcckdmxp7u0urj2k****
    image_id

    string

    The ID of the system image used by the node.

    aliyun_3_x64_20G_alibase_20241218.vhd
    instance_charge_type

    string

    The billing method of the node. Valid values:

    • PrePaid: subscription.

    • PostPaid: pay-as-you-go.

    PostPaid
    instance_id

    string

    The instance ID of the node.

    i-2vcckdmxp7u0urj2****
    instance_name

    string

    The name of the node in the cluster.

    worker-k8s-for-cs-c5cdf7e3938bc4f8eb0e44b21a80f****
    instance_role

    string

    The role type of the node. Valid values:

    • Master: a master node of the cluster.

    • Worker: a worker node of the cluster.

    Worker
    instance_status

    string

    The ECS status of the node. Valid values:

    • Pending: being created.

    • Running: running.

    • Starting: being started.

    • Stopping: being stopped.

    • Stopped: stopped.

    Running
    instance_type

    string

    The node specifications.

    ecs.c5.xlarge
    instance_type_family

    string

    The name of the ECS instance family to which the node belongs.

    ecs.c5
    ip_address

    array

    The IP addresses of the node.

    string

    The IP address.

    192.168.xx.xx
    is_aliyun_node

    boolean

    Indicates whether the node is an Alibaba Cloud instance. Valid values:

    • true: The node is an Alibaba Cloud instance.

    • false: The node is not an Alibaba Cloud instance.

    true
    node_name

    string

    The node name, which is the identifier of the node within the cluster.

    cn-chengdu.192.168xx.xx
    node_status

    string

    Indicates whether the node is ready. Valid values:

    • Ready: The node is ready.

    • NotReady: The node is not ready.

    • Unknown: The node status is unknown.

    • Offline: The node is offline.

    Ready
    nodepool_id

    string

    The node pool ID.

    np0794239424a84eb7a95327369d56****
    source

    string

    The method used to initialize the node, such as manual creation or ROS creation.

    ess
    state

    string

    The running status of the node. Valid values:

    • pending: being created.

    • running: running.

    • starting: being started.

    • stopping: being stopped.

    • stopped: stopped.

    running
    spot_strategy

    string

    The spot instance type. Valid values:

    • NoSpot: a non-spot instance.

    • SpotWithPriceLimit: a spot instance with a price limit.

    • SpotAsPriceGo: a spot instance priced at the market price.

    NoSpot
    page

    object

    The pagination information.

    page_number

    integer

    The current page number.

    1
    page_size

    integer

    The maximum number of records that can be displayed per page.

    10
    total_count

    integer

    The total number of results.

    5

    Examples

    Success response

    JSON format

    {
  "nodes": [
    {
      "creation_time": "2025-04-16T07:28:00Z",
      "error_message": "error***",
      "expired_time": "2099-12-31T15:59:00Z",
      "host_name": "iZ2vcckdmxp7u0urj2k****",
      "image_id": "aliyun_3_x64_20G_alibase_20241218.vhd",
      "instance_charge_type": "PostPaid",
      "instance_id": "i-2vcckdmxp7u0urj2****",
      "instance_name": "worker-k8s-for-cs-c5cdf7e3938bc4f8eb0e44b21a80f****",
      "instance_role": "Worker",
      "instance_status": "Running",
      "instance_type": "ecs.c5.xlarge",
      "instance_type_family": "ecs.c5",
      "ip_address": [
        "192.168.xx.xx"
      ],
      "is_aliyun_node": true,
      "node_name": "cn-chengdu.192.168xx.xx",
      "node_status": "Ready",
      "nodepool_id": "np0794239424a84eb7a95327369d56****",
      "source": "ess",
      "state": "running",
      "spot_strategy": "NoSpot"
    }
  ],
  "page": {
    "page_number": 1,
    "page_size": 10,
    "total_count": 5
  }
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.