Add v2 member API section

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

Change-Id: I5e10a215d685c27a7e5be882a2598fe7cb3875ee
Partial-Bug: #1558385

api-ref/source/parameters.yaml

@@ -19,6 +19,12 @@ path-loadbalancer-id:
   in: path
   required: true
   type: string
+path-member-id:
+  description: |
+    The ID of the member to query.
+  in: path
+  required: true
+  type: string
 path-pool-id:
   description: |
     The ID of the pool to query.
@@ -68,6 +74,12 @@ address:
   in: body
   required: true
   type: string
+address-member:
+  description: |
+    The IP address of the backend member server.
+  in: body
+  required: true
+  type: string
 admin_state_up:
   description: |
     The administrative state of the resource, which is
@@ -344,6 +356,12 @@ loadbalancers:
   in: body
   required: true
   type: array
+member-id:
+  description: |
+    The ID of the member.
+  in: body
+  required: true
+  type: string
 member-ids:
   description: |
     A list of member IDs.
@@ -356,6 +374,34 @@ members-status-object-list:
   in: body
   required: true
   type: array
+monitor_address:
+  description: |
+    An alternate IP address used for health monitoring a backend member.
+    Default is ``null`` which monitors the member ``address``.
+  in: body
+  required: true
+  type: string
+monitor_address-optional:
+  description: |
+    An alternate IP address used for health monitoring a backend member.
+    Default is ``null`` which monitors the member ``address``.
+  in: body
+  required: false
+  type: string
+monitor_port:
+  description: |
+    An alternate protocol port used for health monitoring a backend member.
+    Default is ``null`` which monitors the member ``protocol_port``.
+  in: body
+  required: true
+  type: integer
+monitor_port-optional:
+  description: |
+    An alternate protocol port used for health monitoring a backend member.
+    Default is ``null`` which monitors the member ``protocol_port``.
+  in: body
+  required: false
+  type: integer
 name:
   description: |
     Human-readable name of the resource.
@@ -434,6 +480,12 @@ protocol_port:
   in: body
   required: true
   type: integer
+protocol_port-member:
+  description: |
+    The protocol port number the backend member server is listening on.
+  in: body
+  required: true
+  type: integer
 provider:
   description: |
     Provider name for the load balancer.
@@ -519,6 +571,18 @@ statuses:
   in: body
   required: true
   type: object
+subnet_id:
+  description: |
+    The subnet ID the member service is accessible from.
+  in: body
+  required: true
+  type: string
+subnet_id-optional:
+  description: |
+    The subnet ID the member service is accessible from.
+  in: body
+  required: false
+  type: string
 total_connections:
   description: |
     The total connections handled.
@@ -588,6 +652,28 @@ vip_subnet_id-optional:
   in: body
   required: false
   type: string
+weight:
+  description: |
+    The weight of a member determines the portion of requests or connections it
+    services compared to the other members of the pool. For example, a member
+    with a weight of 10 receives five times as many requests as a member with a
+    weight of 2. A value of 0 means the member does not receive new connections
+    but continues to service existing connections. A valid value is
+    from ``0`` to ``256``. Default is ``1``.
+  in: body
+  required: true
+  type: integer
+weight-optional:
+  description: |
+    The weight of a member determines the portion of requests or connections it
+    services compared to the other members of the pool. For example, a member
+    with a weight of 10 receives five times as many requests as a member with a
+    weight of 2. A value of 0 means the member does not receive new connections
+    but continues to service existing connections. A valid value is
+    from ``0`` to ``256``. Default is ``1``.
+  in: body
+  required: false
+  type: integer
 x_forwarded_for:
   description: |
     When ``true`` a ``X-Forwarded-For`` header is inserted into the request

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

@@ -80,7 +80,6 @@
                 "protocol": "HTTP",
                 "description": "",
                 "admin_state_up": true,
-                "tenant_id": "e3cd678b11784734bc366148aa37580e",
                 "project_id": "e3cd678b11784734bc366148aa37580e",
                 "session_persistence": null,
                 "healthmonitor": {
@@ -113,7 +112,6 @@
                         "weight": 1,
                         "admin_state_up": true,
                         "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
-                        "tenant_id": "e3cd678b11784734bc366148aa37580e",
                         "project_id": "e3cd678b11784734bc366148aa37580e",
                         "address": "192.0.2.19",
                         "protocol_port": 80,
@@ -128,13 +126,11 @@
                 "protocol": "HTTPS",
                 "description": "",
                 "admin_state_up": true,
-                "tenant_id": "e3cd678b11784734bc366148aa37580e",
                 "project_id": "e3cd678b11784734bc366148aa37580e",
                 "session_persistence": null,
                 "healthmonitor": {
                     "name": "",
                     "admin_state_up": true,
-                    "tenant_id": "e3cd678b11784734bc366148aa37580e",
                     "project_id": "e3cd678b11784734bc366148aa37580e",
                     "delay": 3,
                     "expected_codes": "200,201,202",
@@ -152,7 +148,6 @@
                         "weight": 1,
                         "admin_state_up": true,
                         "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
-                        "tenant_id": "e3cd678b11784734bc366148aa37580e",
                         "project_id": "e3cd678b11784734bc366148aa37580e",
                         "address": "192.0.2.51",
                         "protocol_port": 80,
@@ -163,7 +158,6 @@
                         "weight": 1,
                         "admin_state_up": true,
                         "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
-                        "tenant_id": "e3cd678b11784734bc366148aa37580e",
                         "project_id": "e3cd678b11784734bc366148aa37580e",
                         "address": "192.0.2.52",
                         "protocol_port": 80,

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

@@ -0,0 +1 @@
+curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"member":{"name":"web-server-1","weight":"20","admin_state_up":true,"subnet_id":"bbb35f84-35cc-4b2f-84c2-a6a29bba68aa","address":"192.0.2.16","protocol_port":"80","monitor_port":8080}}' http://198.51.100.10:9876/v2.0/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd/members

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

@@ -0,0 +1,11 @@
+{
+    "member": {
+        "name": "web-server-1",
+        "weight": "20",
+        "admin_state_up": true,
+        "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
+        "address": "192.0.2.16",
+        "protocol_port": "80",
+        "monitor_port": 8080
+    }
+}

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

@@ -0,0 +1,18 @@
+{
+    "member": {
+        "monitor_port": 8080,
+        "project_id": "e3cd678b11784734bc366148aa37580e",
+        "name": "web-server-1",
+        "weight": 20,
+        "admin_state_up": true,
+        "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
+        "created_at": "2017-05-11T17:21:34",
+        "provisioning_status": "ACTIVE",
+        "monitor_address": null,
+        "updated_at": "2017-05-11T17:21:37",
+        "address": "192.0.2.16",
+        "protocol_port": 80,
+        "id": "957a1ace-1bd2-449b-8455-820b6e4b63f3",
+        "operating_status": "NO_MONITOR"
+    }
+}

api-ref/source/v2/examples/member-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/members/957a1ace-1bd2-449b-8455-820b6e4b63f3

api-ref/source/v2/examples/member-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/members/957a1ace-1bd2-449b-8455-820b6e4b63f3

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

@@ -0,0 +1,18 @@
+{
+    "member": {
+        "monitor_port": 8080,
+        "project_id": "e3cd678b11784734bc366148aa37580e",
+        "name": "web-server-1",
+        "weight": 20,
+        "admin_state_up": true,
+        "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
+        "created_at": "2017-05-11T17:21:34",
+        "provisioning_status": "ACTIVE",
+        "monitor_address": null,
+        "updated_at": "2017-05-11T17:21:37",
+        "address": "192.0.2.16",
+        "protocol_port": 80,
+        "id": "957a1ace-1bd2-449b-8455-820b6e4b63f3",
+        "operating_status": "NO_MONITOR"
+    }
+}

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

@@ -0,0 +1 @@
+curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"member":{"name":"web-server-1-2","weight":"0","admin_state_up":"true","monitor_address":"192.0.2.40","monitor_port":8888}}' http://198.51.100.10:9876/v2.0/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd/members/957a1ace-1bd2-449b-8455-820b6e4b63f3

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

@@ -0,0 +1,9 @@
+{
+    "member": {
+        "name": "web-server-1-2",
+        "weight": "0",
+        "admin_state_up": "true",
+        "monitor_address": "192.0.2.40",
+        "monitor_port": 8888
+    }
+}

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

@@ -0,0 +1,18 @@
+{
+    "member": {
+        "monitor_port": 8080,
+        "project_id": "e3cd678b11784734bc366148aa37580e",
+        "name": "web-server-1",
+        "weight": 20,
+        "admin_state_up": true,
+        "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
+        "created_at": "2017-05-11T17:21:34",
+        "provisioning_status": "PENDING_UPDATE",
+        "monitor_address": null,
+        "updated_at": "2017-05-11T17:21:37",
+        "address": "192.0.2.16",
+        "protocol_port": 80,
+        "id": "957a1ace-1bd2-449b-8455-820b6e4b63f3",
+        "operating_status": "NO_MONITOR"
+    }
+}

api-ref/source/v2/examples/members-list-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/members?project_id=e3cd678b11784734bc366148aa37580e

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

@@ -0,0 +1,20 @@
+{
+    "members": [
+        {
+            "monitor_port": 8080,
+            "project_id": "e3cd678b11784734bc366148aa37580e",
+            "name": "web-server-1",
+            "weight": 20,
+            "admin_state_up": true,
+            "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
+            "created_at": "2017-05-11T17:21:34",
+            "provisioning_status": "ACTIVE",
+            "monitor_address": null,
+            "updated_at": "2017-05-11T17:21:37",
+            "address": "192.0.2.16",
+            "protocol_port": 80,
+            "id": "957a1ace-1bd2-449b-8455-820b6e4b63f3",
+            "operating_status": "NO_MONITOR"
+        }
+    ]
+}

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

@@ -10,7 +10,7 @@
             }
         ],
         "created_at": "2017-05-10T18:14:44",
-        "provisioning_status": "ACTIVE",
+        "provisioning_status": "PENDING_UPDATE",
         "updated_at": "2017-05-10T23:08:12",
         "session_persistence": {
             "cookie_name": null,

api-ref/source/v2/index.rst

@@ -25,3 +25,8 @@ Listeners
 Pools
 -----
 .. include:: pool.inc
+
+-------
+Members
+-------
+.. include:: member.inc

api-ref/source/v2/listener.inc

@@ -240,6 +240,7 @@ Request
 
 .. rest_parameters:: ../parameters.yaml
 
+   - fields: fields
    - listener_id: path-listener-id
 
 Curl Example

api-ref/source/v2/loadbalancer.inc

@@ -247,6 +247,7 @@ Request
 
 .. rest_parameters:: ../parameters.yaml
 
+   - fields: fields
    - loadbalancer_id: path-loadbalancer-id
 
 Curl Example

api-ref/source/v2/member.inc

@@ -0,0 +1,384 @@
+.. -*- rst -*-
+
+List members
+============
+
+.. rest_method:: GET /v2.0/lbaas/pools/{pool_id}/members
+
+Lists all members 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 members 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
+   - pool_id: path-pool-id
+   - project_id: project_id_query
+
+Curl Example
+------------
+
+.. literalinclude:: examples/members-list-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - address: address-member
+   - admin_state_up: admin_state_up
+   - created_at: created_at
+   - description: description
+   - id: member-id
+   - monitor_address: monitor_address
+   - monitor_port: monitor_port
+   - name: name
+   - operating_status: operating_status
+   - project_id: project_id
+   - protocol_port: protocol_port-member
+   - provisioning_status: provisioning_status
+   - subnet_id: subnet_id
+   - weight: weight
+
+Response Example
+----------------
+
+.. literalinclude:: examples/members-list-response.json
+   :language: javascript
+
+Create Member
+=============
+
+.. rest_method:: POST /v2.0/lbaas/pools/{pool_id}/members
+
+This operation provisions a member and adds it to a pool by using
+the configuration that you define in the request object. After the
+API validates the request and starts the provisioning process, it
+returns a response object, which contains a unique ID.
+
+In the response, the member :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}/members/{member_id}`` to view the progress of
+the provisioning operation. When the member status changes
+to ``ACTIVE``, the member is successfully provisioned and
+is ready for further configuration.
+
+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.
+
+At a minimum, you must specify these member attributes:
+
+- ``address``. The IP address of the backend member to receive traffic from
+  the load balancer.
+
+- ``protocol_port`` The port on which the backend member listens for
+  traffic.
+
+Some attributes receive default values if you omit them from the
+request:
+
+- ``admin_state_up``. Default is ``true``.
+
+- ``weight``. Default is ``1``.
+
+If you omit the ``subnet_id`` parameter, the ``vip_subnet_id`` for the parent
+load balancer will be used for the member subnet UUID.
+
+The member ``address`` does not necessarily need to be a member of the
+``subnet_id`` subnet.  Members can be routable from the subnet specified
+either via the default route or by using ``host_routes`` defined on the subnet.
+
+Administrative users can specify a project ID that is different than
+their own to create members for other projects.
+
+``monitor_address`` and/or ``monitor_port`` can be used to have the health
+monitor, if one is configured for the pool, connect to an alternate IP address
+and port when executing a health check on the member.
+
+To create a member, the 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
+   - address: address
+   - description: description-optional
+   - monitor_address: monitor_address-optional
+   - monitor_port: monitor_port-optional
+   - name: name-optional
+   - pool_id: path-pool-id
+   - project_id: project_id-optional-deprecated
+   - protocol_port: protocol_port
+   - subnet_id: subnet_id-optional
+   - weight: weight-optional
+
+Request Example
+----------------
+
+.. literalinclude:: examples/member-create-request.json
+   :language: javascript
+
+Curl Example
+------------
+
+.. literalinclude:: examples/member-create-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - address: address-member
+   - admin_state_up: admin_state_up
+   - created_at: created_at
+   - description: description
+   - id: member-id
+   - monitor_address: monitor_address
+   - monitor_port: monitor_port
+   - name: name
+   - operating_status: operating_status
+   - project_id: project_id
+   - protocol_port: protocol_port-member
+   - provisioning_status: provisioning_status
+   - subnet_id: subnet_id
+   - weight: weight
+
+Response Example
+----------------
+
+.. literalinclude:: examples/member-create-response.json
+   :language: javascript
+
+Show Member details
+===================
+
+.. rest_method:: GET /v2.0/lbaas/pools/{pool_id}/members/{member-id}
+
+Shows the details of a pool member.
+
+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
+
+   - fields: fields
+   - member_id: path-member-id
+   - pool_id: path-pool-id
+
+Curl Example
+------------
+
+.. literalinclude:: examples/member-show-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - address: address-member
+   - admin_state_up: admin_state_up
+   - created_at: created_at
+   - description: description
+   - id: member-id
+   - monitor_address: monitor_address
+   - monitor_port: monitor_port
+   - name: name
+   - operating_status: operating_status
+   - project_id: project_id
+   - protocol_port: protocol_port-member
+   - provisioning_status: provisioning_status
+   - subnet_id: subnet_id
+   - weight: weight
+
+Response Example
+----------------
+
+.. literalinclude:: examples/member-show-response.json
+   :language: javascript
+
+Update a member
+===============
+
+.. rest_method:: PUT /v2.0/lbaas/pools/{pool_id}/members/{member_id}
+
+Update an existing member.
+
+If the request is valid, the service returns the ``Accepted (202)``
+response code. To confirm the update, check that the member provisioning
+status is ``ACTIVE``. If the status is ``PENDING_UPDATE``, use a GET
+operation to poll the member object for changes.
+
+Setting the member weight to ``0`` means that the member will not receive
+new requests but will finish any existing connections.  This "drains" the
+backend member of active connections.
+
+This operation returns the updated member 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
+   - member_id: path-member-id
+   - monitor_address: monitor_address-optional
+   - monitor_port: monitor_port-optional
+   - name: name-optional
+   - pool_id: path-pool-id
+   - weight: weight-optional
+
+Request Example
+---------------
+
+.. literalinclude:: examples/member-update-request.json
+   :language: javascript
+
+Curl Example
+------------
+
+.. literalinclude:: examples/member-update-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - address: address-member
+   - admin_state_up: admin_state_up
+   - created_at: created_at
+   - description: description
+   - id: member-id
+   - monitor_address: monitor_address
+   - monitor_port: monitor_port
+   - name: name
+   - operating_status: operating_status
+   - project_id: project_id
+   - protocol_port: protocol_port-member
+   - provisioning_status: provisioning_status
+   - subnet_id: subnet_id
+   - weight: weight
+
+Response Example
+----------------
+
+.. literalinclude:: examples/member-update-response.json
+   :language: javascript
+
+Remove a member
+=================
+
+.. rest_method:: DELETE /v2.0/lbaas/pools/{pool_id}/members/{member_id}
+
+Removes a member and its associated configuration from the pool.
+
+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
+
+   - member_id: path-member-id
+   - pool_id: path-pool-id
+
+Curl Example
+------------
+
+.. literalinclude:: examples/member-delete-curl
+   :language: bash
+
+Response
+--------
+
+There is no body content for the response of a successful DELETE request.
+

api-ref/source/v2/pool.inc

@@ -275,6 +275,7 @@ Request
 
 .. rest_parameters:: ../parameters.yaml
 
+   - fields: fields
    - pool_id: path-pool-id
 
 Curl Example