Help Center/ CodeArts Deploy/ API Reference/ APIs/ Managing Host Clusters/ Creating a Host Cluster (Recommended)
Updated on 2025-05-27 GMT+08:00
View PDF

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

Message body type (format).

X-Auth-Token

Yes

String

User token. It can be obtained by calling an IAM API. The value of X-Subject-Token in the response header is the user token.
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] (CloudDeploy_api_0014.xml).

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

Parameter description:

Slave cluster ID. If the ID is left empty, the official resource pool is used by default. The self-hosted resource pool is used when the self-hosted resource pool slave cluster ID is transferred.

Constraints:

N/A

Value range:

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

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