doc-exports/elb/api-ref/CreatePool.rst

604 lines
57 KiB
ReStructuredText

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 <errorcode.html>`__.
**Parent topic:** `Backend Server Group <topic_300000006.html>`__