Add v2 pool API section

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

Change-Id: I70e5cb07a4435f58f5da3999be70162efa7f0bd8
Partial-Bug: #1558385

api-ref/source/parameters.yaml

@@ -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.

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

@@ -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,

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

@@ -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,

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

@@ -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,

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

@@ -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,

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

@@ -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": "",

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

@@ -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,

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

@@ -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": "",

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

@@ -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": "",

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

@@ -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",

api-ref/source/v2/examples/pool-create-curl

@@ -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

api-ref/source/v2/examples/pool-create-request.json

@@ -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"
+    }
+}

api-ref/source/v2/examples/pool-create-response.json

@@ -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"
+    }
+}

api-ref/source/v2/examples/pool-delete-curl

@@ -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

api-ref/source/v2/examples/pool-session-persistence-obj.json

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

api-ref/source/v2/examples/pool-show-curl

@@ -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

api-ref/source/v2/examples/pool-show-response.json

@@ -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"
+    }
+}

api-ref/source/v2/examples/pool-update-curl

@@ -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

api-ref/source/v2/examples/pool-update-request.json

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

api-ref/source/v2/examples/pool-update-response.json

@@ -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"
+    }
+}

api-ref/source/v2/examples/pools-list-curl

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

api-ref/source/v2/examples/pools-list-response.json

@@ -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"
+        }
+    ]
+}

api-ref/source/v2/general.inc

@@ -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"
             }
         ],

api-ref/source/v2/index.rst

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

api-ref/source/v2/listener.inc

@@ -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
 ----------------

api-ref/source/v2/loadbalancer.inc

@@ -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

api-ref/source/v2/pool.inc

@@ -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.