openstack/octavia
Code Issues Proposed changes

Add v2 member API section

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

Change-Id: I5e10a215d685c27a7e5be882a2598fe7cb3875ee
Partial-Bug: #1558385
This commit is contained in:
johnsom 2017-05-11 10:42:17 -07:00 committed by Adam Harwell
parent b14147d337
commit 63b2b0e1ce
19 changed files with 578 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

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

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

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

11
api-ref/source/v2/examples/member-create-request.json Normal file
View File

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

18
api-ref/source/v2/examples/member-create-response.json Normal file
View File

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

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

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

18
api-ref/source/v2/examples/member-show-response.json Normal file
View File

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

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

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

9
api-ref/source/v2/examples/member-update-request.json Normal file
View File

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

18
api-ref/source/v2/examples/member-update-response.json Normal file
View File

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

1
api-ref/source/v2/examples/members-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/24a43e68-36de-45f6-89cf-c03df583131d/members?project_id=e3cd678b11784734bc366148aa37580e

20
api-ref/source/v2/examples/members-list-response.json Normal file
View File

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

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

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

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

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

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

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

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

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

384
api-ref/source/v2/member.inc Normal file
View File

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

1
api-ref/source/v2/pool.inc
View File

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