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

Batch Draining Nodes

Function

This API is used to batch drain nodes. You can use this API to stop the service processing capabilities of specified nodes and release related resources. This API applies to the following scenarios: When the system needs to isolate faults urgently, reclaim resources, perform version upgrade or maintenance operations, you can use this API to suspend the service traffic of the target nodes in batches to ensure service stability during operations. Before using this API, ensure that the target nodes already exist, you have the administrator permissions, the nodes are running and not locked, and the resource pool meets the capacity constraints after drainage (for example, the minimum number of available nodes). In addition, a valid node list and drainage policies (for example, immediate drainage or delayed drainage) must be provided as input parameters. After the operation is complete, the specified node stops receiving new tasks and gradually releases resources. The original service data is retained or migrated according to the policies. If issues arise, like missing nodes, insufficient permissions, incorrect node states (like under maintenance), insufficient capacity of resource pools, or missing input parameters, the system returns errors such as 404 (Node not found), 403 (Permission denied), and 400 (Parameter verification failed).

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

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 permission required for calling this API.

URI

POST /v2/{project_id}/pools/{pool_name}/nodes/batch-drain

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition: Project ID. For details, see Obtaining a Project ID and Name. Constraints: The value can contain 1 to 64 characters. Only letters, digits, and hyphens (-) are allowed. Range: N/A Default Value: N/A
pool_name	Yes	String	Definition: Resource pool ID. The value is the metadata.name field in the resource pool details. Constraints: N/A *Range: The value can contain 36 to 63 characters. It must start with a lowercase letter and cannot end with a hyphen (-). Digits and hyphens (-) are allowed. Default Value: N/A

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
nodeNames	Yes	Array of strings	Definition: Node names. Constraints: A maximum of 10 nodes are allowed.

Response Parameters

Status code: 200

Succeeded.

Status code: 400

**Table 3** Response body parameters
Parameter	Type	Description
error_code	String	Definition: ModelArts error code. Range: N/A
error_msg	String	Definition: Error message. Range: N/A

Example Requests

/v2/{project_id}/pools/{pool_name}/nodes/batch-drain

{
  "nodeNames" : [ "os-node-created-xzz78" ]
}

Example Responses

Status code: 200

Succeeded.

{ }

Status code: 400

Not found.

{
  "error_code" : "ModelArts.50004000",
  "error_msg" : "Bad request. node cannot be drained because it is not in pool"
}

Status Codes

Status Code	Description
200	Succeeded.
400	Not found.

Error Codes

See Error Codes.

Parent topic: Node Management