Creating a Backend Server Group =============================== Function ^^^^^^^^ This API is used to create a backend server group. Constraints ^^^^^^^^^^^ 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. URI ^^^ POST /v3/{project_id}/elb/pools .. table:: **Table 1** Path parameters ========== ========= ====== ========================= Parameter Mandatory Type Description ========== ========= ====== ========================= project_id Yes String Specifies the project ID. ========== ========= ====== ========================= Request Parameters ^^^^^^^^^^^^^^^^^^ .. table:: **Table 2** Request header parameters ============ ========= ====== ================================================ Parameter Mandatory Type Description ============ ========= ====== ================================================ X-Auth-Token Yes String Specifies the token used for IAM authentication. ============ ========= ====== ================================================ .. table:: **Table 3** Request body parameters +-----------+-----------+---------------------------------------------------------------------+-------------------------------------+ | Parameter | Mandatory | Type | Description | +===========+===========+=====================================================================+=====================================+ | pool | Yes | `CreatePoolOption <#CreatePool__request_CreatePoolOption>`__ object | Specifies the backend server group. | +-----------+-----------+---------------------------------------------------------------------+-------------------------------------+ .. table:: **Table 4** CreatePoolOption +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | Parameter | Mandatory | Type | Description | +=============================+=============================+=============================+=============================+ | admin_state_up | No | Boolean | Specifies the | | | | | administrative status of | | | | | the backend server group. | | | | | The value can only be | | | | | updated to **true**. | | | | | | | | | | This parameter is | | | | | unsupported. Please do not | | | | | use it. | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | description | No | String | Provides supplementary | | | | | information about the | | | | | backend server group. | | | | | | | | | | Minimum: **0** | | | | | | | | | | Maximum: **255** | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | lb_algorithm | Yes | String | Specifies the load | | | | | balancing algorithm used by | | | | | the load balancer to route | | | | | requests to backend | | | | | servers. | | | | | | | | | | The value can be one of the | | | | | following: | | | | | | | | | | - **ROUND_ROBIN**: | | | | | weighted round robin | | | | | | | | | | - **LEAST_CONNECTIONS**: | | | | | weighted least | | | | | connections | | | | | | | | | | - **SOURCE_IP**: source IP | | | | | hash | | | | | | | | | | When the value is | | | | | **SOURCE_IP**, the weights | | | | | of backend servers are | | | | | invalid. | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | listener_id | No | String | Specifies the ID of the | | | | | listener associated with | | | | | the backend server group. | | | | | Specify either | | | | | **listener_id** or | | | | | **loadbalancer_id**, or | | | | | both of them. | | | | | | | | | | Minimum: **1** | | | | | | | | | | Maximum: **36** | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | loadbalancer_id | No | String | Specifies the ID of the | | | | | associated load balancer. | | | | | Specify either | | | | | **listener_id** or | | | | | **loadbalancer_id**, or | | | | | both of them. | | | | | | | | | | Minimum: **1** | | | | | | | | | | Maximum: **36** | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | name | No | String | Specifies the backend | | | | | server group name. | | | | | | | | | | Minimum: **0** | | | | | | | | | | Maximum: **255** | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | project_id | No | String | Specifies the project ID. | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | protocol | Yes | String | Specifies the protocol used | | | | | by the backend server group | | | | | to receive requests. TCP, | | | | | UDP, and HTTP are | | | | | supported. | | | | | | | | | | - For UDP listeners, the | | | | | protocol of the backend | | | | | server group must be | | | | | UDP. | | | | | | | | | | - For TCP listeners, the | | | | | protocol of the backend | | | | | server group must be | | | | | TCP. | | | | | | | | | | - For HTTP or HTTPS | | | | | listeners, the protocol | | | | | of the backend server | | | | | group must be HTTP. | | | | | | | | | | Minimum: **1** | | | | | | | | | | Maximum: **255** | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | session_persistence | No | `CreatePoolSess | Specifies whether to enable | | | | ionPersistenceOption <#Crea | sticky sessions. | | | | tePool__request_CreatePoolS | | | | | essionPersistenceOption>`__ | | | | | object | | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | slow_start | No | `CreatePoolSlowStartOpti | Specifies whether to enable | | | | on <#CreatePool__request_Cr | slow start. After you | | | | eatePoolSlowStartOption>`__ | enable slow start, new | | | | object | 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 can be used | | | | | when the protocol of the | | | | | backend server group is | | | | | HTTP or HTTPS. An error | | | | | will be returned if the | | | | | protocol is not HTTP or | | | | | HTTPS. | | | | | | | | | | This parameter is | | | | | unsupported. Please do not | | | | | use it. | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ .. table:: **Table 5** CreatePoolSessionPersistenceOption +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | Parameter | Mandatory | Type | Description | +=============================+=============================+=============================+=============================+ | cookie_name | No | String | Specifies the cookie name. | | | | | This parameter will take | | | | | effect only when **type** | | | | | is set to **APP_COOKIE**. | | | | | Otherwise, an error will be | | | | | returned. | | | | | | | | | | The value can contain only | | | | | letters, digits, hyphens | | | | | (-), underscores (_), and | | | | | periods (.). | | | | | | | | | | Minimum: **0** | | | | | | | | | | Maximum: **1024** | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | type | Yes | String | Specifies the sticky | | | | | session type. The value can | | | | | be **SOURCE_IP**, | | | | | **HTTP_COOKIE**, or | | | | | **APP_COOKIE**. | | | | | | | | | | - If the protocol of the | | | | | backend server group is | | | | | TCP or UDP, only | | | | | **SOURCE_IP** takes | | | | | effect. | | | | | | | | | | - For dedicated load | | | | | balancers, if the | | | | | protocol of the backend | | | | | server group is HTTP or | | | | | HTTPS, the value can | | | | | only be **HTTP_COOKIE**. | | | | | | | | | | - For shared load | | | | | balancers, if the | | | | | protocol of the backend | | | | | server group is HTTP or | | | | | HTTPS, the value can be | | | | | **HTTP_COOKIE** or | | | | | **APP_COOKIE**. | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | persistence_timeout | No | Integer | Specifies the stickiness | | | | | duration, in minutes. This | | | | | parameter will not take | | | | | effect when **type** is set | | | | | to **APP_COOKIE**. | | | | | | | | | | - If the protocol of the | | | | | backend server group is | | | | | TCP or UDP, the value | | | | | ranges from **1** to | | | | | **60**, and the default | | | | | value is **1**. | | | | | | | | | | - If the protocol of the | | | | | backend server group is | | | | | HTTP or HTTPS, the value | | | | | ranges from **1** to | | | | | **1440**, and the | | | | | default value is | | | | | **1440**. | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ .. table:: **Table 6** CreatePoolSlowStartOption +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | Parameter | Mandatory | Type | Description | +=============================+=============================+=============================+=============================+ | enable | Yes | Boolean | Specifies whether to enable | | | | | slow start. | | | | | | | | | | **true** indicates that | | | | | this function is enabled, | | | | | and **false** indicates | | | | | this function is disabled. | | | | | | | | | | Default: **false** | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ | duration | Yes | Integer | Specifies the slow start | | | | | duration, in seconds. | | | | | | | | | | The value ranges from | | | | | **30** to **1200**, and the | | | | | default value is **30**. | | | | | | | | | | Minimum: **30** | | | | | | | | | | Maximum: **1200** | | | | | | | | | | Default: **30** | +-----------------------------+-----------------------------+-----------------------------+-----------------------------+ Response Parameters ^^^^^^^^^^^^^^^^^^^ **Status code: 201** .. table:: **Table 7** Response body parameters ========== ============================================ =============================================================== Parameter Type Description ========== ============================================ =============================================================== request_id String Specifies the request ID. The value is automatically generated. pool `Pool <#CreatePool__response_Pool>`__ object Specifies the backend server group. ========== ============================================ =============================================================== .. table:: **Table 8** Pool +---------------------------------------+---------------------------------------+---------------------------------------+ | Parameter | Type | Description | +=======================================+=======================================+=======================================+ | admin_state_up | Boolean | Specifies the administrative status | | | | of the backend server group. The | | | | value can only be updated to | | | | **true**. | | | | | | | | This parameter is unsupported. Please | | | | do not use it. | | | | | | | | Default: **true** | +---------------------------------------+---------------------------------------+---------------------------------------+ | description | String | Provides supplementary information | | | | about the backend server group. | +---------------------------------------+---------------------------------------+---------------------------------------+ | healthmonitor_id | String | Specifies the ID of the health check | | | | configured for the backend server | | | | group. | +---------------------------------------+---------------------------------------+---------------------------------------+ | id | String | Specifies the backend server group | | | | ID. | +---------------------------------------+---------------------------------------+---------------------------------------+ | lb_algorithm | String | Specifies the load balancing | | | | algorithm used by the load balancer | | | | to route requests to backend servers | | | | in the backend server group. | | | | | | | | The value can be **ROUND_ROBIN** | | | | (weighted round robin), | | | | **LEAST_CONNECTIONS** (weighted least | | | | connections), or **SOURCE_IP** | | | | (source IP hash). | | | | | | | | When the value is **SOURCE_IP**, the | | | | **weight** parameter is invalid. | +---------------------------------------+---------------------------------------+---------------------------------------+ | listeners | Array of | Lists the listeners associated with | | | `ListenerRef < | the backend server group. | | | #CreatePool__response_ListenerRef>`__ | | | | objects | | +---------------------------------------+---------------------------------------+---------------------------------------+ | loadbalancers | Array of | Lists the IDs of load balancers | | | `LoadBalancerRef <#Cre | associated with the backend server | | | atePool__response_LoadBalancerRef>`__ | group. | | | objects | | | | | If only **listener_id** is specified | | | | during the creation of the backend | | | | server group, the ID of the | | | | **loadbalancers** parameter in the | | | | response is the ID of the load | | | | balancer to which the listener is | | | | added. | +---------------------------------------+---------------------------------------+---------------------------------------+ | members | Array of | Lists the backend servers in the | | | `MemberRef | backend server group. | | | <#CreatePool__response_MemberRef>`__ | | | | objects | | +---------------------------------------+---------------------------------------+---------------------------------------+ | name | String | Specifies the backend server group | | | | name. | +---------------------------------------+---------------------------------------+---------------------------------------+ | project_id | String | Specifies the project ID. | +---------------------------------------+---------------------------------------+---------------------------------------+ | protocol | String | Specifies the protocol used by the | | | | backend server group to receive | | | | requests. The protocol can be TCP, | | | | UDP, or HTTP. | | | | | | | | - For UDP listeners, the protocol of | | | | the backend server group must be | | | | UDP. | | | | | | | | - For TCP listeners, the protocol of | | | | the backend server group must be | | | | TCP. | | | | | | | | - For HTTP or HTTPS listeners, the | | | | protocol of the backend server | | | | group must be HTTP. | +---------------------------------------+---------------------------------------+---------------------------------------+ | session_persistence | `SessionPersistence <#Create | Specifies the sticky session. | | | Pool__response_SessionPersistence>`__ | | | | object | | +---------------------------------------+---------------------------------------+---------------------------------------+ | ip_version | String | Specifies the IP version supported by | | | | the backend server group. | | | | | | | | - Shared load balancers: The default | | | | value is **v4**. | | | | | | | | - Dedicated load balancers: The | | | | value can be **dualstack**, | | | | **v4**, or **v6**. | | | | | | | | When the protocol of the backend | | | | server group is TCP or UDP, | | | | **ip_version** is set to | | | | **dualstack**, indicating that both | | | | IPv4 and IPv6 are supported. | | | | | | | | When the protocol of the backend | | | | server group is HTTP, **ip_version** | | | | is set to **v4**. | | | | | | | | IPv6 is unsupported. Only **v4** is | | | | returned. | | | | | | | | Default: **dualstack** | +---------------------------------------+---------------------------------------+---------------------------------------+ | slow_start | `SlowStart | Specifies whether to enable slow | | | <#CreatePool__response_SlowStart>`__ | start. After you enable slow start, | | | object | 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 can be used when the | | | | protocol of the backend server group | | | | is HTTP or HTTPS. An error will be | | | | returned if the protocol is not HTTP | | | | or HTTPS. | | | | | | | | This parameter is unsupported. Please | | | | do not use it. | +---------------------------------------+---------------------------------------+---------------------------------------+ .. table:: **Table 9** ListenerRef ========= ====== ========================== Parameter Type Description ========= ====== ========================== id String Specifies the listener ID. ========= ====== ========================== .. table:: **Table 10** LoadBalancerRef ========= ====== =============================== Parameter Type Description ========= ====== =============================== id String Specifies the load balancer ID. ========= ====== =============================== .. table:: **Table 11** MemberRef ========= ====== ================================ Parameter Type Description ========= ====== ================================ id String Specifies the backend server ID. ========= ====== ================================ .. table:: **Table 12** SessionPersistence +---------------------------------------+---------------------------------------+---------------------------------------+ | Parameter | Type | Description | +=======================================+=======================================+=======================================+ | cookie_name | String | Specifies the cookie name. | | | | | | | | This parameter will take effect only | | | | when **type** is set to | | | | **APP_COOKIE**. | | | | | | | | The value can contain only letters, | | | | digits, hyphens (-), underscores (_), | | | | and periods (.). | | | | | | | | Minimum: **0** | | | | | | | | Maximum: **1024** | +---------------------------------------+---------------------------------------+---------------------------------------+ | type | String | Specifies the sticky session type. | | | | The value can be **SOURCE_IP**, | | | | **HTTP_COOKIE**, or **APP_COOKIE**. | | | | | | | | - If the protocol of the backend | | | | server group is TCP or UDP, only | | | | **SOURCE_IP** takes effect. | | | | | | | | - For dedicated load balancers, if | | | | the protocol of the backend server | | | | group is HTTP or HTTPS, the value | | | | can only be **HTTP_COOKIE**. | | | | | | | | - For shared load balancers, if the | | | | protocol of the backend server | | | | group is HTTP or HTTPS, the value | | | | can be **HTTP_COOKIE** or | | | | **APP_COOKIE**. | +---------------------------------------+---------------------------------------+---------------------------------------+ | persistence_timeout | Integer | Specifies the stickiness duration, in | | | | minutes. This parameter will not take | | | | effect when **type** is set to | | | | **APP_COOKIE**. | | | | | | | | - If the protocol of the backend | | | | server group is TCP or UDP, the | | | | value ranges from **1** to **60**, | | | | and the default value is **1**. | | | | | | | | - If the protocol of the backend | | | | server group is HTTP or HTTPS, the | | | | value ranges from **1** to | | | | **1440**, and the default value is | | | | **1440**. | +---------------------------------------+---------------------------------------+---------------------------------------+ .. table:: **Table 13** SlowStart +---------------------------------------+---------------------------------------+---------------------------------------+ | Parameter | Type | Description | +=======================================+=======================================+=======================================+ | enable | Boolean | Specifies whether to enable slow | | | | start. | | | | | | | | **true** indicates that this function | | | | is enabled, and **false** indicates | | | | this function is disabled. | | | | | | | | Default: **false** | +---------------------------------------+---------------------------------------+---------------------------------------+ | duration | Integer | Specifies the slow start duration, in | | | | seconds. | | | | | | | | The value ranges from **30** to | | | | **1200**, and the default value is | | | | **30**. | | | | | | | | Minimum: **30** | | | | | | | | Maximum: **1200** | | | | | | | | Default: **30** | +---------------------------------------+---------------------------------------+---------------------------------------+ Example Requests ^^^^^^^^^^^^^^^^ Adding an HTTP backend server group .. code:: screen 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 } } } Example Responses ^^^^^^^^^^^^^^^^^ **Status code: 201** Successful request. .. code:: screen { "pool" : { "lb_algorithm" : "LEAST_CONNECTIONS", "protocol" : "HTTP", "description" : "", "admin_state_up" : true, "loadbalancers" : [ { "id" : "098b2f68-af1c-41a9-8efd-69958722af62" } ], "project_id" : "99a3fff0d03c428eac3678da6a7d0f24", "listeners" : [ { "id" : "0b11747a-b139-492f-9692-2df0b1c87193" } ], "members" : [ ], "id" : "36ce7086-a496-4666-9064-5ba0e6840c75", "name" : "My pool", "ip_version" : "v4", "slow_start" : { "enable" : true, "duration" : 50 } }, "request_id" : "2d974978-0733-404d-a21a-b29204f4803a" } Status Codes ^^^^^^^^^^^^ =========== =================== Status Code Description =========== =================== 201 Successful request. =========== =================== Error Codes ^^^^^^^^^^^ See `Error Codes `__. **Parent topic:** `Backend Server Group `__