openstack/octavia
Code Issues Proposed changes

Add v2 listener API section

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

Change-Id: I09731856fedb3758f850208028974dfda080d08a
Partial-Bug: #1558385
This commit is contained in:
johnsom
2017-04-11 08:38:19 -07:00
parent 87bab9bf15
commit 6dd09d7c7c
19 changed files with 830 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,6 +1,12 @@
############################################################################### ###############################################################################
# Path fields # Path fields
############################################################################### ###############################################################################
path-listener-id:
description: |
The ID of the listener to query.
in: path
required: true
type: string
path-loadbalancer-id: path-loadbalancer-id:
description: | description: |
The ID of the load balancer to query. The ID of the load balancer to query.
@@ -112,12 +118,52 @@ bytes_out:
in: body in: body
required: true required: true
type: integer type: integer
connection_limit:
description: |
The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections.
in: body
required: true
type: integer
connection_limit-optional:
description: |
The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections.
in: body
required: false
type: integer
created_at: created_at:
description: | description: |
The UTC date and timestamp when the resource was created. The UTC date and timestamp when the resource was created.
in: body in: body
required: true required: true
type: string type: string
default_pool_id:
description: |
The ID of the pool used by the listener if no L7 policies match.
in: body
required: true
type: string
default_pool_id-optional:
description: |
The ID of the pool used by the listener if no L7 policies match.
in: body
required: false
type: string
default_tls_container_ref:
description: |
The URI to the `key manager service
<https://docs.openstack.org/developer/barbican/>`__ secrets container
containing the certificate and key for ``TERMINATED_TLS`` listeners.
in: body
required: true
type: string
default_tls_container_ref-optional:
description: |
The URI to the `key manager service
<https://docs.openstack.org/developer/barbican/>`__ secrets container
containing the certificate and key for ``TERMINATED_TLS`` listeners.
in: body
required: false
type: string
description: description:
description: | description: |
A human-readable description for the resource. A human-readable description for the resource.
@@ -154,18 +200,58 @@ id:
in: body in: body
required: true required: true
type: string type: string
insert_headers:
description: |
A dictionary of optional headers to insert into the request before it is
sent to the backend ``member``. See :ref:`header_insertions`. Both keys
and values are always specified as strings.
in: body
required: true
type: object
insert_headers-optional:
description: |
A dictionary of optional headers to insert into the request before it is
sent to the backend ``member``. See :ref:`header_insertions`. Both keys
and values are always specified as strings.
in: body
required: false
type: object
l7policies-optional:
description: |
A list of L7 policy objects.
in: body
required: true
type: array
l7policies-status-object-list: l7policies-status-object-list:
description: | description: |
A list of L7 policy status objects. A list of L7 policy status objects.
in: body in: body
required: true required: true
type: array type: array
l7policy-ids:
description: |
A list of L7 policy IDs.
in: body
required: true
type: array
l7rules-status-object-list: l7rules-status-object-list:
description: | description: |
A list of L7 rule status objects. A list of L7 rule status objects.
in: body in: body
required: true required: true
type: array type: array
listener:
description: |
A listener object.
in: body
required: true
type: object
listener-id:
description: |
The ID of the listener.
in: body
required: true
type: string
listeners: listeners:
description: | description: |
The associated listener IDs, if any. The associated listener IDs, if any.
@@ -196,6 +282,12 @@ loadbalancer-id:
in: body in: body
required: true required: true
type: string type: string
loadbalancer-ids:
description: |
A list of load balancer IDs.
in: body
required: true
type: array
loadbalancer-status: loadbalancer-status:
description: | description: |
A load balancer status object. A load balancer status object.
@@ -232,6 +324,12 @@ operating_status:
in: body in: body
required: true required: true
type: string type: string
pool-optional:
description: |
A pool object.
in: body
required: false
type: object
pools-status-list: pools-status-list:
description: | description: |
The list of pools status objects. The list of pools status objects.
@@ -256,6 +354,18 @@ project_id-optional:
in: body in: body
required: false required: false
type: string type: string
project_id-optional-deprecated:
description: |
The ID of the project owning this resource. (deprecated)
in: body
required: false
type: string
protocol:
description: |
The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``TCP``, or ``TERMINATED_HTTPS``.
in: body
required: true
type: integer
protocol_port: protocol_port:
description: | description: |
The protocol port number for the resource. The protocol port number for the resource.
@@ -286,6 +396,24 @@ request_errors:
in: body in: body
required: true required: true
type: integer type: integer
sni_container_refs:
description: |
A list of URIs to the `key manager service
<https://docs.openstack.org/developer/barbican/>`__ secrets containers
containing the certificates and keys for ``TERMINATED_TLS`` the listener
using Server Name Indication.
in: body
required: true
type: array
sni_container_refs-optional:
description: |
A list of URIs to the `key manager service
<https://docs.openstack.org/developer/barbican/>`__ secrets containers
containing the certificates and keys for ``TERMINATED_TLS`` the listener
using Server Name Indication.
in: body
required: false
type: array
stats: stats:
description: | description: |
A statistics object. A statistics object.
@@ -374,3 +502,19 @@ vip_subnet_id-optional:
in: body in: body
required: false required: false
type: string type: string
x_forwarded_for:
description: |
When ``true`` a ``X-Forwarded-For`` header is inserted into the request
to the backend ``member`` that specifies the client (source) IP address.
The default is ``false``.
in: body
required: false
type: boolean
x_forwarded_port:
description: |
When ``true`` a ``X-Forwarded-Port`` header is inserted into the request
to the backend ``member`` that specifies the listener port the request
was received on. The default is ``false``.
in: body
required: false
type: boolean

6
api-ref/source/v2/examples/http-header-insertion-obj.json Normal file
View File

@@ -0,0 +1,6 @@
{
"insert_headers": {
"X-Forwarded-For": "true",
"X-Forwarded-Port": "true"
}
}

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

@@ -0,0 +1 @@
curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"listener": {"protocol": "TERMINATED_HTTPS", "description": "A great TLS listener", "admin_state_up": true, "connection_limit": 200, "protocol_port": "443", "loadbalancer_id": "607226db-27ef-4d41-ae89-f2a800e9c2db", "name": "great_tls_listener", "insert_headers": {"X-Forwarded-For": "true", "X-Forwarded-Port": "true"}, "default_tls_container_ref": "http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51", "sni_container_refs": ["http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51", "http://198.51.100.10:9311/v1/containers/aaebb31e-7761-4826-8cb4-2b829caca3ee"]}}' http://198.51.100.10:9876/v2.0/lbaas/listeners

20
api-ref/source/v2/examples/listener-create-request.json Normal file
View File

@@ -0,0 +1,20 @@
{
"listener": {
"protocol": "TERMINATED_HTTPS",
"description": "A great TLS listener",
"admin_state_up": true,
"connection_limit": 200,
"protocol_port": "443",
"loadbalancer_id": "607226db-27ef-4d41-ae89-f2a800e9c2db",
"name": "great_tls_listener",
"insert_headers": {
"X-Forwarded-For": "true",
"X-Forwarded-Port": "true"
},
"default_tls_container_ref": "http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"sni_container_refs": [
"http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"http://198.51.100.10:9311/v1/containers/aaebb31e-7761-4826-8cb4-2b829caca3ee"
]
}
}

36
api-ref/source/v2/examples/listener-create-response.json Normal file
View File

@@ -0,0 +1,36 @@
{
"listener": {
"description": "A great TLS listener",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"protocol": "TERMINATED_HTTPS",
"protocol_port": 443,
"provisioning_status": "PENDING_CREATE",
"default_tls_container_ref": "http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"loadbalancers": [
{
"id": "607226db-27ef-4d41-ae89-f2a800e9c2db"
}
],
"insert_headers": {
"X-Forwarded-Port": "true",
"X-Forwarded-For": "true"
},
"created_at": "2017-02-28T00:42:44",
"updated_at": "2017-02-28T00:44:30",
"id": "023f2e34-7806-443b-bfae-16c324569a3d",
"operating_status": "OFFLINE",
"default_pool_id": "ddb2b28f-89e9-45d3-a329-a359c3e39e4a",
"sni_container_refs": [
"http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"http://198.51.100.10:9311/v1/containers/aaebb31e-7761-4826-8cb4-2b829caca3ee"
],
"l7policies": [
{
"id": "5e618272-339d-4a80-8d14-dbc093091bb1"
}
],
"name": "great_tls_listener"
}
}

1
api-ref/source/v2/examples/listener-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/listeners/023f2e34-7806-443b-bfae-16c324569a3d

1
api-ref/source/v2/examples/listener-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/listeners/023f2e34-7806-443b-bfae-16c324569a3d

36
api-ref/source/v2/examples/listener-show-response.json Normal file
View File

@@ -0,0 +1,36 @@
{
"listener": {
"description": "A great TLS listener",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"protocol": "TERMINATED_HTTPS",
"protocol_port": 443,
"provisioning_status": "ACTIVE",
"default_tls_container_ref": "http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"loadbalancers": [
{
"id": "607226db-27ef-4d41-ae89-f2a800e9c2db"
}
],
"insert_headers": {
"X-Forwarded-Port": "true",
"X-Forwarded-For": "true"
},
"created_at": "2017-02-28T00:42:44",
"updated_at": "2017-02-28T00:44:30",
"id": "023f2e34-7806-443b-bfae-16c324569a3d",
"operating_status": "ONLINE",
"default_pool_id": "ddb2b28f-89e9-45d3-a329-a359c3e39e4a",
"sni_container_refs": [
"http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"http://198.51.100.10:9311/v1/containers/aaebb31e-7761-4826-8cb4-2b829caca3ee"
],
"l7policies": [
{
"id": "5e618272-339d-4a80-8d14-dbc093091bb1"
}
],
"name": "great_tls_listener"
}
}

1
api-ref/source/v2/examples/listener-stats-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/listeners/023f2e34-7806-443b-bfae-16c324569a3d/stats

9
api-ref/source/v2/examples/listener-stats-response.json Normal file
View File

@@ -0,0 +1,9 @@
{
"stats": {
"bytes_in": 65671420,
"total_connections": 26189172,
"active_connections": 48629,
"bytes_out": 774771186,
"request_errors": 0
}
}

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

@@ -0,0 +1 @@
curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"listener": {"description": "An updated great TLS listener", "admin_state_up": true, "connection_limit": 200, "name": "great_updated_tls_listener", "insert_headers": {"X-Forwarded-For": "false", "X-Forwarded-Port": "true"}, "default_tls_container_ref": "http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51", "sni_container_refs": ["http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51", "http://198.51.100.10:9311/v1/containers/aaebb31e-7761-4826-8cb4-2b829caca3ee"]}}' http://198.51.100.10:9876/v2.0/lbaas/listeners/023f2e34-7806-443b-bfae-16c324569a3d

18
api-ref/source/v2/examples/listener-update-request.json Normal file
View File

@@ -0,0 +1,18 @@
{
"listener": {
"description": "An updated great TLS listener",
"admin_state_up": true,
"connection_limit": 200,
"name": "great_updated_tls_listener",
"default_pool_id": "ddb2b28f-89e9-45d3-a329-a359c3e39e4a",
"insert_headers": {
"X-Forwarded-For": "false",
"X-Forwarded-Port": "true"
},
"default_tls_container_ref": "http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"sni_container_refs": [
"http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"http://198.51.100.10:9311/v1/containers/aaebb31e-7761-4826-8cb4-2b829caca3ee"
]
}
}

36
api-ref/source/v2/examples/listener-update-response.json Normal file
View File

@@ -0,0 +1,36 @@
{
"listener": {
"description": "An updated great TLS listener",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"protocol": "TERMINATED_HTTPS",
"protocol_port": 443,
"provisioning_status": "PENDING_UPDATE",
"default_tls_container_ref": "http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"loadbalancers": [
{
"id": "607226db-27ef-4d41-ae89-f2a800e9c2db"
}
],
"insert_headers": {
"X-Forwarded-Port": "true",
"X-Forwarded-For": "false"
},
"created_at": "2017-02-28T00:42:44",
"updated_at": "2017-02-28T00:44:30",
"id": "023f2e34-7806-443b-bfae-16c324569a3d",
"operating_status": "OFFLINE",
"default_pool_id": "ddb2b28f-89e9-45d3-a329-a359c3e39e4a",
"sni_container_refs": [
"http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"http://198.51.100.10:9311/v1/containers/aaebb31e-7761-4826-8cb4-2b829caca3ee"
],
"l7policies": [
{
"id": "5e618272-339d-4a80-8d14-dbc093091bb1"
}
],
"name": "great_updated_tls_listener"
}
}

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

39
api-ref/source/v2/examples/listeners-list-response.json Normal file
View File

@@ -0,0 +1,39 @@
{
"listeners": [
{
"description": "A great TLS listener",
"admin_state_up": true,
"tenant_id": "e3cd678b11784734bc366148aa37580e",
"project_id": "e3cd678b11784734bc366148aa37580e",
"protocol": "TERMINATED_HTTPS",
"protocol_port": 443,
"provisioning_status": "ACTIVE",
"default_tls_container_ref": "http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"loadbalancers": [
{
"id": "607226db-27ef-4d41-ae89-f2a800e9c2db"
}
],
"insert_headers": {
"X-Forwarded-Port": "true",
"X-Forwarded-For": "true"
},
"created_at": "2017-02-28T00:42:44",
"updated_at": "2017-02-28T00:44:30",
"id": "023f2e34-7806-443b-bfae-16c324569a3d",
"operating_status": "ONLINE",
"default_pool_id": "ddb2b28f-89e9-45d3-a329-a359c3e39e4a",
"sni_container_refs": [
"http://198.51.100.10:9311/v1/containers/a570068c-d295-4780-91d4-3046a325db51",
"http://198.51.100.10:9311/v1/containers/aaebb31e-7761-4826-8cb4-2b829caca3ee"
],
"l7policies": [
{
"id": "58284ac9-673e-47ff-9dcb-09871a1956c4",
"id": "5e618272-339d-4a80-8d14-dbc093091bb1"
}
],
"name": "great_tls_listener"
}
]
}

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

@@ -14,7 +14,7 @@
"created_at": "2017-02-28T00:41:44", "created_at": "2017-02-28T00:41:44",
"updated_at": "2017-02-28T00:43:30", "updated_at": "2017-02-28T00:43:30",
"id": "607226db-27ef-4d41-ae89-f2a800e9c2db", "id": "607226db-27ef-4d41-ae89-f2a800e9c2db",
"operating_status": "ONLINE", "operating_status": "OFFLINE",
"name": "best_load_balancer" "name": "best_load_balancer"
} }
} }

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

@@ -15,3 +15,8 @@ General API Overview
Load Balancers Load Balancers
-------------- --------------
.. include:: loadbalancer.inc .. include:: loadbalancer.inc
---------
Listeners
---------
.. include:: listener.inc

473
api-ref/source/v2/listener.inc Normal file
View File

@@ -0,0 +1,473 @@
.. -*- rst -*-
List listeners
==============
.. rest_method:: GET /v2.0/lbaas/listeners
Lists all listeners 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 listeners 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
- tenant_id: tenant_id_query
Curl Example
------------
.. literalinclude:: examples/listeners-list-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up
- connection_limit: connection_limit
- created_at: created_at
- default_pool_id: default_pool_id
- default_tls_container_ref: default_tls_container_ref
- description: description
- id: listener-id
- insert_headers: insert_headers
- l7policies: l7policy-ids
- listener: listener
- loadbalancers: loadbalancer-ids
- name: name
- operating_status: operating_status
- project_id: project_id
- protocol: protocol
- protocol_port: protocol_port
- provisioning_status: provisioning_status
- sni_container_refs: sni_container_refs
- tenant_id: tenant_id
Response Example
----------------
.. literalinclude:: examples/listeners-list-response.json
:language: javascript
Create Listener
===============
.. rest_method:: POST /v2.0/lbaas/listeners
Creates a listener for a load balancer.
The listener configures a port and protocol for the load balancer to listen
on for incoming requests. A load balancer may have zero or more listeners
configured.
This operation provisions a new listener 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 that
contains a unique ID and the status of provisioning the listener.
In the response, the listener :ref:`provisioning status<prov_status>` is
``ACTIVE``, ``PENDING_CREATE``, or ``ERROR``.
If the status is ``PENDING_CREATE``, issue GET
``/v2.0/lbaas/listeners/{listener_id}`` to view the progress of
the provisioning operation. When the listener status changes
to ``ACTIVE``, the listener 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.
Specifying a project_id or tenant_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
specifying the additional elements or attributes in the request.
To create a listener, 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
.. _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
-------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up-default-optional
- connection_limit: connection_limit-optional
- default_pool: pool-optional
- default_pool_id: default_pool_id-optional
- default_tls_container_ref: default_tls_container_ref-optional
- description: description-optional
- insert_headers: insert_headers-optional
- l7policies: l7policies-optional
- listeners: listener
- loadbalancer_id: loadbalancer-id
- name: name-optional
- project_id: project_id-optional-deprecated
- protocol: protocol
- protocol_port: protocol_port
- sni_container_refs: sni_container_refs-optional
- tenant_id: tenant_id
Request Example
----------------
.. literalinclude:: examples/listener-create-request.json
:language: javascript
Curl Example
------------
.. literalinclude:: examples/listener-create-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up
- connection_limit: connection_limit
- created_at: created_at
- default_pool_id: default_pool_id
- default_tls_container_ref: default_tls_container_ref
- description: description
- id: listener-id
- insert_headers: insert_headers
- l7policies: l7policy-ids
- listener: listener
- loadbalancers: loadbalancer-ids
- name: name
- operating_status: operating_status
- project_id: project_id
- protocol: protocol
- protocol_port: protocol_port
- provisioning_status: provisioning_status
- sni_container_refs: sni_container_refs
- tenant_id: tenant_id
Response Example
----------------
.. literalinclude:: examples/listener-create-response.json
:language: javascript
Show Listener details
=====================
.. rest_method:: GET /v2.0/lbaas/listeners/{listener_id}
Shows the details of a listener.
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
- listener_id: path-listener-id
Curl Example
------------
.. literalinclude:: examples/listener-show-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up
- connection_limit: connection_limit
- created_at: created_at
- default_pool_id: default_pool_id
- default_tls_container_ref: default_tls_container_ref
- description: description
- id: listener-id
- insert_headers: insert_headers
- l7policies: l7policy-ids
- listener: listener
- loadbalancers: loadbalancer-ids
- name: name
- operating_status: operating_status
- project_id: project_id
- protocol: protocol
- protocol_port: protocol_port
- provisioning_status: provisioning_status
- sni_container_refs: sni_container_refs
- tenant_id: tenant_id
Response Example
----------------
.. literalinclude:: examples/listener-show-response.json
:language: javascript
Update a listener
=================
.. rest_method:: PUT /v2.0/lbaas/listeners/{listener_id}
Update an existing listener.
If the request is valid, the service returns the ``Accepted (202)``
response code. To confirm the update, check that the listener provisioning
status is ``ACTIVE``. If the status is ``PENDING_UPDATE``, use a GET
operation to poll the listener object for changes.
This operation returns the updated listener 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
- connection_limit: connection_limit-optional
- default_pool_id: default_pool_id-optional
- default_tls_container_ref: default_tls_container_ref-optional
- description: description-optional
- insert_headers: insert_headers-optional
- listener_id: path-listener-id
- name: name-optional
- sni_container_refs: sni_container_refs-optional
Request Example
---------------
.. literalinclude:: examples/listener-update-request.json
:language: javascript
Curl Example
------------
.. literalinclude:: examples/listener-update-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up
- connection_limit: connection_limit
- created_at: created_at
- default_pool_id: default_pool_id
- default_tls_container_ref: default_tls_container_ref
- description: description
- id: listener-id
- insert_headers: insert_headers
- l7policies: l7policy-ids
- listener: listener
- loadbalancers: loadbalancer-ids
- name: name
- operating_status: operating_status
- project_id: project_id
- protocol: protocol
- protocol_port: protocol_port
- provisioning_status: provisioning_status
- sni_container_refs: sni_container_refs
- tenant_id: tenant_id
Response Example
----------------
.. literalinclude:: examples/listener-update-response.json
:language: javascript
Remove a listener
=================
.. rest_method:: DELETE /v2.0/lbaas/listeners/{listener_id}
Removes a listener and its associated configuration from the project.
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
- listener_id: path-listener-id
Curl Example
------------
.. literalinclude:: examples/listener-delete-curl
:language: bash
Response
--------
There is no body content for the response of a successful DELETE request.
Get listener statistics
=======================
.. rest_method:: GET /v2.0/lbaas/listeners/{listener_id}/stats
Shows the current statistics for a listener.
This operation returns the statistics of a listener object identified
by listener_id.
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
- listener_id: path-listener-id
Curl Example
------------
.. literalinclude:: examples/listener-stats-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- stats: stats
- active_connections: active_connections
- bytes_in: bytes_in
- bytes_out: bytes_out
- request_errors: request_errors
- total_connections: total_connections
Response Example
----------------
.. literalinclude:: examples/listener-stats-response.json
:language: javascript

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

@@ -375,7 +375,7 @@ Remove a load balancer
Removes a load balancer and its associated configuration from the project. Removes a load balancer and its associated configuration from the project.
The API immediately purges any and all configuration data, depending on the The API immediately purges any and all configuration data, depending on the
configuration settings.. You cannot recover it. configuration settings. You cannot recover it.
.. rest_status_code:: success ../http-status.yaml .. rest_status_code:: success ../http-status.yaml