Creating a Backend Server Group
Function
This API is used to create a backend server group.
Constraints
Note the following when you create a backend server group:
-
If session_persistence is specified, cookie_name is available only when type is set to APP_COOKIE.
-
If listener_id is specified, the listener must have no backend server group associated.
Calling Method
For details, see Calling APIs.
URI
POST /v3/{project_id}/elb/pools
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
project_id |
Yes |
String |
Definition: Specifies the project ID. For details about how to obtain a project ID, see Obtaining a Project ID. Constraints: N/A Range: The value can contain a maximum of 32 characters, including digits and lowercase letters. Default value: N/A |
Request Parameters
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
X-Auth-Token |
Yes |
String |
Definition: Specifies the token used for IAM authentication. Constraints: N/A Range: N/A Default value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
pool |
Yes |
CreatePoolOption object |
Definition: Specifies the request parameters for creating a backend server group. Constraints: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
admin_state_up |
No |
Boolean |
Definition: Specifies the administrative status of the backend server group. Constraints: The value can only be true. Range: true Default value: true |
az_affinity |
No |
AzAffinity object |
Definition: Specifies how AZ affinity is configured for the backend server group. Constraints: N/A |
description |
No |
String |
Definition: Provides supplementary information about the backend server group. Constraints: N/A Range: N/A Default value: N/A |
lb_algorithm |
Yes |
String |
Definition: Specifies the load balancing algorithm used by the load balancer to route requests to backend servers in the associated backend server group. Constraints:
Range:
Default value: N/A |
listener_id |
No |
String |
Definition: Specifies the ID of the listener with which the backend server group is associated. Constraints:
Range: N/A Default value: N/A |
loadbalancer_id |
No |
String |
Definition: Specifies the ID of the load balancer with which the backend server group is associated. Constraints:
Range: N/A Default value: N/A |
name |
No |
String |
Definition: Specifies the backend server group name. Constraints: N/A Range: N/A Default value: N/A |
project_id |
No |
String |
Definition: Specifies the project ID of the backend server group. Constraints: N/A Range: N/A Default value: N/A |
protocol |
Yes |
String |
Definition: Specifies the protocol used by the backend server group to receive requests. Constraints:
QUIC is not supported. Range: TCP, UDP, IP, TLS, HTTP, HTTPS, GRPC, or QUIC Default value: N/A |
session_persistence |
No |
Definition: Specifies the sticky session. Constraints: Slow start and sticky session cannot be enabled at the same time. If both are enabled, sticky session will be invalid. |
|
slow_start |
No |
CreatePoolSlowStartOption object |
Definition: Specifies slow start details. After you enable slow start, new backend servers added to the backend server group are warmed up, and the number of requests they can receive increases linearly during the configured slow start duration. Constraints:
This parameter is not supported by gateway load balancers. Please do not use it. |
member_deletion_protection_enable |
No |
Boolean |
Definition: Whether to enable removal protection for the backend server. Once the option is enabled, backend servers cannot be removed from the backend server group. Constraints: Once the option is enabled, an error will be returned when the following APIs are called to:
Range: false (disable this option) or true (enable this option). Default value: false
NOTE:
Disable deletion protection or removal protection for your resources before deregistering your account.
This parameter is unsupported. Please do not use it. |
vpc_id |
No |
String |
Definition: Specifies the ID of the VPC where the backend server group works. Constraints:
Range: N/A Default value: N/A |
type |
No |
String |
Definition: Specifies the backend server group type. Constraints:
Range:
Default value: N/A |
ip_version |
No |
String |
Definition: Specifies the IP address version supported by the backend server group. Constraints: N/A Default value: N/A |
quic_cid_hash_strategy |
No |
QuicCidHashStrategy object |
Definition: Specifies multi-path forwarding configuration based on destination connection IDs. Constraints: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
enable |
Yes |
Boolean |
Definition: Specifies whether to enable AZ affinity for the backend server group. If this parameter is set to true, ELB forwards traffic across the backend servers in the same AZ as the load balancer. Constraints:
Range: false (disable this option) or true (enable this option). Default value: N/A |
az_minimum_healthy_member_percentage |
No |
Integer |
Definition: Specifies a percentage that is used to determine the health of an AZ. If the percentage of healthy servers in the AZ of the load balancer falls below the specified value, az_unhealthy_fallback_strategy is triggered. az_minimum_healthy_member_percentage shows the percentage of backend servers that are healthy in a backend server group of an AZ. The number of healthy servers is rounded up. For example, in AZ A, if there are three backend servers in the backend server group and az_minimum_healthy_member_percentage is set to 66%, the number of healthy servers is rounded up to 2 (3 × 0.66 = 1.98). If there are fewer than two healthy servers in AZ A, az_unhealthy_fallback_strategy is triggered. If az_minimum_healthy_member_percentage is set to 67%, the number of healthy servers is rounded up to 3 (3 × 0.67 = 2.01). If there are fewer than three healthy servers in AZ A, az_unhealthy_fallback_strategy is triggered. Constraints:
Range: an integer ranging from -1 to 100. -1 indicates that az_minimum_healthy_member_count takes effect. Default value: N/A |
az_minimum_healthy_member_count |
No |
Integer |
Definition: Specifies a number that is used to determine the health of an AZ. If the number of healthy servers in the AZ of the load balancer falls below the specified value, az_unhealthy_fallback_strategy is triggered. az_minimum_healthy_member_count shows the number of healthy servers in a backend server group of an AZ. Constraints:
Range: an integer ranging from -1 to 10000. -1 indicates that az_minimum_healthy_member_percentage takes effect. Default value: N/A |
az_unhealthy_fallback_strategy |
No |
String |
Definition: Specifies how traffic will be distributed across backend servers in an AZ if the percentage or number of healthy servers in the AZ of the load balancer falls below the specified value. Range:
Constraints: N/A Default value: forward_to_all_member_of_local_az |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
cookie_name |
No |
String |
Definition: Specifies the cookie name. Constraints:
Range: The value can contain a maximum of 1,024 characters. Default value: N/A This parameter is unsupported. Please do not use it. |
type |
Yes |
String |
Definition: Specifies the sticky session type. Constraints:
Range: SOURCE_IP, HTTP_COOKIE, or APP_COOKIE. Default value: N/A |
persistence_timeout |
No |
Integer |
Definition: Specifies the stickiness duration, in minutes. Constraints: This parameter will not take effect when type is set to APP_COOKIE. Range:
Default value: N/A |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
enable |
No |
Boolean |
Definition: Specifies whether to enable slow start. Constraints: N/A Range:
Default value: false |
duration |
No |
Integer |
Definition: Specifies the slow start duration, in seconds. Constraints: N/A Range: 30 to 1200, in seconds. Default value: 30 |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
len |
Yes |
Integer |
Definition: Specifies the length of the hash factor in the connection ID. Constraints: This parameter is valid only when the load balancing algorithm is QUIC_CID. Range: 1 to 20 Default value: 3 |
offset |
Yes |
Integer |
Definition: Specifies the start position in the connection ID as the hash factor. Constraints: This parameter is valid only when the load balancing algorithm is QUIC_CID. Range: 0 to 19 Default value: 1 |
Response Parameters
Status code: 201
Parameter |
Type |
Description |
---|---|---|
request_id |
String |
Definition: Specifies the request ID. Range: The value is automatically generated, and can contain characters including digits, lowercase letters, and hyphens (-). |
pool |
Pool object |
Definition: Specifies the backend server group. |
Parameter |
Type |
Description |
---|---|---|
admin_state_up |
Boolean |
Definition: Specifies the administrative status of the backend server group. The value can only be true. Range: true (enabled) |
az_affinity |
AzAffinity object |
Definition: Specifies how AZ affinity is configured for the backend server group. |
description |
String |
Definition: Provides supplementary information about the backend server group. Range: N/A |
healthmonitor_id |
String |
Definition: Specifies the ID of the health check configured for the backend server group. Range: N/A |
id |
String |
Definition: Specifies the backend server group ID. Range: N/A |
lb_algorithm |
String |
Definition: Specifies the load balancing algorithm used by the load balancer to route requests to backend servers in the associated backend server group. Range:
QUIC_CID is not supported. |
listeners |
Array of ListenerRef objects |
Definition: Specifies the IDs of the listeners with which the backend server group is associated. |
loadbalancers |
Array of LoadBalancerRef objects |
Definition: Specifies the IDs of the load balancers with which the backend server group is associated. |
members |
Array of MemberRef objects |
Definition: Specifies the IDs of backend servers in the backend server group. |
name |
String |
Definition: Specifies the backend server group name. Range: N/A |
project_id |
String |
Definition: Specifies the project ID of the backend server group. Range: N/A |
protocol |
String |
Definition: Specifies the protocol used by the backend server group to receive requests from the load balancer. Constraints: N/A Range: The value can be TCP, UDP, IP, TLS, HTTP, HTTPS, GRPC, or QUIC. Default value: N/A QUIC is not supported. |
session_persistence |
SessionPersistence object |
Definition: Specifies the sticky session. |
ip_version |
String |
Definition: Specifies the IP address version supported by the backend server group. |
slow_start |
SlowStart object |
Definition: Specifies slow start details. After you enable slow start, new backend servers added to the backend server group are warmed up, and the number of requests they can receive increases linearly during the configured slow start duration. This parameter is not supported by gateway load balancers. Please do not use it. |
member_deletion_protection_enable |
Boolean |
Definition: Whether to enable removal protection for the backend server. Once the option is enabled, backend servers cannot be removed from the backend server group. Constraints: Once the option is enabled, an error will be returned when the following APIs are called to:
Range: false (disable this option) or true (enable this option). Default value: false
NOTE:
Disable deletion protection or removal protection for your resources before deregistering your account.
This parameter is unsupported. Please do not use it. |
created_at |
String |
Definition: Specifies the creation time. Range: The value must be a UTC time in the yyyy-MM-dd'T'HH:mm:ss'Z' format. |
updated_at |
String |
Definition: Specifies the update time. Range: The value must be a UTC time in the yyyy-MM-dd'T'HH:mm:ss'Z' format. |
vpc_id |
String |
Definition: Specifies the ID of the VPC where the backend server group works. Range: N/A |
type |
String |
Definition: Specifies the backend server group type. Range:
|
any_port_enable |
Boolean |
Definition: Specifies whether to enable any_port_enable for a backend server group. If this option is enabled, the listener routes the requests to the backend server over the same port as the frontend port. If this option is disabled, the listener routes the requests over the port specified by protocol_port. Constraints: This option is available only for TCP, UDP, or QUIC backend server groups. Range: false (disable this option) or true (enable this option). This parameter is unsupported. Please do not use it. |
connection_drain |
ConnectionDrain object |
Definition: Specifies the configurations of deregistration delay. This parameter takes effect when:
This parameter is unsupported. Please do not use it. |
enterprise_project_id |
String |
Definition: Specifies the ID of the enterprise project. Range:
|
pool_health |
PoolHealth object |
Definition: Specifies the configurations of the pool health feature. |
public_border_group |
String |
Definition: Specifies the public border group. Range:
This parameter is unsupported. Please do not use it. |
quic_cid_hash_strategy |
QuicCidHashStrategy object |
Definition: Specifies multi-path distribution configuration based on destination connection IDs. |
Parameter |
Type |
Description |
---|---|---|
enable |
Boolean |
Definition: Specifies whether to enable AZ affinity for the backend server group. If this parameter is set to true, ELB forwards traffic across the backend servers in the same AZ as the load balancer. Constraints:
Range: false (disable this option) or true (enable this option). Default value: N/A |
az_minimum_healthy_member_percentage |
Integer |
Definition: Specifies a percentage that is used to determine the health of an AZ. If the percentage of healthy servers in the AZ of the load balancer falls below the specified value, az_unhealthy_fallback_strategy is triggered. az_minimum_healthy_member_percentage shows the percentage of backend servers that are healthy in a backend server group of an AZ. The number of healthy servers is rounded up. For example, in AZ A, if there are three backend servers in the backend server group and az_minimum_healthy_member_percentage is set to 66%, the number of healthy servers is rounded up to 2 (3 × 0.66 = 1.98). If there are fewer than two healthy servers in AZ A, az_unhealthy_fallback_strategy is triggered. If az_minimum_healthy_member_percentage is set to 67%, the number of healthy servers is rounded up to 3 (3 × 0.67 = 2.01). If there are fewer than three healthy servers in AZ A, az_unhealthy_fallback_strategy is triggered. Constraints:
Range: an integer ranging from -1 to 100. -1 indicates that az_minimum_healthy_member_count takes effect. Default value: N/A |
az_minimum_healthy_member_count |
Integer |
Definition: Specifies a number that is used to determine the health of an AZ. If the number of healthy servers in the AZ of the load balancer falls below the specified value, az_unhealthy_fallback_strategy is triggered. az_minimum_healthy_member_count shows the number of healthy servers in a backend server group of an AZ. Constraints:
Range: an integer ranging from -1 to 10000. -1 indicates that az_minimum_healthy_member_percentage takes effect. Default value: N/A |
az_unhealthy_fallback_strategy |
String |
Definition: Specifies how traffic will be distributed across backend servers in an AZ if the percentage or number of healthy servers in the AZ of the load balancer falls below the specified value. Range:
Constraints: N/A Default value: forward_to_all_member_of_local_az |
Parameter |
Type |
Description |
---|---|---|
id |
String |
Definition: Specifies the listener ID. Range: N/A |
Parameter |
Type |
Description |
---|---|---|
id |
String |
Definition: Specifies the load balancer ID. |
Parameter |
Type |
Description |
---|---|---|
id |
String |
Definition: Specifies the backend server ID. |
Parameter |
Type |
Description |
---|---|---|
cookie_name |
String |
Definition: Specifies the cookie name. Range: The value can contain a maximum of 1,024 characters. This parameter is unsupported. Please do not use it. |
type |
String |
Definition: Specifies the sticky session type. Constraints:
Range: SOURCE_IP, HTTP_COOKIE, or APP_COOKIE. |
persistence_timeout |
Integer |
Definition: Specifies the stickiness duration, in minutes. This parameter will not take effect when type is set to APP_COOKIE. Range:
|
Parameter |
Type |
Description |
---|---|---|
enable |
Boolean |
Definition: Specifies whether to enable slow start. Range:
|
duration |
Integer |
Definition: Specifies the slow start duration, in seconds. Range: 30 to 1200, in seconds. |
Parameter |
Type |
Description |
---|---|---|
enable |
Boolean |
Definition: Specifies whether to enable connection_drain. Constraints: N/A Range: The value can be true (enable this option) or false (disable this option). Default value: N/A |
timeout |
Integer |
Definition: Specifies the deregistration delay timeout, in seconds. Constraints: N/A Range: 10 to 4000, in seconds. Constraints: N/A |
Parameter |
Type |
Description |
---|---|---|
minimum_healthy_member_count |
Integer |
Definition: Specifies the number of healthy backend servers below which the backend server group is considered as unhealthy. Constraints: N/A Range:
Default value: N/A This parameter is unsupported. Please do not use it. |
Parameter |
Type |
Description |
---|---|---|
len |
Integer |
Definition: Specifies the length of the hash factor in the connection ID. Constraints: This parameter is valid only when the load balancing algorithm is QUIC_CID. Range: 1 to 20 Default value: 3 |
offset |
Integer |
Definition: Specifies the start position in the connection ID as the hash factor. Constraints: This parameter is valid only when the load balancing algorithm is QUIC_CID. Range: 0 to 19 Default value: 1 |
Example Requests
-
Creating a backend server group and setting its backend protocol to TCP
POST https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/pools { "pool" : { "name" : "My pool", "lb_algorithm" : "LEAST_CONNECTIONS", "listener_id" : "0b11747a-b139-492f-9692-2df0b1c87193", "protocol" : "TCP", "member_deletion_protection_enable" : false } }
-
Creating a backend server group and setting its backend protocol to HTTP
POST https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/pools { "pool" : { "name" : "My pool", "lb_algorithm" : "LEAST_CONNECTIONS", "listener_id" : "0b11747a-b139-492f-9692-2df0b1c87193", "protocol" : "HTTP", "slow_start" : { "enable" : true, "duration" : 50 }, "member_deletion_protection_enable" : false } }
-
Creating an IP backend server group for a gateway load balancer
POST https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/pools { "pool" : { "name" : "My IP pool", "lb_algorithm" : "2_tuple_hash", "listener_id" : "0b11747a-b139-492f-9692-2df0b1c87193", "protocol" : "IP", "type" : "instance", "member_deletion_protection_enable" : false } }
Example Responses
Status code: 201
Successful request.
{ "pool" : { "type" : "", "vpc_id" : "", "lb_algorithm" : "LEAST_CONNECTIONS", "protocol" : "TCP", "description" : "", "admin_state_up" : true, "member_deletion_protection_enable" : false, "loadbalancers" : [ { "id" : "098b2f68-af1c-41a9-8efd-69958722af62" } ], "project_id" : "99a3fff0d03c428eac3678da6a7d0f24", "session_persistence" : null, "healthmonitor_id" : null, "listeners" : [ { "id" : "0b11747a-b139-492f-9692-2df0b1c87193" } ], "members" : [ ], "id" : "36ce7086-a496-4666-9064-5ba0e6840c75", "name" : "My pool", "ip_version" : "v4", "slow_start" : null }, "request_id" : "2d974978-0733-404d-a21a-b29204f4803a" }
Status Codes
Status Code |
Description |
---|---|
201 |
Successful request. |
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.