Help Center/ CodeArts Deploy/ API Reference (Ally Region)/ APIs/ Managing Host Clusters/ Creating a Host Cluster (Recommended)
Updated on 2026-01-15 GMT+08:00
Online Debugging
CLI Examples
Share

Creating a Host Cluster (Recommended)

Function

This API is used to create a host cluster in a project.

Calling Method

For details, see Calling APIs.

URI

POST /v1/resources/host-groups

Request Parameters

Table 1 Request header parameters

Parameter

Mandatory

Type

Description

Content-Type

Yes

String

Definition:

Type (or format) of the message body.

Constraints:

N/A.

Value range:

N/A.

Default value:

N/A.

X-Auth-Token

Yes

String

Definition:

User token. Obtain a token (the value of the X-Subject-Token response header) by calling the IAM API used for.

Constraints:

N/A.

Value range:

String. Max. 20,000 characters.

Default value:

N/A.
Table 2 Request body parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Parameter description:

Host cluster name.

Constraints:

N/A

Value range:

The value consists of 3-128 characters. Only letters, digits, hyphens (-), underscores (_), and periods (.) are allowed.

Default value:

N/A

project_id

Yes

String

Parameter description:

Project ID. For details, see Obtaining a Project ID.

Constraints:

N/A

Value range:

The value consists of 32 characters. Only letters and digits are allowed.

Default value:

N/A

os

Yes

String

Parameter description:

OS of the host cluster.

Constraints:

N/A

Value range:

  • Windows: Windows OS.

  • Linux: Linux OS.

Default value:

N/A

slave_cluster_id

No

String

Definition:

Slave cluster ID. It is empty by default. When it is empty, the default agent pool is used.

Constraints:

N/A.

Value range:

1 to 32 characters, including letters and digits.

Default value:

N/A.

description

No

String

Parameter description:

Host cluster description.

Constraints:

N/A

Value range:

The value is a string of 0 to 500 characters.

Default value:

N/A

is_proxy_mode

Yes

Integer

Parameter description:

Whether the host cluster is in the proxy mode.

Constraints:

N/A

Value range:

  • 0: Non-proxy mode host cluster.

  • 1: Proxy mode host cluster.

Default value:

N/A

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

id

String

Parameter description:

Host cluster ID.

Value range:

The value consists of 32 characters. Only letters and digits are allowed.

status

String

Parameter description:

Request success or failure status.

Value range:

  • success: Request succeeded

  • failed: Request failed

Example Requests

When creating a host cluster, you need to enter basic information, including the host cluster name, description, operating system, and whether be proxy access mode.

https://{endpoint}/v1/resources/host-groups

{
  "name" : "test123",
  "description" : "",
  "project_id" : "6039d4480efc4dddb178abff98719913",
  "os" : "linux",
  "slave_cluster_id" : "",
  "is_proxy_mode" : 1
}

Example Responses

Status code: 200

OK: The request is successful.

{
  "status" : "success",
  "id" : "f3938bd63e354d2bb9d9cf7b5dc3bf95"
}

Status Codes

Status Code

Description

200

OK: The request is successful.

Error Codes

See Error Codes.

Parent topic: Managing Host Clusters