openstack/octavia
Code Issues Proposed changes

Add v2 pool API section

Browse Source 
This patch adds the pool section to the v2 API reference.

Change-Id: I70e5cb07a4435f58f5da3999be70162efa7f0bd8
Partial-Bug: #1558385
This commit is contained in:
johnsom 2017-04-19 11:53:27 -07:00
parent 875cb2db03
commit 639aa1cd04
27 changed files with 718 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
api-ref/source/parameters.yaml
View File

@ -19,6 +19,12 @@ path-loadbalancer-id:
in: path
required: true
type: string
path-pool-id:
description: |
The ID of the pool to query.
in: path
required: true
type: string
###############################################################################
# Query fields
###############################################################################
@ -40,12 +46,6 @@ project_id_query:
in: query
required: false
type: string
tenant_id_query:
description: |
The ID of the project to query. (deprecated)
in: query
required: false
type: string
###############################################################################
# Body fields
@ -194,9 +194,15 @@ flavor-id-optional:
in: body
required: false
type: string
healthmonitor-id:
description: |
The associated health monitor ID.
in: body
required: true
type: string
healthmonitor-status:
description: |
The associated healthmonitor status object.
The associated health monitor status object.
in: body
required: true
type: object
@ -246,6 +252,20 @@ l7rules-status-object-list:
in: body
required: true
type: array
lb-algorithm:
description: |
The load balancing algorithm for the pool. One of ``LEAST_CONNECTIONS``,
``ROUND_ROBIN``, or ``SOURCE_IP``.
in: body
required: true
type: string
lb-algorithm-optional:
description: |
The load balancing algorithm for the pool. One of ``LEAST_CONNECTIONS``,
``ROUND_ROBIN``, or ``SOURCE_IP``.
in: body
required: false
type: string
listener:
description: |
A listener object.
@ -258,6 +278,18 @@ listener-id:
in: body
required: true
type: string
listener-id-pool-optional:
description: |
The ID of the listener for the pool. Either ``listener_id`` or ``loadbalancer_id`` must be specified.
in: body
required: false
type: string
listener-ids:
description: |
A list of listener IDs.
in: body
required: true
type: array
listeners:
description: |
The associated listener IDs, if any.
@ -288,6 +320,12 @@ loadbalancer-id:
in: body
required: true
type: string
loadbalancer-id-pool-optional:
description: |
The ID of the load balancer for the pool. Either ``listener_id`` or ``loadbalancer_id`` must be specified.
in: body
required: false
type: string
loadbalancer-ids:
description: |
A list of load balancer IDs.
@ -306,6 +344,12 @@ loadbalancers:
in: body
required: true
type: array
member-ids:
description: |
A list of member IDs.
in: body
required: true
type: array
members-status-object-list:
description: |
A list of members status objects.
@ -330,6 +374,12 @@ operating_status:
in: body
required: true
type: string
pool-id:
description: |
The ID of the pool.
in: body
required: true
type: string
pool-optional:
description: |
A pool object.
@ -372,6 +422,12 @@ protocol:
in: body
required: true
type: integer
protocol-pools:
description: |
The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``PROXY``, or ``TCP``.
in: body
required: true
type: string
protocol_port:
description: |
The protocol port number for the resource.
@ -402,6 +458,36 @@ request_errors:
in: body
required: true
type: integer
session_persistence:
description: |
A JSON object specifying the session persistence for the pool or ``null``
for no session persistence. See :ref:`session_persistence`. Default is
``null``.
in: body
required: true
type: object
session_persistence-optional:
description: |
A JSON object specifying the session persistence for the pool or ``null``
for no session persistence. See :ref:`session_persistence`. Default is
``null``.
in: body
required: false
type: object
session_persistence_cookie:
description: |
The name of the cookie to use for session persistence. Only applicable to
the ``APP_COOKIE`` session persistence type.
in: body
required: false
type: string
session_persistence_type:
description: |
Session persistence type for the pool. One of ``APP_COOKIE``,
``HTTP_COOKIE``, ``SOURCE_IP``.
in: body
required: true
type: string
sni_container_refs:
description: |
A list of URIs to the `key manager service
@ -433,12 +519,6 @@ statuses:
in: body
required: true
type: object
tenant_id:
description: |
The ID of the project that owns the resource. (deprecated)
in: body
required: false
type: string
total_connections:
description: |
The total connections handled.

1
api-ref/source/v2/examples/listener-create-response.json
View File

@ -2,7 +2,6 @@
"listener": {
"description": "A great TLS listener",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"protocol": "TERMINATED_HTTPS",
"protocol_port": 443,

1
api-ref/source/v2/examples/listener-show-response.json
View File

@ -2,7 +2,6 @@
"listener": {
"description": "A great TLS listener",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"protocol": "TERMINATED_HTTPS",
"protocol_port": 443,

1
api-ref/source/v2/examples/listener-update-response.json
View File

@ -2,7 +2,6 @@
"listener": {
"description": "An updated great TLS listener",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"protocol": "TERMINATED_HTTPS",
"protocol_port": 443,

1
api-ref/source/v2/examples/listeners-list-response.json
View File

@ -3,7 +3,6 @@
{
"description": "A great TLS listener",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"protocol": "TERMINATED_HTTPS",
"protocol_port": 443,

1
api-ref/source/v2/examples/loadbalancer-create-response.json
View File

@ -2,7 +2,6 @@
"loadbalancer": {
"description": "My favorite load balancer",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"provisioning_status": "PENDING_CREATE",
"flavor": "",

9
api-ref/source/v2/examples/loadbalancer-full-create-response.json
View File

@ -2,7 +2,6 @@
"loadbalancer": {
"description": "My favorite load balancer",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"provisioning_status": "ACTIVE",
"flavor": "",
@ -17,7 +16,6 @@
"default_pool": {
"id": "c8cec227-410a-4a5b-af13-ecf38c2b0abb"
},
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"default_tls_container_id": null,
"connection_limit": -1,
@ -33,9 +31,8 @@
"default_tls_container_ref": null,
"admin_state_up": true,
"default_pool": {
"id": "b0577aff-c1f9-40c6-9a3b-7b1d2a669136",
"id": "b0577aff-c1f9-40c6-9a3b-7b1d2a669136"
},
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"default_tls_container_id": null,
"connection_limit": -1,
@ -50,7 +47,6 @@
"description": "",
"admin_state_up": true,
"rules": [],
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"listener_id": "95de30ec-67f4-437b-b3f3-22c5d9ef9828",
"redirect_url": "https://www.example.com/",
@ -65,7 +61,6 @@
"default_tls_container_ref": null,
"admin_state_up": true,
"default_pool": null,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"default_tls_container_id": null,
"connection_limit": -1,
@ -91,7 +86,6 @@
"healthmonitor": {
"name": "",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"delay": 3,
"expected_codes": "200,201,202",
@ -109,7 +103,6 @@
"weight": 1,
"admin_state_up": true,
"subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"address": "192.0.2.16",
"protocol_port": 80,

1
api-ref/source/v2/examples/loadbalancer-show-response.json
View File

@ -2,7 +2,6 @@
"loadbalancer": {
"description": "My favorite load balancer",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"provisioning_status": "PENDING_CREATE",
"flavor": "",

1
api-ref/source/v2/examples/loadbalancer-update-response.json
View File

@ -2,7 +2,6 @@
"loadbalancer": {
"description": "Temporarily disabled load balancer",
"admin_state_up": false,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"provisioning_status": "PENDING_UPDATE",
"flavor": "",

1
api-ref/source/v2/examples/loadbalancers-list-response.json
View File

@ -3,7 +3,6 @@
{
"description": "My favorite load balancer",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"provisioning_status": "ACTIVE",
"flavor": "a7ae5d5a-d855-4f9a-b187-af66b53f4d04",

1
api-ref/source/v2/examples/pool-create-curl Normal file
View File

@ -0,0 +1 @@
curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"pool":{"lb_algorithm":"ROUND_ROBIN","protocol":"HTTP","description":"Super Round Robin Pool","admin_state_up":true,"session_persistence":{"cookie_name":"ChocolateChip","type":"APP_COOKIE"},"listener_id":"023f2e34-7806-443b-bfae-16c324569a3d","name":"super-pool"}}' http://198.51.100.10:9876/v2.0/lbaas/pools

14
api-ref/source/v2/examples/pool-create-request.json Normal file
View File

@ -0,0 +1,14 @@
{
"pool": {
"lb_algorithm": "ROUND_ROBIN",
"protocol": "HTTP",
"description": "Super Round Robin Pool",
"admin_state_up": true,
"session_persistence": {
"cookie_name": "ChocolateChip",
"type": "APP_COOKIE"
},
"listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
"name": "super-pool"
}
}

31
api-ref/source/v2/examples/pool-create-response.json Normal file
View File

@ -0,0 +1,31 @@
{
"pool": {
"lb_algorithm": "ROUND_ROBIN",
"protocol": "HTTP",
"description": "Super Round Robin Pool",
"admin_state_up": true,
"loadbalancers": [
{
"id": "607226db-27ef-4d41-ae89-f2a800e9c2db"
}
],
"created_at": "2017-05-10T18:14:44",
"provisioning_status": "ACTIVE",
"updated_at": "2017-05-10T23:08:12",
"session_persistence": {
"cookie_name": "ChocolateChip",
"type": "APP_COOKIE"
},
"listeners": [
{
"id": "023f2e34-7806-443b-bfae-16c324569a3d"
}
],
"members": [],
"healthmonitor_id": null,
"project_id": "e3cd678b11784734bc366148aa37580e",
"id": "4029d267-3983-4224-a3d0-afb3fe16a2cd",
"operating_status": "ONLINE",
"name": "super-pool"
}
}

1
api-ref/source/v2/examples/pool-delete-curl Normal file
View File

@ -0,0 +1 @@
curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd

1
api-ref/source/v2/examples/pool-session-persistence-obj.json Normal file
View File

@ -0,0 +1 @@
{"cookie_name": "my_app_cookie", "type": "APP_COOKIE"}

1
api-ref/source/v2/examples/pool-show-curl Normal file
View File

@ -0,0 +1 @@
curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/pools/24a43e68-36de-45f6-89cf-c03df583131d

31
api-ref/source/v2/examples/pool-show-response.json Normal file
View File

@ -0,0 +1,31 @@
{
"pool": {
"lb_algorithm": "ROUND_ROBIN",
"protocol": "HTTP",
"description": "Super Round Robin Pool",
"admin_state_up": true,
"loadbalancers": [
{
"id": "607226db-27ef-4d41-ae89-f2a800e9c2db"
}
],
"created_at": "2017-05-10T18:14:44",
"provisioning_status": "ACTIVE",
"updated_at": "2017-05-10T23:08:12",
"session_persistence": {
"cookie_name": "ChocolateChip",
"type": "APP_COOKIE"
},
"listeners": [
{
"id": "023f2e34-7806-443b-bfae-16c324569a3d"
}
],
"members": [],
"healthmonitor_id": null,
"project_id": "e3cd678b11784734bc366148aa37580e",
"id": "4029d267-3983-4224-a3d0-afb3fe16a2cd",
"operating_status": "ONLINE",
"name": "super-pool"
}
}

1
api-ref/source/v2/examples/pool-update-curl Normal file
View File

@ -0,0 +1 @@
curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"pool":{"lb_algorithm":"LEAST_CONNECTIONS","session_persistence":{"type":"SOURCE_IP"},"description":"second description","name":"second_name"}}' http://198.51.100.10:9876/v2.0/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd

10
api-ref/source/v2/examples/pool-update-request.json Normal file
View File

@ -0,0 +1,10 @@
{
"pool": {
"lb_algorithm": "LEAST_CONNECTIONS",
"session_persistence": {
"type": "SOURCE_IP"
},
"description": "Super Least Connections Pool",
"name": "super-least-conn-pool"
}
}

31
api-ref/source/v2/examples/pool-update-response.json Normal file
View File

@ -0,0 +1,31 @@
{
"pool": {
"lb_algorithm": "LEAST_CONNECTIONS",
"protocol": "HTTP",
"description": "Super Least Connections Pool",
"admin_state_up": true,
"loadbalancers": [
{
"id": "607226db-27ef-4d41-ae89-f2a800e9c2db"
}
],
"created_at": "2017-05-10T18:14:44",
"provisioning_status": "ACTIVE",
"updated_at": "2017-05-10T23:08:12",
"session_persistence": {
"cookie_name": null,
"type": "SOURCE_IP"
},
"listeners": [
{
"id": "023f2e34-7806-443b-bfae-16c324569a3d"
}
],
"members": [],
"healthmonitor_id": null,
"project_id": "e3cd678b11784734bc366148aa37580e",
"id": "4029d267-3983-4224-a3d0-afb3fe16a2cd",
"operating_status": "ONLINE",
"name": "super-least-conn-pool"
}
}

1
api-ref/source/v2/examples/pools-list-curl Normal file
View File

@ -0,0 +1 @@
curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/pools?project_id=e3cd678b11784734bc366148aa37580e

38
api-ref/source/v2/examples/pools-list-response.json Normal file
View File

@ -0,0 +1,38 @@
{
"pools": [
{
"lb_algorithm": "ROUND_ROBIN",
"protocol": "HTTP",
"description": "My round robin pool",
"admin_state_up": true,
"loadbalancers": [
{
"id": "607226db-27ef-4d41-ae89-f2a800e9c2db"
}
],
"created_at": "2017-04-13T18:14:44",
"provisioning_status": "ACTIVE",
"updated_at": "2017-04-13T23:08:12",
"session_persistence": {
"cookie_name": null,
"type": "SOURCE_IP"
},
"listeners": [
{
"id": "023f2e34-7806-443b-bfae-16c324569a3d"
}
],
"members": [
{
"id": "5bc73753-348f-4b5a-8f9c-10bd7b30dc35",
"id": "692e8358-f8fd-4b92-bbca-6e4b97c75571"
}
],
"healthmonitor_id": null,
"project_id": "e3cd678b11784734bc366148aa37580e",
"id": "ddb2b28f-89e9-45d3-a329-a359c3e39e4a",
"operating_status": "ONLINE",
"name": "round_robin_pool"
}
]
}

32
api-ref/source/v2/general.inc
View File

@ -44,7 +44,7 @@ the full API call for ``/v2.0/lbaas/loadbalancers`` is
``http://198.51.100.10:9876/v2.0/lbaas/loadbalancers``.
Depending on the deployment, the ``load-balancer`` ``endpoint URL`` might be
http or https, a custom port, a custom path, and include your tenant id. The
http or https, a custom port, a custom path, and include your project id. The
only way to know the URLs for your deployment is by using the service catalog.
The ``load-balancer`` ``endpoint URL`` should never be hard coded in
applications, even if they are only expected to work at a single site. It
@ -87,9 +87,6 @@ header. You obtain the token by authenticating to the Keystone endpoint.
When Keystone is enabled, the ``project_id`` attribute is not required in create
requests because the project ID is derived from the authentication token.
NOTE: Currently the Octavia API accepts the deprecated ``tenant_id``
attribute for the project ID for backward compatibility.
The default authorization settings allow only administrative users to create
resources on behalf of a different project.
@ -118,18 +115,6 @@ Request format
The Octavia API v2.0 only accepts requests with the JSON data serialization
format. The ``Content-Type`` header is ignored.
Tenant and project attributes in requests
-----------------------------------------
Starting with the Newton release of the Octavia service, the Octavia API
accepts the ``project_id`` attribute in addition to the ``tenant_id`` attribute
in requests. The ``tenant_id`` attribute is accepted for backward compatibility.
If both the ``project_id`` and the ``tenant_id`` attribute are provided in the
same request, ``project_id`` will be used.
The ``tenant_id`` attribute is deprecated and will be removed in a future
release.
Response format
---------------
@ -144,18 +129,6 @@ Query extension
- **GET** *publicURL*/loadbalancers.json
Tenant and project attributes in responses
------------------------------------------
Starting with the Newton release of the Octavia service, the Octavia API
returns a ``project_id`` attribute in responses, while still returning a
``tenant_id`` attribute for backward compatibility. The values will always be
identical.
The ``tenant_id`` attribute is deprecated and will be removed in a future
release.
.. _filtering:
Filtering and column selection
@ -288,7 +261,6 @@ behavior regardless of the particular plug-in running in the background.
"provisioning_status": "ACTIVE",
"vip_port_id": "1e20d91d-8df9-4c15-9778-28bc89226c19",
"vip_address": "203.0.113.10",
"tenant_id": "bf325b04-e7b1-4002-9b10-f4984630367f",
"project_id": "bf325b04-e7b1-4002-9b10-f4984630367f"
},
{
@ -304,7 +276,6 @@ behavior regardless of the particular plug-in running in the background.
"provisioning_status": "ACTIVE",
"vip_port_id": "21f7ac04-6824-4222-93cf-46e0d70607f9",
"vip_address": "203.0.113.20",
"tenant_id": "bf325b04-e7b1-4002-9b10-f4984630367f",
"project_id": "bf325b04-e7b1-4002-9b10-f4984630367f"
}
],
@ -353,7 +324,6 @@ The last page won't show the "next" links
"provisioning_status": "ACTIVE",
"vip_port_id": "f777a1c7-7f59-4a36-ad34-24dfebaf19e6",
"vip_address": "203.0.113.50",
"tenant_id": "bf325b04-e7b1-4002-9b10-f4984630367f",
"project_id": "bf325b04-e7b1-4002-9b10-f4984630367f"
}
],

5
api-ref/source/v2/index.rst
View File

@ -20,3 +20,8 @@ Load Balancers
Listeners
---------
.. include:: listener.inc
-----
Pools
-----
.. include:: pool.inc

62
api-ref/source/v2/listener.inc
View File

@ -33,7 +33,6 @@ Request
- fields: fields
- project_id: project_id_query
- tenant_id: tenant_id_query
Curl Example
------------
@ -64,7 +63,6 @@ Response Parameters
- protocol_port: protocol_port
- provisioning_status: provisioning_status
- sni_container_refs: sni_container_refs
- tenant_id: tenant_id
Response Example
----------------
@ -103,7 +101,7 @@ data that is not valid, the service returns the HTTP ``Bad Request
response body. Validation errors require that you correct the error
and submit the request again.
Specifying a project_id or tenant_id is deprecated. The listener will inherit
Specifying a project_id is deprecated. The listener will inherit
the project_id of the parent load balancer.
You can configure all documented features of the listener at creation time by
@ -125,35 +123,6 @@ provisioning status.
- 500
- 503
.. _header_insertions:
Supported HTTP Header Insertions
--------------------------------
HTTP header insertion allows you to insert additional HTTP headers as the
requests are passed to the backend members. This allows you to expose
information that would have otherwise not be visible to the backend members.
The default is to not insert these headers.
.. note::
Both the key and the values are always specified as strings when specifying
header insertions.
HTTP Header Insertion Object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. rest_parameters:: ../parameters.yaml
- X-Forwarded-For: x_forwarded_for
- X-Forwarded-Port: x_forwarded_port
HTTP Header Insertion Object Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. literalinclude:: examples/http-header-insertion-obj.json
:language: javascript
Request
-------
@ -174,7 +143,31 @@ Request
- protocol: protocol
- protocol_port: protocol_port
- sni_container_refs: sni_container_refs-optional
- tenant_id: tenant_id
.. _header_insertions:
Supported HTTP Header Insertions
--------------------------------
.. note::
Both the key and the values are always specified as strings when specifying
header insertions.
+------------------+---------+------------------------------------------------+
| Key | Value | Description |
+==================+=========+================================================+
| X-Forwarded-For | boolean | When ``true`` a ``X-Forwarded-For`` header is |
| | | inserted into the request to the backend |
| | | ``member`` that specifies the client IP |
| | | address. |
+------------------+---------+------------------------------------------------+
| X-Forwarded-Port | integer | A ``X-Forwarded-Port`` header is inserted into |
| | | the request to the backend ``member`` that |
| | | specifies the integer provided. Typically this |
| | | is used to indicate the port the client |
| | | connected to on the load balancer. |
+------------------+---------+------------------------------------------------+
Request Example
----------------
@ -211,7 +204,6 @@ Response Parameters
- protocol_port: protocol_port
- provisioning_status: provisioning_status
- sni_container_refs: sni_container_refs
- tenant_id: tenant_id
Response Example
----------------
@ -279,7 +271,6 @@ Response Parameters
- protocol_port: protocol_port
- provisioning_status: provisioning_status
- sni_container_refs: sni_container_refs
- tenant_id: tenant_id
Response Example
----------------
@ -365,7 +356,6 @@ Response Parameters
- protocol_port: protocol_port
- provisioning_status: provisioning_status
- sni_container_refs: sni_container_refs
- tenant_id: tenant_id
Response Example
----------------

6
api-ref/source/v2/loadbalancer.inc
View File

@ -33,7 +33,6 @@ Request
- fields: fields
- project_id: project_id_query
- tenant_id: tenant_id_query
Curl Example
------------
@ -59,7 +58,6 @@ Response Parameters
- project_id: project_id
- provider: provider
- provisioning_status: provisioning_status
- tenant_id: tenant_id
- vip_address: vip_address
- vip_network_id: vip_network_id
- vip_port_id: vip_port_id
@ -151,7 +149,6 @@ Request
- name: name-optional
- project_id: project_id-optional
- provider: provider-optional
- tenant_id: tenant_id
- vip_address: vip_address-optional
- vip_network_id: vip_network_id-optional
- vip_port_id: vip_port_id-optional
@ -187,7 +184,6 @@ Response Parameters
- project_id: project_id
- provider: provider
- provisioning_status: provisioning_status
- tenant_id: tenant_id
- vip_address: vip_address
- vip_network_id: vip_network_id
- vip_port_id: vip_port_id
@ -277,7 +273,6 @@ Response Parameters
- project_id: project_id
- provider: provider
- provisioning_status: provisioning_status
- tenant_id: tenant_id
- vip_address: vip_address
- vip_network_id: vip_network_id
- vip_port_id: vip_port_id
@ -359,7 +354,6 @@ Response Parameters
- project_id: project_id
- provider: provider
- provisioning_status: provisioning_status
- tenant_id: tenant_id
- vip_address: vip_address
- vip_network_id: vip_network_id
- vip_port_id: vip_port_id

431
api-ref/source/v2/pool.inc Normal file
View File

@ -0,0 +1,431 @@
.. -*- rst -*-
List pools
==========
.. rest_method:: GET /v2.0/lbaas/pools
Lists all pools for the project.
Use the ``fields`` query parameter to control which fields are
returned in the response body. Additionally, you can filter results
by using query string parameters. For information, see :ref:`filtering`.
Administrative users can specify a project ID that is different than their own
to list pools for other projects.
The list might be empty.
.. rest_status_code:: success ../http-status.yaml
- 200
.. rest_status_code:: error ../http-status.yaml
- 400
- 401
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- fields: fields
- project_id: project_id_query
Curl Example
------------
.. literalinclude:: examples/pools-list-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up
- created_at: created_at
- description: description
- healthmonitor_id: healthmonitor-id
- id: pool-id
- lb_algorithm: lb-algorithm
- listeners: listener-ids
- loadbalancers: loadbalancer-ids
- members: member-ids
- name: name
- operating_status: operating_status
- project_id: project_id
- protocol: protocol-pools
- provisioning_status: provisioning_status
- session_persistence: session_persistence
Response Example
----------------
.. literalinclude:: examples/pools-list-response.json
:language: javascript
Create Pool
===========
.. rest_method:: POST /v2.0/lbaas/pools
Creates a pool for a load balancer.
The pool defines how requests should be balanced across the backend
member servers.
This operation provisions a pool by using the configuration that
you define in the request object. After the API validates the
request and starts the provisioning process, the API returns a
response object, which contains a unique ID.
In the response, the pool :ref:`provisioning status<prov_status>` is
``ACTIVE``, ``PENDING_CREATE``, or ``ERROR``.
If the status is ``PENDING_CREATE``, issue GET
``/v2.0/lbaas/pools/{pool_id}`` to view the progress of
the provisioning operation. When the pool status changes
to ``ACTIVE``, the pool is successfully provisioned and
is ready for further configuration.
At a minimum, you must specify these pool attributes:
- ``protocol`` The protocol for which this pool and its members
listen. A valid value is ``HTTP``, ``HTTPS``, ``PROXY``, or ``TCP``.
- ``lb_algorithm`` The load-balancer algorithm, such as
``ROUND_ROBIN``, ``LEAST_CONNECTIONS``, and ``SOURCE_IP``, that
distributes traffic to the pool members. The load-balancer
provider must support this algorithm.
- ``listener_id`` The ID of the listener in which this pool
becomes the default pool. Each listener has only one default
pool.
---OR---
- ``loadbalancer_id`` The ID of the load balancer under which this
pool will be created. Each load balancer can have zero or more pools
associated with it. These pools can be used for L7policies.
.. note::
Either ``listener_id`` or ``loadbalancer_id`` must be specified.
Some attributes receive default values if you omit them from the
request:
- ``admin_state_up`` Default is ``true``.
- ``name`` Default is an empty string.
- ``description`` Default is an empty string.
If the API cannot fulfill the request due to insufficient data or
data that is not valid, the service returns the HTTP ``Bad Request
(400)`` response code with information about the failure in the
response body. Validation errors require that you correct the error
and submit the request again.
Specifying a project_id is deprecated. The pool will inherit the
project_id of the parent load balancer.
You can configure all documented features of the pool at creation time by
specifying the additional elements or attributes in the request.
To create a pool, the parent load balancer must have an ``ACTIVE``
provisioning status.
.. rest_status_code:: success ../http-status.yaml
- 201
.. rest_status_code:: error ../http-status.yaml
- 400
- 401
- 403
- 404
- 500
- 503
Request
-------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up-default-optional
- description: description-optional
- lb_algorithm: lb-algorithm
- listener_id: listener-id-pool-optional
- loadbalancer_id: loadbalancer-id-pool-optional
- name: name-optional
- project_id: project_id-optional-deprecated
- protocol: protocol-pools
- session_persistence: session_persistence-optional
.. _session_persistence:
Pool Session Persistence
------------------------
Pool session persistence tells the load balancer to attempt to send future
requests from a client to the same backend member as the initial request.
When the pool has no session persistence, the session persistence object is
``null``.
Octavia currently support three session persistence methods:
+-----------------+----------------------------------------------------------+
| Method | Description |
+=================+==========================================================+
| ``APP_COOKIE`` | Use the specified ``cookie_name`` send future requests |
| | to the same member. |
+-----------------+----------------------------------------------------------+
| ``HTTP_COOKIE`` | The load balancer will generate a cookie that is |
| | inserted into the response. This cookie will be used to |
| | send future requests to the same member. |
+-----------------+----------------------------------------------------------+
| ``SOURCE_IP`` | The source IP address on the request will be hashed to |
| | send future requests to the same member. |
+-----------------+----------------------------------------------------------+
Pool Session Persistence Object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. rest_parameters:: ../parameters.yaml
- type: session_persistence_type
- cookie_name: session_persistence_cookie
Pool Session Persistence Object Example
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. literalinclude:: examples/pool-session-persistence-obj.json
:language: javascript
Request Example
----------------
.. literalinclude:: examples/pool-create-request.json
:language: javascript
Curl Example
------------
.. literalinclude:: examples/pool-create-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up
- created_at: created_at
- description: description
- healthmonitor_id: healthmonitor-id
- id: pool-id
- lb_algorithm: lb-algorithm
- listeners: listener-ids
- loadbalancers: loadbalancer-ids
- members: member-ids
- name: name
- operating_status: operating_status
- project_id: project_id
- protocol: protocol-pools
- provisioning_status: provisioning_status
- session_persistence: session_persistence
Response Example
----------------
.. literalinclude:: examples/pool-create-response.json
:language: javascript
Show Pool details
=================
.. rest_method:: GET /v2.0/lbaas/pools/{pool_id}
Shows the details of a pool.
If you are not an administrative user and the parent load balancer does not
belong to your project, the service returns the HTTP ``Forbidden (403)``
response code.
This operation does not require a request body.
.. rest_status_code:: success ../http-status.yaml
- 200
.. rest_status_code:: error ../http-status.yaml
- 401
- 403
- 404
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- pool_id: path-pool-id
Curl Example
------------
.. literalinclude:: examples/pool-show-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up
- created_at: created_at
- description: description
- healthmonitor_id: healthmonitor-id
- id: pool-id
- lb_algorithm: lb-algorithm
- listeners: listener-ids
- loadbalancers: loadbalancer-ids
- members: member-ids
- name: name
- operating_status: operating_status
- project_id: project_id
- protocol: protocol-pools
- provisioning_status: provisioning_status
- session_persistence: session_persistence
Response Example
----------------
.. literalinclude:: examples/pool-show-response.json
:language: javascript
Update a pool
=============
.. rest_method:: PUT /v2.0/lbaas/pools/{pool_id}
Update an existing pool.
If the request is valid, the service returns the ``Accepted (202)``
response code. To confirm the update, check that the pool provisioning
status is ``ACTIVE``. If the status is ``PENDING_UPDATE``, use a GET
operation to poll the pool object for changes.
This operation returns the updated pool object with the
``ACTIVE``, ``PENDING_UPDATE``, or ``ERROR`` provisioning status.
.. rest_status_code:: success ../http-status.yaml
- 202
.. rest_status_code:: error ../http-status.yaml
- 400
- 401
- 403
- 404
- 409
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up-default-optional
- description: description-optional
- lb_algorithm: lb-algorithm-optional
- name: name-optional
- pool_id: path-pool-id
- session_persistence: session_persistence-optional
Request Example
---------------
.. literalinclude:: examples/pool-update-request.json
:language: javascript
Curl Example
------------
.. literalinclude:: examples/pool-update-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up
- created_at: created_at
- description: description
- healthmonitor_id: healthmonitor-id
- id: pool-id
- lb_algorithm: lb-algorithm
- listeners: listener-ids
- loadbalancers: loadbalancer-ids
- members: member-ids
- name: name
- operating_status: operating_status
- project_id: project_id
- protocol: protocol-pools
- provisioning_status: provisioning_status
- session_persistence: session_persistence
Response Example
----------------
.. literalinclude:: examples/pool-update-response.json
:language: javascript
Remove a pool
=============
.. rest_method:: DELETE /v2.0/lbaas/pools/{pool_id}
Removes a pool and its associated configuration from the load balancer.
The API immediately purges any and all configuration data, depending on the
configuration settings. You cannot recover it.
.. rest_status_code:: success ../http-status.yaml
- 204
.. rest_status_code:: error ../http-status.yaml
- 400
- 401
- 403
- 404
- 409
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- pool_id: path-pool-id
Curl Example
------------
.. literalinclude:: examples/pool-delete-curl
:language: bash
Response
--------
There is no body content for the response of a successful DELETE request.