Octavia API v2 (Current)

General API Overview

This section introduces readers to OpenStack Octavia v2 ReSTful HTTP API and provides guidelines on how to use it.

Note

To clarify the Octavia API versioning we have updated the endpoint to support both the previously documented /v2.0 and the new path of /v2. They are exactly the same API and /v2.0 will be a supported alias for the life of the v2 API.

Service Endpoints

All API calls described throughout the rest of this document require authentication with the OpenStack Identity service. After authentication, the base endpoint URL for the service type of load-balancer and service name of octavia can be extracted from the service catalog returned with the identity token.

Example token snippet with service catalog

{
    "token": {
        "catalog": [
            {
                "endpoints": [
                    {
                        "url": "http://198.51.100.10:9876/",
                        "interface": "public",
                        "region": "RegionOne",
                        "region_id": "RegionOne",
                        "id": "cd1c3c2dc6434c739ed0a12015373754"
                    }
                ],
                "type": "load-balancer",
                "id": "1209701aecd3453e9803119cd28cb013",
                "name": "octavia"
            }
        ]
    }
}

For instance, if the endpoint URL is http://198.51.100.10:9876/ then the full API call for /v2/lbaas/loadbalancers is http://198.51.100.10:9876/v2/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 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 should always be discovered from the Identity token.

As such, for the rest of this document we will be using short hand where GET /v2/lbaas/loadbalancers really means GET {your_load-balancer_endpoint_URL}/v2/lbaas/loadbalancers.

Neutron-lbaas and Octavia v2 APIs

The Octavia v2 API is fully backward compatible with the neutron-lbaas v2 API and is a superset of the neutron-lbaas v2 API. This is intended to provide a simple migration path for deployments currently using the neutron-lbaas v2 API. You can update the endpoint your application is using from the keystone service catalog to use the octavia endpoint instead of the neutron endpoint for load balancer activities.

During the neutron-lbaas deprecation period a pass-through proxy will be included in neutron to allow requests via neutron and the neutron-lbaas v2 API to continue to function. Users are strongly encouraged to update their applications to access load balancing via the Octavia v2 API.

Warning

Load balancing functions accessed via the neutron endpoint are deprecated and will be removed in a future release. Users are strongly encouraged to migrate to using the octavia endpoint.

Authentication and authorization

The Octavia API v2 uses the OpenStack Identity service as the default authentication service. When Keystone is enabled, users that submit requests to the Octavia service must provide an authentication token in X-Auth-Token request 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.

The default authorization settings allow only administrative users to create resources on behalf of a different project.

Octavia uses information received from Keystone to authorize user requests. Octavia Networking handles the following types of authorization policies:

  • Operation-based policies specify access criteria for specific operations, possibly with fine-grained control over specific attributes.

  • Resource-based policies access a specific resource. Permissions might or might not be granted depending on the permissions configured for the resource. Currently available for only the network resource.

The actual authorization policies enforced in Octavia might vary from deployment to deployment.

Request and response formats

The Octavia API v2 supports JSON data serialization request and response formats only.

Request format

The Octavia API v2 only accepts requests with the JSON data serialization format. The request must have no Accept header or an Accept header that is compatible with application/json. The one exception is the Oslo middleware healthcheck endpoint.

Response format

The Octavia API v2 always responds with the JSON data serialization format. The one exception is the Oslo middleware healthcheck endpoint.

Query extension

A .json extension can be added to the request URI. For example, the .json extension in the following requests are equivalent:

  • GET publicURL/loadbalancers

  • GET publicURL/loadbalancers.json

Filtering and column selection

The Octavia API v2 supports filtering based on all top level attributes of a resource. Filters are applicable to all list requests.

For example, the following request returns all loadbalancers named foobar:

GET /v2/lbaas/loadbalancers?name=foobar

When you specify multiple filters, the Octavia API v2 returns only objects that meet all filtering criteria. The operation applies an AND condition among the filters.

Note

Octavia does not offer an OR mechanism for filters.

Alternatively, you can issue a distinct request for each filter and build a response set from the received responses on the client-side.

Filtering by Tags

New in version 2.5

Most Octavia resources support adding tags to the resource attributes. Octavia supports advanced filtering using these tags. The following tag filters are supported by the Octavia API:

  • tags - Return the list of entities that have this tag or tags.

  • tags-any - Return the list of entities that have one or more of the given tags.

  • not-tags - Return the list of entities that do not have one or more of the given tags.

  • not-tags-any - Return the list of entities that do not have at least one of the given tags.

When supplying a list of tags, the tags should be provided in a comma separated list.

For example, if you would like to get the list of load balancers with both the “red” and “blue” tags you would request:

GET /v2/lbaas/loadbalancers?tags=red,blue

To get a list of load balancers that have the “red” or “blue” tag, you would request:

GET /v2/lbaas/loadbalancers?tags-any=red,blue

For a list of load balancers that do not have the “red” tag, you would request:

GET /v2/lbaas/loadbalancers?not-tags=red

To get a list of load balancers that don’t have either the “red” or “blue” tag you would request:

GET /v2/lbaas/loadbalancers?not-tags-any=red,blue

Tag filters can also be combined in the same request:

GET /v2/lbaas/loadbalancers?tags=red,blue&tags-any=green,orange

Column Selection

By default, Octavia returns all attributes for any show or list call. The Octavia API v2 has a mechanism to limit the set of attributes returned. For example, return id.

You can use the fields query parameter to control the attributes returned from the Octavia API v2.

For example, the following request returns only id and name for each load balancer:

GET /v2/lbaas/loadbalancers.json?fields=id&fields=name

Synchronous versus asynchronous plug-in behavior

The Octavia API v2 presents a logical model of load balancers consisting of listeners, pools, and members. It is up to the OpenStack Octavia plug-in to communicate with the underlying infrastructure to ensure load balancing is consistent with the logical model. A plug-in might perform these operations asynchronously.

When an API client modifies the logical model by issuing an HTTP POST, PUT, or DELETE request, the API call might return before the plug-in modifies underlying virtual and physical load balancing devices. However, an API client is guaranteed that all subsequent API calls properly reflect the changed logical model.

For example, if a client issues an HTTP PUT request to set the weight of a member, there is no guarantee that the new weight will be in effect when the HTTP call returns. This is indicated by an HTTP response code of 202.

You can use the provisioning_status attribute to determine whether the Octavia plug-in has successfully completed the configuration of the resource.

Bulk-create

The Octavia v2 API does not support bulk create. You cannot create more than one load balancer per API call.

The Octavia v2 API does support single call create which allows you to create a fully populated load balancer in one API call. This is discussed in the load balancer create section of this reference.

Pagination

To reduce load on the service, list operations will return a maximum number of items at a time. To navigate the collection, the parameters limit, marker and page_reverse can be set in the URI. For example:

?limit=100&marker=1234&page_reverse=False

The marker parameter is the ID of the last item in the previous list. The limit parameter sets the page size. The page_reverse parameter sets the page direction. These parameters are optional. If the client requests a limit beyond the maximum limit configured by the deployment, the server returns the maximum limit number of items.

For convenience, list responses contain atom “next” links and “previous” links. The last page in the list requested with ‘page_reverse=False’ will not contain “next” link, and the last page in the list requested with ‘page_reverse=True’ will not contain “previous” link. The following examples illustrate two pages with three items. The first page was retrieved through:

GET http://198.51.100.10:9876/v2/lbaas/loadbalancers.json?limit=2

If a particular plug-in does not support pagination operations the Octavia API v2 will emulate the pagination behavior so that users can expect the same behavior regardless of the particular plug-in running in the background.

Example load balancer list, first page: JSON request

GET /v2/lbaas/loadbalancers.json?limit=2 HTTP/1.1
Host: 198.51.100.10:9876
Content-Type: application/json
Accept: application/json

Example load balancer list, first page: JSON response

{
    "loadbalancers": [
        {
            "admin_state_up": true,
            "listeners": [],
            "vip_subnet_id": "08dce793-daef-411d-a896-d389cd45b1ea",
            "pools": [],
            "provider": "octavia",
            "description": "Best App load balancer 1",
            "name": "bestapplb1",
            "operating_status": "ONLINE",
            "id": "34d5f4a5-cbbc-43a0-878f-b8a26370e6e7",
            "provisioning_status": "ACTIVE",
            "vip_port_id": "1e20d91d-8df9-4c15-9778-28bc89226c19",
            "vip_address": "203.0.113.10",
            "project_id": "bf325b04-e7b1-4002-9b10-f4984630367f"
        },
        {
            "admin_state_up": true,
            "listeners": [],
            "vip_subnet_id": "08dce793-daef-411d-a896-d389cd45b1ea",
            "pools": [],
            "provider": "octavia",
            "description": "Second Best App load balancer 1",
            "name": "2ndbestapplb1",
            "operating_status": "ONLINE",
            "id": "0fdb0ca7-0a38-4aea-891c-daaed40bcafe",
            "provisioning_status": "ACTIVE",
            "vip_port_id": "21f7ac04-6824-4222-93cf-46e0d70607f9",
            "vip_address": "203.0.113.20",
            "project_id": "bf325b04-e7b1-4002-9b10-f4984630367f"
        }
    ],
    "loadbalancers_links": [
        {
            "href": "http://198.51.100.10:9876/v2/lbaas/loadbalancers.json?limit=2&marker=0fdb0ca7-0a38-4aea-891c-daaed40bcafe",
            "rel": "next"
        },
        {
            "href": "http://198.51.100.10:9876/v2/lbaas/loadbalancers.json?limit=2&marker=34d5f4a5-cbbc-43a0-878f-b8a26370e6e7&page_reverse=True",
            "rel": "previous"
        }
    ]
}

The last page won’t show the “next” links

Example load balancer list, last page: JSON request

GET /v2/lbaas/loadbalancers.json?limit=2&marker=4ef465f3-0233-44af-b93d-9d3eae4daf85 HTTP/1.1
Host: 198.51.100.10:9876
Content-Type: application/json
Accept: application/json

Example load balancer list, last page: JSON response

{
    "loadbalancers": [
        {
            "admin_state_up": true,
            "listeners": [],
            "vip_subnet_id": "08dce793-daef-411d-a896-d389cd45b1ea",
            "pools": [],
            "provider": "octavia",
            "description": "Other App load balancer 1",
            "name": "otherapplb1",
            "operating_status": "ONLINE",
            "id": "4ef465f3-0233-44af-b93d-9d3eae4daf85",
            "provisioning_status": "ACTIVE",
            "vip_port_id": "f777a1c7-7f59-4a36-ad34-24dfebaf19e6",
            "vip_address": "203.0.113.50",
            "project_id": "bf325b04-e7b1-4002-9b10-f4984630367f"
        }
    ],
    "loadbalancers_links": [
        {
            "href": "http://198.51.100.10:9876/v2/lbaas/loadbalancers.json?limit=2&marker=4ef465f3-0233-44af-b93d-9d3eae4daf85&page_reverse=True",
            "rel": "previous"
        }
    ]
}

Sorting

Sorting is determined through the use of the ‘sort’ query string parameter. The value of this parameter is a comma-separated list of sort keys. Sort directions can optionally be appended to each sort key, separated by the ‘:’ character.

The supported sort directions are either ‘asc’ for ascending or ‘desc’ for descending.

The caller may (but is not required to) specify a sort direction for each key. If a sort direction is not specified for a key, then a default is set by the server.

For example:

  • Only sort keys specified:

    • sort=key1,key2,key3

    • ‘key1’ is the first key, ‘key2’ is the second key, etc.

    • Sort directions are defaulted by the server

  • Some sort directions specified:

    • sort=key1:asc,key2,key3

    • Any sort key without a corresponding direction is defaulted

    • ‘key1’ is the first key (ascending order), ‘key2’ is the second key (direction defaulted by the server), etc.

  • Equal number of sort keys and directions specified:

    • sort=key1:asc,key2:desc,key3:asc

    • Each key is paired with the corresponding direction

    • ‘key1’ is the first key (ascending order), ‘key2’ is the second key (descending order), etc.

You can also use the sort_key and sort_dir parameters to sort the results of list operations. Currently sorting does not work with extended attributes of resource. The sort_key and sort_dir can be repeated, and the number of sort_key and sort_dir provided must be same. The sort_dir parameter indicates in which direction to sort. Acceptable values are asc (ascending) and desc (descending).

If a particular plug-in does not support sorting operations the Octavia API v2 emulates the sorting behavior so that users can expect the same behavior regardless of the particular plug-in that runs in the background.

Response Codes

The following HTTP response status codes are used by the Octavia v2 API.

Success

Code

Description

200

  • The synchronous request was successful

202

  • The asynchronous request was accepted and is being processed

204

  • The request was successful, no content to return

  • The entity was successfully deleted

Faults

The Octavia API v2 returns an error response if a failure occurs while processing a request. Octavia uses only standard HTTP error codes. 4nn errors indicate problems in the particular request being sent from the client.

Code

Description

400

  • Bad request

  • Malformed request URI or body requested

  • The request could not be understood

  • Invalid values entered

  • Bulk operations disallowed

  • Validation failed

  • Method not allowed for request body (such as trying to update attributes that can be specified at create-time only)

401

  • Unauthorized: Access is denied due to invalid credentials

403

  • Policy does not allow current user to do this operation

  • The project is over quota for the request

404

  • Not Found

  • Non existent URI

  • Resource not found

409

  • Conflict

  • The resource is in an immutable state

500

  • Internal server error

503

  • Service unavailable

  • The project is busy with other requests, try again later

Status Codes

Octavia API v2 entities have two status codes present in the response body. The provisioning_status describes the lifecycle status of the entity while the operating_status provides the observed status of the entity.

For example, a member may be in a provisioning_status of PENDING_UPDATE and have an operating_status of ONLINE. This would indicate that an update operation is occurring on this member and it is in an immutable state but it is healthy and able to service requests. This situation could occur if the user made a request to update the weight of the member.

Operating Status Codes

Code

Description

ONLINE

  • Entity is operating normally

  • All pool members are healthy

DRAINING

  • The member is not accepting new connections

OFFLINE

  • Entity is administratively disabled

DEGRADED

  • One or more of the entity’s components are in ERROR

ERROR

  • The entity has failed

  • The member is failing it’s health monitoring checks

  • All of the pool members are in ERROR

NO_MONITOR

  • No health monitor is configured for this entity and it’s status is unknown

Provisioning Status Codes

Code

Description

ACTIVE

  • The entity was provisioned successfully

DELETED

  • The entity has been successfully deleted

ERROR

  • Provisioning failed

PENDING_CREATE

  • The entity is being created

PENDING_UPDATE

  • The entity is being updated

PENDING_DELETE

  • The entity is being deleted

Entities in a PENDING_* state are immutable and cannot be modified until the requested operation completes. The entity will return to the ACTIVE provisioning status once the asynchronus operation completes.

An entity in ERROR has failed provisioning. The entity may be deleted and recreated.

Protocol Combinations (Listener/Pool)

The listener and pool can be associated through the listener’s default_pool_id or l7policy’s redirect_pool_id. Both listener and pool must set the protocol parameter, but the association between the listener and the pool isn’t arbitrary and has some constraints on the protocol aspect.

Valid protocol combinations

    Listener
Pool
HTTP

HTTPS

SCTP

TCP

TERMINATED_HTTPS

UDP

HTTP

  Y

  N

  N

  Y

        Y

  N

HTTPS

  N

  Y

  N

  Y

        N

  N

PROXY

  Y

  Y

  N

  Y

        Y

  N

PROXYV2

  Y

  Y

  N

  Y

        Y

  N

SCTP

  N

  N

  Y

  N

        N

  N

TCP

  N

  Y

  N

  Y

        N

  N

UDP

  N

  N

  N

  N

        N

  Y

“Y” means the combination is valid and “N” means invalid.

The HTTPS protocol is HTTPS pass-through. For most providers, this is treated as a TCP protocol. Some advanced providers may support HTTPS session persistence features by using the session ID. The Amphora provider treats HTTPS as a TCP flow, but currently does not support HTTPS session persistence using the session ID.

The pool protocol of PROXY will use the listener protocol as the pool protocol but will wrap that protocol in the proxy protocol. In the case of listener protocol TERMINATED_HTTPS, a pool protocol of PROXY will be HTTP wrapped in the proxy protocol.

Protocol Combinations (Pool/Health Monitor)

Pools and health monitors are also related with regard to protocol. Pools set the protocol parameter for the real member connections, and the health monitor sets a type for health checks. Health check types are limited based on the protocol of the pool.

Valid protocol combinations

    Health Monitor
Pool
HTTP

HTTPS

PING

SCTP

TCP

TLS-HELLO

UDP-CONNECT

HTTP

  Y

  Y

  Y

  N

  Y

    Y

      N

HTTPS

  Y

  Y

  Y

  N

  Y

    Y

      N

PROXY

  Y

  Y

  Y

  N

  Y

    Y

      N

PROXYV2

  Y

  Y

  Y

  N

  Y

    Y

      N

SCTP

  Y

  N

  N

  Y

  Y

    N

      Y

TCP

  Y

  Y

  Y

  N

  Y

    Y

      N

UDP

  Y

  N

  N

  Y

  Y

    N

      Y

“Y” means the combination is valid and “N” means invalid.

These combinations are mostly as you’d expect for all non-UDP/SCTP pool protocols: non-UDP/SCTP pools can have health monitors with any check type besides UDP-CONNECT and SCTP. For UDP or SCTP pools however, things are a little more complicated. UDP and SCTP Pools support UDP-CONNECT and SCTP but also HTTP and TCP checks. HTTPS checks are technically feasible but have not yet been implemented.

Load Balancers

GET
/v2/lbaas/loadbalancers

List Load Balancers

Lists all load balancers 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 Filtering and column selection.

Administrative users can specify a project ID that is different than their own to list load balancers for other projects.

The list might be empty.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

project_id (Optional)

query

string

The ID of the project to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/loadbalancers?project_id=e3cd678b11784734bc366148aa37580e

Response Parameters

Name

In

Type

Description

additional_vips (Optional)

body

array

A list of JSON objects defining “additional VIPs”. The format for these is {"subnet_id": <subnet_id>, "ip_address": <ip_address>}, where the subnet_id field is mandatory and the ip_address field is optional. Additional VIP subnets must all belong to the same network as the primary VIP.

New in version 2.26

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

availability_zone

body

object

An availability zone name.

created_at

body

string

The UTC date and timestamp when the resource was created.

description

body

string

A human-readable description for the resource.

flavor_id

body

uuid

The ID of the flavor.

id

body

uuid

The ID of the load balancer.

listeners

body

array

The associated listener IDs, if any.

loadbalancers

body

array

A list of loadbalancer objects.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

pools

body

array

The associated pool IDs, if any.

project_id

body

string

The ID of the project owning this resource.

provider

body

string

Provider name for the load balancer.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

vip_address

body

string

The IP address of the Virtual IP (VIP).

vip_network_id

body

uuid

The ID of the network for the Virtual IP (VIP).

vip_port_id

body

uuid

The ID of the Virtual IP (VIP) port.

vip_qos_policy_id

body

uuid

The ID of the QoS Policy which will apply to the Virtual IP (VIP).

vip_subnet_id

body

uuid

The ID of the subnet for the Virtual IP (VIP).

vip_vnic_type

body

string

The VIP vNIC type used for the load balancer. One of normal or direct.

New in version 2.28

Response Example

{
    "loadbalancers": [
        {
            "description": "My favorite load balancer",
            "admin_state_up": true,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "provisioning_status": "ACTIVE",
            "flavor_id": "",
            "vip_subnet_id": "d4af86e1-0051-488c-b7a0-527f97490c9a",
            "listeners": [
                {
                    "id": "023f2e34-7806-443b-bfae-16c324569a3d"
                }
            ],
            "vip_address": "203.0.113.50",
            "vip_network_id": "d0d217df-3958-4fbf-a3c2-8dad2908c709",
            "vip_port_id": "b4ca07d1-a31e-43e2-891a-7d14f419f342",
            "additional_vips": [],
            "provider": "octavia",
            "pools": [
                {
                    "id": "9aa16cdc-8d18-47b9-aba9-ec044531a79f"
                }
            ],
            "created_at": "2017-02-28T00:41:44",
            "updated_at": "2017-02-28T00:43:30",
            "id": "607226db-27ef-4d41-ae89-f2a800e9c2db",
            "operating_status": "ONLINE",
            "name": "best_load_balancer",
            "vip_qos_policy_id": "ec4f78ca-8da8-4e99-8a1a-e3b94595a7a3",
            "availability_zone": "my_az",
            "tags": [],
            "vip_vnic_type": "normal"
        }
    ]
}
POST
/v2/lbaas/loadbalancers

Create a Load Balancer

Creates a load balancer.

This operation provisions a new load balancer 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 load balancer.

In the response, the load balancer provisioning status is ACTIVE, PENDING_CREATE, or ERROR.

If the status is PENDING_CREATE, issue GET /v2/lbaas/loadbalancers/{loadbalancer_id} to view the progress of the provisioning operation. When the load balancer status changes to ACTIVE, the load balancer 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.

Administrative users can specify a project ID that is different than their own to create load balancers for other projects.

An optional flavor_id attribute can be used to create the load balancer using a pre-configured octavia flavor. Flavors are created by the operator to allow custom load balancer configurations, such as allocating more memory for the load balancer.

An optional vip_qos_policy_id attribute from Neutron can be used to apply QoS policies on a loadbalancer VIP, also could pass a ‘null’ value to remove QoS policies.

You can also specify the provider attribute when you create a load balancer. The provider attribute specifies which backend should be used to create the load balancer. This could be the default provider (octavia) or a vendor supplied provider if one has been installed. Setting both a flavor_id and a provider will result in a conflict error if the provider does not match the provider of the configured flavor profiles.

Specifying a Virtual IP (VIP) is mandatory. There are three ways to specify a VIP network for the load balancer:

  1. Provide a vip_port_id.

    Providing a neutron port ID for the vip_port_id tells octavia to use this port for the VIP. Some port settings may be changed or removed as required by octavia, but the IP address will be retained. If the port has more than one subnet you must specify either the vip_subnet_id or vip_address to clarify which address should be used for the VIP.

  2. Provide a vip_network_id.

    When a vip_network_ip is specified, unless neither vip_subnet_id nor vip_address is specified, octavia will select a subnet from the network, preferring IPv4 over IPv6 subnets.

  3. Provide a vip_subnet_id.

    Specifying a neutron subnet ID will tell octavia to create a neutron port on this subnet and allocate an IP address from the subnet if the vip_address was not specified. If vip_address was specified, octavia will attempt to allocate the vip_address from the subnet for the VIP address.

Additional VIPs may also be specified in the additional_vips field, by providing a list of JSON objects containing a subnet_id and optionally an ip_address. All additional subnets must be part of the same network as the primary VIP.

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

503 - Service Unavailable

The service cannot handle the request right now.

Request

Name

In

Type

Description

additional_vips (Optional)

body

array

A list of JSON objects defining “additional VIPs”. The format for these is {"subnet_id": <subnet_id>, "ip_address": <ip_address>}, where the subnet_id field is mandatory and the ip_address field is optional. Additional VIP subnets must all belong to the same network as the primary VIP.

New in version 2.26

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

availability_zone (Optional)

body

object

An availability zone name.

description (Optional)

body

string

A human-readable description for the resource.

flavor_id (Optional)

body

uuid

The ID of the flavor.

listeners (Optional)

body

array

The associated listener IDs, if any.

loadbalancer

body

object

A load balancer object.

name (Optional)

body

string

Human-readable name of the resource.

project_id (Optional)

body

string

The ID of the project owning this resource.

provider (Optional)

body

string

Provider name for the load balancer. Default is octavia.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

vip_address (Optional)

body

string

The IP address of the Virtual IP (VIP).

vip_network_id (Optional)

body

uuid

The ID of the network for the Virtual IP (VIP). One of vip_network_id, vip_port_id, or vip_subnet_id must be specified.

vip_port_id (Optional)

body

uuid

The ID of the Virtual IP (VIP) port. One of vip_network_id, vip_port_id, or vip_subnet_id must be specified.

vip_qos_policy_id (Optional)

body

uuid

The ID of the QoS Policy which will apply to the Virtual IP (VIP).

vip_subnet_id (Optional)

body

uuid

The ID of the subnet for the Virtual IP (VIP). One of vip_network_id, vip_port_id, or vip_subnet_id must be specified.

Request Example

{
    "loadbalancer": {
        "description": "My favorite load balancer",
        "admin_state_up": true,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "vip_subnet_id": "d4af86e1-0051-488c-b7a0-527f97490c9a",
        "vip_address": "203.0.113.50",
        "additional_vips": [
            {"subnet_id": "3ca40b2e-c286-4e53-bdb9-dd01c8a0ad6d", "ip_address": "2001:db8::b33f"},
            {"subnet_id": "44d92b92-510f-4c05-8058-bf5a17b4d41c"}
        ],
        "provider": "octavia",
        "name": "best_load_balancer",
        "vip_qos_policy_id": "ec4f78ca-8da8-4e99-8a1a-e3b94595a7a3",
        "availability_zone": "my_az",
        "tags": ["test_tag"]
    }
}

Curl Example

curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"loadbalancer": {"description": "My favorite load balancer", "admin_state_up": true, "project_id": "e3cd678b11784734bc366148aa37580e", "flavor_id": "a7ae5d5a-d855-4f9a-b187-af66b53f4d04", "vip_subnet_id": "d4af86e1-0051-488c-b7a0-527f97490c9a", "vip_address": "203.0.113.50", "additional_vips": [{"subnet_id": "3ca40b2e-c286-4e53-bdb9-dd01c8a0ad6d", "ip_address": "2001:db8::b33f"}, {"subnet_id": "44d92b92-510f-4c05-8058-bf5a17b4d41c"}], "provider": "octavia", "name": "best_load_balancer", "vip_qos_policy_id": "ec4f78ca-8da8-4e99-8a1a-e3b94595a7a3", "availability_zone": "my_az", "tags": ["test_tag"]}}' http://198.51.100.10:9876/v2/lbaas/loadbalancers

Response Parameters

Name

In

Type

Description

additional_vips (Optional)

body

array

A list of JSON objects defining “additional VIPs”. The format for these is {"subnet_id": <subnet_id>, "ip_address": <ip_address>}, where the subnet_id field is mandatory and the ip_address field is optional. Additional VIP subnets must all belong to the same network as the primary VIP.

New in version 2.26

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

availability_zone

body

object

An availability zone name.

created_at

body

string

The UTC date and timestamp when the resource was created.

description

body

string

A human-readable description for the resource.

flavor_id

body

uuid

The ID of the flavor.

id

body

uuid

The ID of the load balancer.

listeners

body

array

The associated listener IDs, if any.

loadbalancer

body

object

A load balancer object.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

pools

body

array

The associated pool IDs, if any.

project_id

body

string

The ID of the project owning this resource.

provider

body

string

Provider name for the load balancer.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

vip_address

body

string

The IP address of the Virtual IP (VIP).

vip_network_id

body

uuid

The ID of the network for the Virtual IP (VIP).

vip_port_id

body

uuid

The ID of the Virtual IP (VIP) port.

vip_qos_policy_id

body

uuid

The ID of the QoS Policy which will apply to the Virtual IP (VIP).

vip_subnet_id

body

uuid

The ID of the subnet for the Virtual IP (VIP).

vip_vnic_type

body

string

The VIP vNIC type used for the load balancer. One of normal or direct.

New in version 2.28

Response Example

{
    "loadbalancer": {
        "description": "My favorite load balancer",
        "admin_state_up": true,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "provisioning_status": "PENDING_CREATE",
        "flavor_id": "",
        "vip_subnet_id": "d4af86e1-0051-488c-b7a0-527f97490c9a",
        "vip_address": "203.0.113.50",
        "vip_network_id": "d0d217df-3958-4fbf-a3c2-8dad2908c709",
        "vip_port_id": "b4ca07d1-a31e-43e2-891a-7d14f419f342",
        "additional_vips": [
            {"subnet_id": "3ca40b2e-c286-4e53-bdb9-dd01c8a0ad6d", "ip_address": "2001:db8::b33f"},
            {"subnet_id": "44d92b92-510f-4c05-8058-bf5a17b4d41c", "ip_address": "198.51.100.4"}
        ],
        "provider": "octavia",
        "created_at": "2017-02-28T00:41:44",
        "updated_at": "2017-02-28T00:43:30",
        "id": "607226db-27ef-4d41-ae89-f2a800e9c2db",
        "operating_status": "OFFLINE",
        "name": "best_load_balancer",
        "vip_qos_policy_id": "ec4f78ca-8da8-4e99-8a1a-e3b94595a7a3",
        "availability_zone": "my_az",
        "tags": ["test_tag"],
        "vip_vnic_type": "normal"
    }
}

Creating a Fully Populated Load Balancer

You can configure all documented features of the load balancer at creation time by specifying the additional elements or attributes in the request.

Note: all pools must have names, and must only be fully defined once. To reference a pool from multiple objects, supply the pool name only for all subsequent references.

Request Example

{
    "loadbalancer": {
        "description": "My favorite load balancer",
        "admin_state_up": true,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "flavor_id": "",
        "listeners": [
            {
                "name": "http_listener",
                "protocol": "HTTP",
                "protocol_port": 80,
                "default_pool": {
                    "name": "rr_pool",
                    "protocol": "HTTP",
                    "lb_algorithm": "ROUND_ROBIN",
                    "healthmonitor": {
                        "type": "HTTP",
                        "delay": "3",
                        "expected_codes": "200,201,202",
                        "http_method": "GET",
                        "max_retries": 2,
                        "timeout": 1,
                        "url_path": "/index.html"
                    },
                    "members": [
                        {
                            "address": "192.0.2.16",
                            "protocol_port": 80
                        },
                        {
                            "address": "192.0.2.19",
                            "protocol_port": 80
                        }
                    ]
                }
            },
            {
                "name": "https_listener",
                "protocol": "HTTPS",
                "protocol_port": 443,
                "default_pool": {
                    "name": "https_pool"
                },
                "tags": ["test_tag"]
            },
            {
                "name": "redirect_listener",
                "protocol": "HTTP",
                "protocol_port": 8080,
                "l7policies": [
                    {
                        "action": "REDIRECT_TO_URL",
                        "name": "redirect_policy",
                        "redirect_url": "https://www.example.com/",
                        "admin_state_up": true
                    }
                ]
            }
        ],
        "pools": [
            {
                "name": "https_pool",
                "protocol": "HTTPS",
                "lb_algorithm": "ROUND_ROBIN",
                "healthmonitor": {
                    "type": "HTTPS",
                    "delay": "3",
                    "max_retries": 2,
                    "timeout": 1
                },
                "members": [
                    {
                        "address": "192.0.2.51",
                        "protocol_port": 80
                    },
                    {
                        "address": "192.0.2.52",
                        "protocol_port": 80
                    }
                ]
            }
        ],
        "vip_subnet_id": "d4af86e1-0051-488c-b7a0-527f97490c9a",
        "vip_address": "203.0.113.50",
        "provider": "octavia",
        "name": "best_load_balancer",
        "vip_qos_policy_id": "ec4f78ca-8da8-4e99-8a1a-e3b94595a7a3",
        "availability_zone": "my_az",
        "tags": ["test_tag"]
    }
}

Response Example

{
    "loadbalancer": {
        "description": "My favorite load balancer",
        "admin_state_up": true,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "provisioning_status": "ACTIVE",
        "flavor_id": "",
        "vip_subnet_id": "d4af86e1-0051-488c-b7a0-527f97490c9a",
        "listeners": [
            {
                "l7policies": [],
                "protocol": "HTTP",
                "description": "",
                "default_tls_container_ref": null,
                "admin_state_up": true,
                "default_pool": {
                    "id": "c8cec227-410a-4a5b-af13-ecf38c2b0abb"
                },
                "project_id": "e3cd678b11784734bc366148aa37580e",
                "default_tls_container_id": null,
                "connection_limit": -1,
                "sni_container_refs": [],
                "protocol_port": 80,
                "id": "a99995c6-4f04-4ed3-a37f-ae58f6e7e5e1",
                "name": "http_listener"
            },
            {
                "l7policies": [],
                "protocol": "HTTPS",
                "description": "",
                "default_tls_container_ref": null,
                "admin_state_up": true,
                "default_pool": {
                    "id": "b0577aff-c1f9-40c6-9a3b-7b1d2a669136"
                },
                "project_id": "e3cd678b11784734bc366148aa37580e",
                "default_tls_container_id": null,
                "connection_limit": -1,
                "sni_container_refs": [],
                "protocol_port": 443,
                "id": "73c6c564-f215-48e9-91d6-f10bb3454954",
                "name": "https_listener",
                "tags": ["test_tag"]
            },
            {
                "l7policies": [
                    {
                        "description": "",
                        "admin_state_up": true,
                        "rules": [],
                        "project_id": "e3cd678b11784734bc366148aa37580e",
                        "listener_id": "95de30ec-67f4-437b-b3f3-22c5d9ef9828",
                        "redirect_url": "https://www.example.com/",
                        "action": "REDIRECT_TO_URL",
                        "position": 1,
                        "id": "d0553837-f890-4981-b99a-f7cbd6a76577",
                        "name": "redirect_policy"
                    }
                ],
                "protocol": "HTTP",
                "description": "",
                "default_tls_container_ref": null,
                "admin_state_up": true,
                "default_pool": null,
                "project_id": "e3cd678b11784734bc366148aa37580e",
                "default_tls_container_id": null,
                "connection_limit": -1,
                "sni_container_refs": [],
                "protocol_port": 8080,
                "id": "95de30ec-67f4-437b-b3f3-22c5d9ef9828",
                "name": "redirect_listener"
            }
        ],
        "vip_address": "203.0.113.50",
        "vip_network_id": "d0d217df-3958-4fbf-a3c2-8dad2908c709",
        "vip_port_id": "b4ca07d1-a31e-43e2-891a-7d14f419f342",
        "additional_vips": [],
        "provider": "octavia",
        "pools": [
            {
                "lb_algorithm": "ROUND_ROBIN",
                "protocol": "HTTP",
                "description": "",
                "admin_state_up": true,
                "project_id": "e3cd678b11784734bc366148aa37580e",
                "session_persistence": null,
                "healthmonitor": {
                    "name": "",
                    "admin_state_up": true,
                    "project_id": "e3cd678b11784734bc366148aa37580e",
                    "delay": 3,
                    "expected_codes": "200,201,202",
                    "max_retries": 2,
                    "http_method": "GET",
                    "timeout": 1,
                    "max_retries_down": 3,
                    "url_path": "/index.html",
                    "type": "HTTP",
                    "id": "a8a2aa3f-d099-4752-8265-e6472f8147f9"
                },
                "members": [
                    {
                        "name": "",
                        "weight": 1,
                        "admin_state_up": true,
                        "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
                        "project_id": "e3cd678b11784734bc366148aa37580e",
                        "address": "192.0.2.16",
                        "protocol_port": 80,
                        "id": "7d19ad6c-d549-453e-a5cd-05382c6be96a"
                    },
                    {
                        "name": "",
                        "weight": 1,
                        "admin_state_up": true,
                        "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
                        "project_id": "e3cd678b11784734bc366148aa37580e",
                        "address": "192.0.2.19",
                        "protocol_port": 80,
                        "id": "a167402b-caa6-41d5-b4d4-bde7f2cbfa5e"
                    }
                ],
                "id": "c8cec227-410a-4a5b-af13-ecf38c2b0abb",
                "name": "rr_pool"
            },
            {
                "lb_algorithm": "ROUND_ROBIN",
                "protocol": "HTTPS",
                "description": "",
                "admin_state_up": true,
                "project_id": "e3cd678b11784734bc366148aa37580e",
                "session_persistence": null,
                "healthmonitor": {
                    "name": "",
                    "admin_state_up": true,
                    "project_id": "e3cd678b11784734bc366148aa37580e",
                    "delay": 3,
                    "expected_codes": "200,201,202",
                    "max_retries": 2,
                    "http_method": "GET",
                    "timeout": 1,
                    "max_retries_down": 3,
                    "url_path": "/index.html",
                    "type": "HTTPS",
                    "id": "d5bb7712-26b7-4809-8c14-3b407c0cb00d"
                },
                "members": [
                    {
                        "name": "",
                        "weight": 1,
                        "admin_state_up": true,
                        "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
                        "project_id": "e3cd678b11784734bc366148aa37580e",
                        "address": "192.0.2.51",
                        "protocol_port": 80,
                        "id": "f83832d5-1f22-45fa-866a-4abea36e0886"
                    },
                    {
                        "name": "",
                        "weight": 1,
                        "admin_state_up": true,
                        "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
                        "project_id": "e3cd678b11784734bc366148aa37580e",
                        "address": "192.0.2.52",
                        "protocol_port": 80,
                        "id": "f83832d5-1f22-45fa-866a-4abea36e0886"
                    }
                ],
                "id": "b0577aff-c1f9-40c6-9a3b-7b1d2a669136",
                "name": "https_pool"
            }
        ],
        "created_at": "2017-02-28T00:41:44",
        "updated_at": "2017-02-28T00:43:30",
        "id": "607226db-27ef-4d41-ae89-f2a800e9c2db",
        "operating_status": "ONLINE",
        "name": "best_load_balancer",
        "vip_qos_policy_id": "ec4f78ca-8da8-4e99-8a1a-e3b94595a7a3",
        "availability_zone": "my_az",
        "tags": ["test_tag"],
        "vip_vnic_type": "normal"
    }
}
GET
/v2/lbaas/loadbalancers/{loadbalancer_id}

Show Load Balancer details

Shows the details of a load balancer.

If you are not an administrative user and the load balancer object does not belong to your project, the service returns the HTTP Forbidden (403) response code.

This operation does not require a request body.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

loadbalancer_id

path

uuid

The ID of the load balancer to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/loadbalancers/8a562351-f0fb-424c-a0af-513461424ea5

Response Parameters

Name

In

Type

Description

additional_vips (Optional)

body

array

A list of JSON objects defining “additional VIPs”. The format for these is {"subnet_id": <subnet_id>, "ip_address": <ip_address>}, where the subnet_id field is mandatory and the ip_address field is optional. Additional VIP subnets must all belong to the same network as the primary VIP.

New in version 2.26

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

availability_zone

body

object

An availability zone name.

created_at

body

string

The UTC date and timestamp when the resource was created.

description

body

string

A human-readable description for the resource.

flavor_id

body

uuid

The ID of the flavor.

id

body

uuid

The ID of the load balancer.

loadbalancer

body

object

A load balancer object.

listeners

body

array

The associated listener IDs, if any.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

pools

body

array

The associated pool IDs, if any.

project_id

body

string

The ID of the project owning this resource.

provider

body

string

Provider name for the load balancer.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

vip_address

body

string

The IP address of the Virtual IP (VIP).

vip_network_id

body

uuid

The ID of the network for the Virtual IP (VIP).

vip_port_id

body

uuid

The ID of the Virtual IP (VIP) port.

vip_qos_policy_id

body

uuid

The ID of the QoS Policy which will apply to the Virtual IP (VIP).

vip_subnet_id

body

uuid

The ID of the subnet for the Virtual IP (VIP).

vip_vnic_type

body

string

The VIP vNIC type used for the load balancer. One of normal or direct.

New in version 2.28

Response Example

{
    "loadbalancer": {
        "description": "My favorite load balancer",
        "admin_state_up": true,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "provisioning_status": "PENDING_CREATE",
        "flavor_id": "",
        "vip_subnet_id": "d4af86e1-0051-488c-b7a0-527f97490c9a",
        "vip_address": "203.0.113.50",
        "vip_network_id": "d0d217df-3958-4fbf-a3c2-8dad2908c709",
        "vip_port_id": "b4ca07d1-a31e-43e2-891a-7d14f419f342",
        "additional_vips": [],
        "provider": "octavia",
        "created_at": "2017-02-28T00:41:44",
        "updated_at": "2017-02-28T00:43:30",
        "id": "8a562351-f0fb-424c-a0af-513461424ea5",
        "operating_status": "ONLINE",
        "name": "best_load_balancer",
        "vip_qos_policy_id": "ec4f78ca-8da8-4e99-8a1a-e3b94595a7a3",
        "availability_zone": "my_az",
        "tags": [],
        "vip_vnic_type": "normal"
    }
}
PUT
/v2/lbaas/loadbalancers/{loadbalancer_id}

Update a Load Balancer

Updates a load balancer.

If the request is valid, the service returns the Accepted (202) response code. To confirm the update, check that the load balancer provisioning status is ACTIVE. If the status is PENDING_UPDATE, use a GET operation to poll the load balancer object for changes.

This operation returns the updated load balancer object with the ACTIVE, PENDING_UPDATE, or ERROR provisioning status.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false).

description (Optional)

body

string

A human-readable description for the resource.

loadbalancer

body

object

A load balancer object.

loadbalancer_id

path

uuid

The ID of the load balancer to query.

name (Optional)

body

string

Human-readable name of the resource.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

vip_qos_policy_id (Optional)

body

uuid

The ID of the QoS Policy which will apply to the Virtual IP (VIP).

Request Example

{
    "loadbalancer": {
        "description": "Temporarily disabled load balancer",
        "admin_state_up": false,
        "name": "disabled_load_balancer",
        "vip_qos_policy_id": "ec4f78ca-8da8-4e99-8a1a-e3b94595a7a3",
        "tags": ["updated_tag"]
    }
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"loadbalancer": {"description": "Temporarily disabled load balancer", "admin_state_up": false, "name": "disabled_load_balancer", "vip_qos_policy_id": "ec4f78ca-8da8-4e99-8a1a-e3b94595a7a3", "tags": ["updated_tag"]}}' http://198.51.100.10:9876/v2/lbaas/loadbalancers/8b6fc468-07d5-4d8b-a0b9-695060e72c31

Response Parameters

Name

In

Type

Description

additional_vips (Optional)

body

array

A list of JSON objects defining “additional VIPs”. The format for these is {"subnet_id": <subnet_id>, "ip_address": <ip_address>}, where the subnet_id field is mandatory and the ip_address field is optional. Additional VIP subnets must all belong to the same network as the primary VIP.

New in version 2.26

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

created_at

body

string

The UTC date and timestamp when the resource was created.

description

body

string

A human-readable description for the resource.

flavor_id

body

uuid

The ID of the flavor.

id

body

uuid

The ID of the load balancer.

listeners

body

array

The associated listener IDs, if any.

loadbalancer

body

object

A load balancer object.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

pools

body

array

The associated pool IDs, if any.

project_id

body

string

The ID of the project owning this resource.

provider

body

string

Provider name for the load balancer.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

vip_address

body

string

The IP address of the Virtual IP (VIP).

vip_network_id

body

uuid

The ID of the network for the Virtual IP (VIP).

vip_port_id

body

uuid

The ID of the Virtual IP (VIP) port.

vip_qos_policy_id

body

uuid

The ID of the QoS Policy which will apply to the Virtual IP (VIP).

vip_subnet_id

body

uuid

The ID of the subnet for the Virtual IP (VIP).

vip_vnic_type

body

string

The VIP vNIC type used for the load balancer. One of normal or direct.

New in version 2.28

Response Example

{
    "loadbalancer": {
        "description": "Temporarily disabled load balancer",
        "admin_state_up": false,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "provisioning_status": "PENDING_UPDATE",
        "flavor_id": "",
        "vip_subnet_id": "d4af86e1-0051-488c-b7a0-527f97490c9a",
        "vip_address": "203.0.113.50",
        "vip_network_id": "d0d217df-3958-4fbf-a3c2-8dad2908c709",
        "vip_port_id": "b4ca07d1-a31e-43e2-891a-7d14f419f342",
        "additional_vips": [],
        "provider": "octavia",
        "created_at": "2017-02-28T00:41:44",
        "updated_at": "2017-02-28T00:43:30",
        "id": "8b6fc468-07d5-4d8b-a0b9-695060e72c31",
        "operating_status": "ONLINE",
        "name": "disabled_load_balancer",
        "vip_qos_policy_id": "ec4f78ca-8da8-4e99-8a1a-e3b94595a7a3",
        "tags": ["updated_tag"],
        "vip_vnic_type": "normal"
    }
}
DELETE
/v2/lbaas/loadbalancers/{loadbalancer_id}

Remove a Load Balancer

Removes a load balancer and its associated configuration from the project.

The optional parameter cascade when defined as true will delete all child objects of the load balancer.

The API immediately purges any and all configuration data, depending on the configuration settings. You cannot recover it.

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

cascade (Optional)

query

boolean

If true will delete all child objects of the load balancer.

loadbalancer_id

path

uuid

The ID of the load balancer to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/loadbalancers/4b9b652c-537a-44bf-bbe8-85a690625597

Response

There is no body content for the response of a successful DELETE request.

GET
/v2/lbaas/loadbalancers/{loadbalancer_id}/stats

Get Load Balancer statistics

Shows the current statistics for a load balancer.

This operation returns the statistics of a load balancer object identified by loadbalancer_id.

If you are not an administrative user and the load balancer object does not belong to your project, the service returns the HTTP Forbidden (403) response code.

This operation does not require a request body.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

loadbalancer_id

path

uuid

The ID of the load balancer to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/loadbalancers/4a13c573-623c-4d23-8a9c-581dc17ceb1f/stats

Response Parameters

Name

In

Type

Description

stats

body

object

A statistics object.

active_connections

body

integer

The currently active connections.

bytes_in

body

integer

The total bytes received.

bytes_out

body

integer

The total bytes sent.

request_errors

body

integer

The total requests that were unable to be fulfilled.

total_connections

body

integer

The total connections handled.

Response Example

{
    "stats": {
        "bytes_in": 131342840,
        "total_connections": 52378345,
        "active_connections": 97258,
        "bytes_out": 1549542372,
        "request_errors": 0
    }
}
GET
/v2/lbaas/loadbalancers/{loadbalancer_id}/status

Get the Load Balancer status tree

Shows the status tree for a load balancer.

This operation returns a status tree for a load balancer object, by load balancer ID.

provisioning_status is the status associated with lifecycle of the resource. See Provisioning Status Codes for descriptions of the status codes.

operating_status is the observed status of the resource. See Operating Status Codes for descriptions of the status codes.

If you are not an administrative user and the load balancer object does not belong to your project, the service returns the HTTP Forbidden (403) response code.

If the operation succeeds, the returned element is a status tree that contains the load balancer and all provisioning and operating statuses for its children.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

loadbalancer_id

path

uuid

The ID of the load balancer to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/loadbalancers/bda6f032-80d3-414a-b395-e79c374e3929/status

Response Parameters

Name

In

Type

Description

action

body

string

The action associated with the resource.

address

body

string

The IP address of the resource.

healthmonitor

body

object

The associated health monitor status object.

id

body

uuid

The ID of the resource.

l7policies

body

array

A list of L7 policy status objects.

l7rules

body

array

A list of L7 rule status objects.

listeners

body

array

A list of listener status objects.

loadbalancer

body

object

A load balancer status object.

members

body

array

A list of members status objects.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

pools

body

array

The list of pools status objects.

protocol_port

body

integer

The protocol port number for the resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

statuses

body

object

The status tree of a load balancer object contains all provisioning and operating statuses for its children.

type

body

string

The type associated with the resource.

Response Example

{
    "statuses": {
        "loadbalancer": {
            "name": "excellent_load_balancer",
            "provisioning_status": "ACTIVE",
            "listeners": [
                {
                    "name": "HTTP_listener",
                    "provisioning_status": "ACTIVE",
                    "pools": [
                        {
                            "name": "HTTP_pool",
                            "provisioning_status": "ACTIVE",
                            "healthmonitor": {
                                "type": "HTTP",
                                "id": "0b608787-ea2d-48c7-89a1-8b8c24fa3b17",
                                "name": "HTTP_healthmonitor",
                                "provisioning_status": "ACTIVE"
                            },
                            "members": [
                                {
                                    "name": "",
                                    "provisioning_status": "ACTIVE",
                                    "address": "192.0.2.20",
                                    "protocol_port": 80,
                                    "id": "3c6857f4-057a-405a-9134-bdeaa8796c8a",
                                    "operating_status": "ERROR"
                                },
                                {
                                    "name": "",
                                    "provisioning_status": "ACTIVE",
                                    "address": "192.0.2.21",
                                    "protocol_port": 80,
                                    "id": "f7495909-1706-4c91-83b4-641dab6962ac",
                                    "operating_status": "ONLINE"
                                }
                            ],
                            "id": "89a47f78-cf81-480b-ad74-bba4177eeb81",
                            "operating_status": "DEGRADED"
                        }
                    ],
                    "l7policies": [],
                    "id": "78febaf6-1e63-47c6-af5f-7b5e23fd7094",
                    "operating_status": "DEGRADED"
                },
                {
                    "name": "redirect_listener",
                    "provisioning_status": "ACTIVE",
                    "pools": [],
                    "l7policies": [
                        {
                            "action": "REDIRECT_TO_URL",
                            "rules": [
                                {
                                    "type": "PATH",
                                    "id": "27f3007a-a1cb-4e17-9696-0e578d617715",
                                    "provisioning_status": "ACTIVE"
                                }
                            ],
                            "id": "2e8f3139-0673-43f9-aae4-c7a9460e3233",
                            "name": "redirect_policy",
                            "provisioning_status": "ACTIVE"
                        }
                    ],
                    "id": "1341fbaf-ad4f-4cfe-a943-ad5e14e664cb",
                    "operating_status": "ONLINE"
                }
            ],
            "pools": [
                {
                    "name": "HTTP_pool",
                    "provisioning_status": "ACTIVE",
                    "healthmonitor": {
                        "type": "HTTP",
                        "id": "0b608787-ea2d-48c7-89a1-8b8c24fa3b17",
                        "name": "HTTP_healthmonitor",
                        "provisioning_status": "ACTIVE"
                    },
                    "members": [
                        {
                            "name": "",
                            "provisioning_status": "ACTIVE",
                            "address": "192.0.2.20",
                            "protocol_port": 80,
                            "id": "3c6857f4-057a-405a-9134-bdeaa8796c8a",
                            "operating_status": "ERROR"
                        },
                        {
                            "name": "",
                            "provisioning_status": "ACTIVE",
                            "address": "192.0.2.21",
                            "protocol_port": 80,
                            "id": "f7495909-1706-4c91-83b4-641dab6962ac",
                            "operating_status": "ONLINE"
                        }
                    ],
                    "id": "89a47f78-cf81-480b-ad74-bba4177eeb81",
                    "operating_status": "DEGRADED"
                },
                {
                    "name": "source_ip_pool",
                    "provisioning_status": "ACTIVE",
                    "healthmonitor": {},
                    "members": [],
                    "id": "8189d6a9-646e-4d23-b742-548dab991951",
                    "operating_status": "ONLINE"
                }
            ],
            "id": "84faceee-cb97-48d0-93df-9e41d40d4cb4",
            "operating_status": "DEGRADED"
        }
    }
}
PUT
/v2/lbaas/loadbalancers/{loadbalancer_id}/failover

Failover a load balancer

Performs a failover of a load balancer.

This operation is only available to users with load balancer administrative rights.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

loadbalancer_id

path

uuid

The ID of the load balancer to query.

Curl Example

curl -X PUT -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/loadbalancers/4a13c573-623c-4d23-8a9c-581dc17ceb1f/failover

Response

There is no body content for the response of a successful failover request.

Listeners

GET
/v2/lbaas/listeners

List 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 Filtering and column selection.

Administrative users can specify a project ID that is different than their own to list listeners for other projects.

The list might be empty.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

project_id (Optional)

query

string

The ID of the project to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/listeners?project_id=e3cd678b11784734bc366148aa37580e

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_cidrs

body

array

A list of IPv4, IPv6 or mix of both CIDRs.

New in version 2.12

alpn_protocols

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.20

client_authentication

body

string

The TLS client authentication mode. One of the options NONE, OPTIONAL or MANDATORY.

New in version 2.8

client_ca_tls_container_ref

body

string

The ref of the key manager service secret containing a PEM format client CA certificate bundle for TERMINATED_HTTPS listeners.

New in version 2.8

client_crl_container_ref

body

string

The URI of the key manager service secret containing a PEM format CA revocation list file for TERMINATED_HTTPS listeners.

New in version 2.8

connection_limit

body

integer

The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections or a default value defined by the provider driver.

created_at

body

string

The UTC date and timestamp when the resource was created.

default_pool_id

body

uuid

The ID of the pool used by the listener if no L7 policies match. The pool has some restrictions. See Protocol Combinations (Listener/Pool).

default_tls_container_ref

body

string

The URI of the key manager service secret containing a PKCS12 format certificate/key bundle for TERMINATED_HTTPS listeners. DEPRECATED: A secret container of type “certificate” containing the certificate and key for TERMINATED_HTTPS listeners.

description

body

string

A human-readable description for the resource.

hsts_include_subdomains

body

bool

Defines whether the includeSubDomains directive should be added to the Strict-Transport-Security HTTP response header.

New in version 2.27

hsts_max_age

body

integer

The value of the max_age directive for the Strict-Transport-Security HTTP response header.

New in version 2.27

hsts_preload

body

bool

Defines whether the preload directive should be added to the Strict-Transport-Security HTTP response header.

New in version 2.27

id

body

uuid

The ID of the listener.

insert_headers

body

object

A dictionary of optional headers to insert into the request before it is sent to the backend member. See Supported HTTP Header Insertions. Both keys and values are always specified as strings.

l7policies

body

array

A list of L7 policy IDs.

listener

body

object

A listener object.

loadbalancers

body

array

A list of load balancer IDs.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol

body

string

The protocol for the resource. One of HTTP, HTTPS, SCTP, PROMETHEUS, TCP, TERMINATED_HTTPS, or UDP.

protocol_port

body

integer

The protocol port number for the resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

sni_container_refs

body

array

A list of URIs to the key manager service secrets containing PKCS12 format certificate/key bundles for TERMINATED_HTTPS listeners. (DEPRECATED) Secret containers of type “certificate” containing the certificates and keys for TERMINATED_HTTPS listeners.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout_client_data

body

integer

Frontend client inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_member_connect

body

integer

Backend member connection timeout in milliseconds. Default: 5000.

New in version 2.1

timeout_member_data

body

integer

Backend member inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_tcp_inspect

body

integer

Time, in milliseconds, to wait for additional TCP packets for content inspection. Default: 0.

New in version 2.1

tls_ciphers

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_versions

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "listeners": [
        {
            "description": "A great TLS listener",
            "admin_state_up": true,
            "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",
            "timeout_client_data": 50000,
            "timeout_member_connect": 5000,
            "timeout_member_data": 50000,
            "timeout_tcp_inspect": 0,
            "tags": [
                "test_tag"
            ],
            "client_ca_tls_container_ref": "http://198.51.100.10:9311/v1/containers/35649991-49f3-4625-81ce-2465fe8932e5",
            "client_authentication": "NONE",
            "client_crl_container_ref": "http://198.51.100.10:9311/v1/containers/e222b065-b93b-4e2a-9a02-804b7a118c3c",
            "allowed_cidrs": [
                "192.0.2.0/24",
                "198.51.100.0/24"
            ],
            "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
            "tls_versions": [
                "TLSv1.2",
                "TLSv1.3"
            ],
            "alpn_protocols": [
                "http/1.1",
                "http/1.0"
            ],
            "hsts_include_subdomains": true,
            "hsts_max_age": 31536000,
            "hsts_preload": true
        }
    ]
}
POST
/v2/lbaas/listeners

Create Listener

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 provisioning status is ACTIVE, PENDING_CREATE, or ERROR.

If the status is PENDING_CREATE, issue GET /v2/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 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.

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

503 - Service Unavailable

The service cannot handle the request right now.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

allowed_cidrs (Optional)

body

array

A list of IPv4, IPv6 or mix of both CIDRs. The default is all allowed. When a list of CIDRs is provided, the default switches to deny all.

New in version 2.12

alpn_protocols (Optional)

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.20

client_authentication (Optional)

body

string

The TLS client authentication mode. One of the options NONE, OPTIONAL or MANDATORY.

New in version 2.8

client_ca_tls_container_ref (Optional)

body

string

The ref of the key manager service secret containing a PEM format client CA certificate bundle for TERMINATED_HTTPS listeners.

New in version 2.8

client_crl_container_ref (Optional)

body

string

The URI of the key manager service secret containing a PEM format CA revocation list file for TERMINATED_HTTPS listeners.

New in version 2.8

connection_limit (Optional)

body

integer

The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections or a default value defined by the provider driver.

default_pool (Optional)

body

object

A pool object.

default_pool_id (Optional)

body

uuid

The ID of the pool used by the listener if no L7 policies match. The pool has some restrictions. See Protocol Combinations (Listener/Pool).

default_tls_container_ref (Optional)

body

string

The URI of the key manager service secret containing a PKCS12 format certificate/key bundle for TERMINATED_HTTPS listeners. DEPRECATED: A secret container of type “certificate” containing the certificate and key for TERMINATED_HTTPS listeners.

description (Optional)

body

string

A human-readable description for the resource.

hsts_include_subdomains (Optional)

body

bool

Defines whether the includeSubDomains directive should be added to the Strict-Transport-Security HTTP response header. This requires setting the hsts_max_age option as well in order to become effective.

New in version 2.27

hsts_max_age (Optional)

body

integer

The value of the max_age directive for the Strict-Transport-Security HTTP response header. Setting this enables HTTP Strict Transport Security (HSTS) for the TLS-terminated listener.

New in version 2.27

hsts_preload (Optional)

body

bool

Defines whether the preload directive should be added to the Strict-Transport-Security HTTP response header. This requires setting the hsts_max_age option as well in order to become effective.

New in version 2.27

insert_headers (Optional)

body

object

A dictionary of optional headers to insert into the request before it is sent to the backend member. See Supported HTTP Header Insertions. Both keys and values are always specified as strings.

l7policies (Optional)

body

array

A list of L7 policy objects.

listeners

body

object

A listener object.

loadbalancer_id

body

uuid

The ID of the load balancer.

name (Optional)

body

string

Human-readable name of the resource.

project_id (Optional)

body

string

The ID of the project owning this resource. (deprecated)

protocol

body

string

The protocol for the resource. One of HTTP, HTTPS, SCTP, PROMETHEUS, TCP, TERMINATED_HTTPS, or UDP.

protocol_port

body

integer

The protocol port number for the resource.

sni_container_refs (Optional)

body

array

A list of URIs to the key manager service secrets containing PKCS12 format certificate/key bundles for TERMINATED_HTTPS listeners. (DEPRECATED) Secret containers of type “certificate” containing the certificates and keys for TERMINATED_HTTPS listeners.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout_client_data (Optional)

body

integer

Frontend client inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_member_connect (Optional)

body

integer

Backend member connection timeout in milliseconds. Default: 5000.

New in version 2.1

timeout_member_data (Optional)

body

integer

Backend member inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_tcp_inspect (Optional)

body

integer

Time, in milliseconds, to wait for additional TCP packets for content inspection. Default: 0.

New in version 2.1

tls_ciphers (Optional)

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_versions (Optional)

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

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

string

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

string

When “true” a X-Forwarded-Port header is inserted into the request to the backend member that specifies the listener port.

X-Forwarded-Proto

string

When “true” a X-Forwarded-Proto header is inserted into the request to the backend member. HTTP for the HTTP listener protocol type, HTTPS for the TERMINATED_HTTPS listener protocol type. New in version 2.1

X-SSL-Client-Verify

string

When “true” a X-SSL-Client-Verify header is inserted into the request to the backend member that contains 0 if the client authentication was successful, or an result error number greater than 0 that align to the openssl veryify error codes.

X-SSL-Client-Has-Cert

string

When “true” a X-SSL-Client-Has-Cert header is inserted into the request to the backend member that is ‘’true’’ if a client authentication certificate was presented, and ‘’false’’ if not. Does not indicate validity.

X-SSL-Client-DN

string

When “true” a X-SSL-Client-DN header is inserted into the request to the backend member that contains the full Distinguished Name of the certificate presented by the client.

X-SSL-Client-CN

string

When “true” a X-SSL-Client-CN header is inserted into the request to the backend member that contains the Common Name from the full Distinguished Name of the certificate presented by the client.

X-SSL-Issuer

string

When “true” a X-SSL-Issuer header is inserted into the request to the backend member that contains the full Distinguished Name of the client certificate issuer.

X-SSL-Client-SHA1

string

When “true” a X-SSL-Client-SHA1 header is inserted into the request to the backend member that contains the SHA-1 fingerprint of the certificate presented by the client in hex string format.

X-SSL-Client-Not-Before

string

When “true” a X-SSL-Client-Not-Before header is inserted into the request to the backend member that contains the start date presented by the client as a formatted string YYMMDDhhmmss[Z].

X-SSL-Client-Not-After

string

When “true” a X-SSL-Client-Not-After header is inserted into the request to the backend member that contains the end date presented by the client as a formatted string YYMMDDhhmmss[Z].

Request Example

{
    "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"
        ],
        "timeout_client_data": 50000,
        "timeout_member_connect": 5000,
        "timeout_member_data": 50000,
        "timeout_tcp_inspect": 0,
        "tags": ["test_tag"],
        "client_ca_tls_container_ref": "http://198.51.100.10:9311/v1/containers/35649991-49f3-4625-81ce-2465fe8932e5",
        "client_authentication": "MANDATORY",
        "client_crl_container_ref": "http://198.51.100.10:9311/v1/containers/e222b065-b93b-4e2a-9a02-804b7a118c3c",
        "allowed_cidrs": [
            "192.0.2.0/24",
            "198.51.100.0/24"
        ],
        "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
        "tls_versions": ["TLSv1.2", "TLSv1.3"],
        "alpn_protocols": ["http/1.1", "http/1.0"],
        "hsts_include_subdomains": true,
        "hsts_max_age": 31536000,
        "hsts_preload": true
    }
}

Curl Example

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"], "timeout_client_data": 50000, "timeout_member_connect": 5000, "timeout_member_data": 50000, "timeout_tcp_inspect": 0, "tags": ["test_tag"], "client_ca_tls_container_ref": "http://198.51.100.10:9311/v1/containers/35649991-49f3-4625-81ce-2465fe8932e5", "client_authentication": "MANDATORY", "client_crl_container_ref": "http://198.51.100.10:9311/v1/containers/e222b065-b93b-4e2a-9a02-804b7a118c3c", "allowed_cidrs": ["192.0.2.0/24", "198.51.100.0/24"], "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256", "tls_versions": ["TLSv1.2", "TLSv1.3"], "alpn_protocols": ["http/1.1", "http/1.0"], "hsts_include_subdomains": true, "hsts_max_age": 31536000, "hsts_preload": true}}' http://198.51.100.10:9876/v2/lbaas/listeners

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_cidrs

body

array

A list of IPv4, IPv6 or mix of both CIDRs.

New in version 2.12

alpn_protocols

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.20

client_authentication

body

string

The TLS client authentication mode. One of the options NONE, OPTIONAL or MANDATORY.

New in version 2.8

client_ca_tls_container_ref

body

string

The ref of the key manager service secret containing a PEM format client CA certificate bundle for TERMINATED_HTTPS listeners.

New in version 2.8

client_crl_container_ref

body

string

The URI of the key manager service secret containing a PEM format CA revocation list file for TERMINATED_HTTPS listeners.

New in version 2.8

connection_limit

body

integer

The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections or a default value defined by the provider driver.

created_at

body

string

The UTC date and timestamp when the resource was created.

default_pool_id

body

uuid

The ID of the pool used by the listener if no L7 policies match. The pool has some restrictions. See Protocol Combinations (Listener/Pool).

default_tls_container_ref

body

string

The URI of the key manager service secret containing a PKCS12 format certificate/key bundle for TERMINATED_HTTPS listeners. DEPRECATED: A secret container of type “certificate” containing the certificate and key for TERMINATED_HTTPS listeners.

description

body

string

A human-readable description for the resource.

hsts_include_subdomains

body

bool

Defines whether the includeSubDomains directive should be added to the Strict-Transport-Security HTTP response header.

New in version 2.27

hsts_max_age

body

integer

The value of the max_age directive for the Strict-Transport-Security HTTP response header.

New in version 2.27

hsts_preload

body

bool

Defines whether the preload directive should be added to the Strict-Transport-Security HTTP response header.

New in version 2.27

id

body

uuid

The ID of the listener.

insert_headers

body

object

A dictionary of optional headers to insert into the request before it is sent to the backend member. See Supported HTTP Header Insertions. Both keys and values are always specified as strings.

l7policies

body

array

A list of L7 policy IDs.

listener

body

object

A listener object.

loadbalancers

body

array

A list of load balancer IDs.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol

body

string

The protocol for the resource. One of HTTP, HTTPS, SCTP, PROMETHEUS, TCP, TERMINATED_HTTPS, or UDP.

protocol_port

body

integer

The protocol port number for the resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

sni_container_refs

body

array

A list of URIs to the key manager service secrets containing PKCS12 format certificate/key bundles for TERMINATED_HTTPS listeners. (DEPRECATED) Secret containers of type “certificate” containing the certificates and keys for TERMINATED_HTTPS listeners.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout_client_data

body

integer

Frontend client inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_member_connect

body

integer

Backend member connection timeout in milliseconds. Default: 5000.

New in version 2.1

timeout_member_data

body

integer

Backend member inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_tcp_inspect

body

integer

Time, in milliseconds, to wait for additional TCP packets for content inspection. Default: 0.

New in version 2.1

tls_ciphers

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_versions

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "listener": {
        "description": "A great TLS listener",
        "admin_state_up": true,
        "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",
        "timeout_client_data": 50000,
        "timeout_member_connect": 5000,
        "timeout_member_data": 50000,
        "timeout_tcp_inspect": 0,
        "tags": ["test_tag"],
        "client_ca_tls_container_ref": "http://198.51.100.10:9311/v1/containers/35649991-49f3-4625-81ce-2465fe8932e5",
        "client_authentication": "MANDATORY",
        "client_crl_container_ref": "http://198.51.100.10:9311/v1/containers/e222b065-b93b-4e2a-9a02-804b7a118c3c",
        "allowed_cidrs": [
            "192.0.2.0/24",
            "198.51.100.0/24"
        ],
        "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
        "tls_versions": [
            "TLSv1.2",
            "TLSv1.3"
        ],
        "alpn_protocols": [
            "http/1.1",
            "http/1.0"
        ],
        "hsts_include_subdomains": true,
        "hsts_max_age": 31536000,
        "hsts_preload": true
    }
}
GET
/v2/lbaas/listeners/{listener_id}

Show Listener details

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.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

listener_id

path

uuid

The ID of the listener to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/listeners/023f2e34-7806-443b-bfae-16c324569a3d

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_cidrs

body

array

A list of IPv4, IPv6 or mix of both CIDRs.

New in version 2.12

alpn_protocols

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.20

client_authentication

body

string

The TLS client authentication mode. One of the options NONE, OPTIONAL or MANDATORY.

New in version 2.8

client_ca_tls_container_ref

body

string

The ref of the key manager service secret containing a PEM format client CA certificate bundle for TERMINATED_HTTPS listeners.

New in version 2.8

client_crl_container_ref

body

string

The URI of the key manager service secret containing a PEM format CA revocation list file for TERMINATED_HTTPS listeners.

New in version 2.8

connection_limit

body

integer

The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections or a default value defined by the provider driver.

created_at

body

string

The UTC date and timestamp when the resource was created.

default_pool_id

body

uuid

The ID of the pool used by the listener if no L7 policies match. The pool has some restrictions. See Protocol Combinations (Listener/Pool).

default_tls_container_ref

body

string

The URI of the key manager service secret containing a PKCS12 format certificate/key bundle for TERMINATED_HTTPS listeners. DEPRECATED: A secret container of type “certificate” containing the certificate and key for TERMINATED_HTTPS listeners.

description

body

string

A human-readable description for the resource.

hsts_include_subdomains

body

bool

Defines whether the includeSubDomains directive should be added to the Strict-Transport-Security HTTP response header.

New in version 2.27

hsts_max_age

body

integer

The value of the max_age directive for the Strict-Transport-Security HTTP response header.

New in version 2.27

hsts_preload

body

bool

Defines whether the preload directive should be added to the Strict-Transport-Security HTTP response header.

New in version 2.27

id

body

uuid

The ID of the listener.

insert_headers

body

object

A dictionary of optional headers to insert into the request before it is sent to the backend member. See Supported HTTP Header Insertions. Both keys and values are always specified as strings.

l7policies

body

array

A list of L7 policy IDs.

listener

body

object

A listener object.

loadbalancers

body

array

A list of load balancer IDs.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol

body

string

The protocol for the resource. One of HTTP, HTTPS, SCTP, PROMETHEUS, TCP, TERMINATED_HTTPS, or UDP.

protocol_port

body

integer

The protocol port number for the resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

sni_container_refs

body

array

A list of URIs to the key manager service secrets containing PKCS12 format certificate/key bundles for TERMINATED_HTTPS listeners. (DEPRECATED) Secret containers of type “certificate” containing the certificates and keys for TERMINATED_HTTPS listeners.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout_client_data

body

integer

Frontend client inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_member_connect

body

integer

Backend member connection timeout in milliseconds. Default: 5000.

New in version 2.1

timeout_member_data

body

integer

Backend member inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_tcp_inspect

body

integer

Time, in milliseconds, to wait for additional TCP packets for content inspection. Default: 0.

New in version 2.1

tls_ciphers

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_versions

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "listener": {
        "description": "A great TLS listener",
        "admin_state_up": true,
        "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",
        "timeout_client_data": 50000,
        "timeout_member_connect": 5000,
        "timeout_member_data": 50000,
        "timeout_tcp_inspect": 0,
        "tags": ["test_tag"],
        "client_ca_tls_container_ref": "http://198.51.100.10:9311/v1/containers/35649991-49f3-4625-81ce-2465fe8932e5",
        "client_authentication": "MANDATORY",
        "client_crl_container_ref": "http://198.51.100.10:9311/v1/containers/e222b065-b93b-4e2a-9a02-804b7a118c3c",
        "allowed_cidrs": [
            "192.0.2.0/24",
            "198.51.100.0/24"
        ],
        "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
        "tls_versions": [
            "TLSv1.2",
            "TLSv1.3"
        ],
        "alpn_protocols": [
            "http/1.1",
            "http/1.0"
        ],
        "hsts_include_subdomains": true,
        "hsts_max_age": 31536000,
        "hsts_preload": true
    }
}
PUT
/v2/lbaas/listeners/{listener_id}

Update a Listener

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.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

allowed_cidrs (Optional)

body

array

A list of IPv4, IPv6 or mix of both CIDRs. The default is all allowed. When a list of CIDRs is provided, the default switches to deny all.

New in version 2.12

alpn_protocols (Optional)

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.20

client_authentication (Optional)

body

string

The TLS client authentication mode. One of the options NONE, OPTIONAL or MANDATORY.

New in version 2.8

client_ca_tls_container_ref (Optional)

body

string

The ref of the key manager service secret containing a PEM format client CA certificate bundle for TERMINATED_HTTPS listeners.

New in version 2.8

client_crl_container_ref (Optional)

body

string

The URI of the key manager service secret containing a PEM format CA revocation list file for TERMINATED_HTTPS listeners.

New in version 2.8

connection_limit (Optional)

body

integer

The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections or a default value defined by the provider driver.

default_pool_id (Optional)

body

uuid

The ID of the pool used by the listener if no L7 policies match. The pool has some restrictions. See Protocol Combinations (Listener/Pool).

default_tls_container_ref (Optional)

body

string

The URI of the key manager service secret containing a PKCS12 format certificate/key bundle for TERMINATED_HTTPS listeners. DEPRECATED: A secret container of type “certificate” containing the certificate and key for TERMINATED_HTTPS listeners.

description (Optional)

body

string

A human-readable description for the resource.

hsts_include_subdomains (Optional)

body

bool

Defines whether the includeSubDomains directive should be added to the Strict-Transport-Security HTTP response header. This requires setting the hsts_max_age option as well in order to become effective.

New in version 2.27

hsts_max_age (Optional)

body

integer

The value of the max_age directive for the Strict-Transport-Security HTTP response header. Setting this enables HTTP Strict Transport Security (HSTS) for the TLS-terminated listener.

New in version 2.27

hsts_preload (Optional)

body

bool

Defines whether the preload directive should be added to the Strict-Transport-Security HTTP response header. This requires setting the hsts_max_age option as well in order to become effective.

New in version 2.27

insert_headers (Optional)

body

object

A dictionary of optional headers to insert into the request before it is sent to the backend member. See Supported HTTP Header Insertions. Both keys and values are always specified as strings.

listener_id

path

uuid

The ID of the listener to query.

name (Optional)

body

string

Human-readable name of the resource.

sni_container_refs (Optional)

body

array

A list of URIs to the key manager service secrets containing PKCS12 format certificate/key bundles for TERMINATED_HTTPS listeners. (DEPRECATED) Secret containers of type “certificate” containing the certificates and keys for TERMINATED_HTTPS listeners.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout_client_data (Optional)

body

integer

Frontend client inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_member_connect (Optional)

body

integer

Backend member connection timeout in milliseconds. Default: 5000.

New in version 2.1

timeout_member_data (Optional)

body

integer

Backend member inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_tcp_inspect (Optional)

body

integer

Time, in milliseconds, to wait for additional TCP packets for content inspection. Default: 0.

New in version 2.1

tls_ciphers (Optional)

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_versions (Optional)

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

Request Example

{
    "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"
        ],
        "timeout_client_data": 100000,
        "timeout_member_connect": 1000,
        "timeout_member_data": 100000,
        "timeout_tcp_inspect": 5,
        "tags": [
            "updated_tag"
        ],
        "client_ca_tls_container_ref": null,
        "allowed_cidrs": [
            "192.0.2.0/24",
            "198.51.100.0/24"
        ],
        "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
        "tls_versions": [
            "TLSv1.2",
            "TLSv1.3"
        ],
        "alpn_protocols": [
            "http/1.1",
            "http/1.0"
        ],
        "hsts_include_subdomains": true,
        "hsts_max_age": 31536000,
        "hsts_preload": true
    }
}

Curl Example

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"], "timeout_client_data": 100000, "timeout_member_connect": 1000, "timeout_member_data": 100000, "timeout_tcp_inspect": 5, "tags": ["updated_tag"], "client_ca_tls_container_ref": null, "allowed_cidrs": ["192.0.2.0/24", "198.51.100.0/24"], "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256", "tls_versions": ["TLSv1.2", "TLSv1.3"], "alpn_protocols": ["http/1.1", "http/1.0"], "hsts_include_subdomains": true, "hsts_max_age": 31536000, "hsts_preload": true}}' http://198.51.100.10:9876/v2/lbaas/listeners/023f2e34-7806-443b-bfae-16c324569a3d

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

allowed_cidrs

body

array

A list of IPv4, IPv6 or mix of both CIDRs.

New in version 2.12

alpn_protocols

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.20

client_authentication

body

string

The TLS client authentication mode. One of the options NONE, OPTIONAL or MANDATORY.

New in version 2.8

client_ca_tls_container_ref

body

string

The ref of the key manager service secret containing a PEM format client CA certificate bundle for TERMINATED_HTTPS listeners.

New in version 2.8

client_crl_container_ref

body

string

The URI of the key manager service secret containing a PEM format CA revocation list file for TERMINATED_HTTPS listeners.

New in version 2.8

connection_limit

body

integer

The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections or a default value defined by the provider driver.

created_at

body

string

The UTC date and timestamp when the resource was created.

default_pool_id

body

uuid

The ID of the pool used by the listener if no L7 policies match. The pool has some restrictions. See Protocol Combinations (Listener/Pool).

default_tls_container_ref

body

string

The URI of the key manager service secret containing a PKCS12 format certificate/key bundle for TERMINATED_HTTPS listeners. DEPRECATED: A secret container of type “certificate” containing the certificate and key for TERMINATED_HTTPS listeners.

description

body

string

A human-readable description for the resource.

hsts_include_subdomains

body

bool

Defines whether the includeSubDomains directive should be added to the Strict-Transport-Security HTTP response header.

New in version 2.27

hsts_max_age

body

integer

The value of the max_age directive for the Strict-Transport-Security HTTP response header.

New in version 2.27

hsts_preload

body

bool

Defines whether the preload directive should be added to the Strict-Transport-Security HTTP response header.

New in version 2.27

id

body

uuid

The ID of the listener.

insert_headers

body

object

A dictionary of optional headers to insert into the request before it is sent to the backend member. See Supported HTTP Header Insertions. Both keys and values are always specified as strings.

l7policies

body

array

A list of L7 policy IDs.

listener

body

object

A listener object.

loadbalancers

body

array

A list of load balancer IDs.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol

body

string

The protocol for the resource. One of HTTP, HTTPS, SCTP, PROMETHEUS, TCP, TERMINATED_HTTPS, or UDP.

protocol_port

body

integer

The protocol port number for the resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

sni_container_refs

body

array

A list of URIs to the key manager service secrets containing PKCS12 format certificate/key bundles for TERMINATED_HTTPS listeners. (DEPRECATED) Secret containers of type “certificate” containing the certificates and keys for TERMINATED_HTTPS listeners.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout_client_data

body

integer

Frontend client inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_member_connect

body

integer

Backend member connection timeout in milliseconds. Default: 5000.

New in version 2.1

timeout_member_data

body

integer

Backend member inactivity timeout in milliseconds. Default: 50000.

New in version 2.1

timeout_tcp_inspect

body

integer

Time, in milliseconds, to wait for additional TCP packets for content inspection. Default: 0.

New in version 2.1

tls_ciphers

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_versions

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "listener": {
        "description": "An updated great TLS listener",
        "admin_state_up": true,
        "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",
        "timeout_client_data": 100000,
        "timeout_member_connect": 1000,
        "timeout_member_data": 100000,
        "timeout_tcp_inspect": 5,
        "tags": ["updated_tag"],
        "client_ca_tls_container_ref": null,
        "client_authentication": "NONE",
        "client_crl_container_ref": null,
        "allowed_cidrs": [
            "192.0.2.0/24",
            "198.51.100.0/24"
        ],
        "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
        "tls_versions": [
            "TLSv1.2",
            "TLSv1.3"
        ],
        "alpn_protocols": [
            "http/1.1",
            "http/1.0"
        ],
        "hsts_include_subdomains": true,
        "hsts_max_age": 31536000,
        "hsts_preload": true
    }
}
DELETE
/v2/lbaas/listeners/{listener_id}

Remove a Listener

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.

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

listener_id

path

uuid

The ID of the listener to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/listeners/023f2e34-7806-443b-bfae-16c324569a3d

Response

There is no body content for the response of a successful DELETE request.

GET
/v2/lbaas/listeners/{listener_id}/stats

Get Listener statistics

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.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

listener_id

path

uuid

The ID of the listener to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/listeners/023f2e34-7806-443b-bfae-16c324569a3d/stats

Response Parameters

Name

In

Type

Description

stats

body

object

A statistics object.

active_connections

body

integer

The currently active connections.

bytes_in

body

integer

The total bytes received.

bytes_out

body

integer

The total bytes sent.

request_errors

body

integer

The total requests that were unable to be fulfilled.

total_connections

body

integer

The total connections handled.

Response Example

{
    "stats": {
        "bytes_in": 65671420,
        "total_connections": 26189172,
        "active_connections": 48629,
        "bytes_out": 774771186,
        "request_errors": 0
    }
}

Pools

GET
/v2/lbaas/pools

List 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 Filtering and column selection.

Administrative users can specify a project ID that is different than their own to list pools for other projects.

The list might be empty.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

project_id (Optional)

query

string

The ID of the project to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/pools?project_id=e3cd678b11784734bc366148aa37580e

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

alpn_protocols

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.24

ca_tls_container_ref

body

string

The reference of the key manager service secret containing a PEM format CA certificate bundle for tls_enabled pools.

New in version 2.8

created_at

body

string

The UTC date and timestamp when the resource was created.

crl_container_ref

body

string

The reference of the key manager service secret containing a PEM format CA revocation list file for tls_enabled pools.

description

body

string

A human-readable description for the resource.

healthmonitor_id

body

uuid

The associated health monitor ID.

id

body

uuid

The ID of the pool.

lb_algorithm

body

string

The load balancing algorithm for the pool. One of LEAST_CONNECTIONS, ROUND_ROBIN, SOURCE_IP, or SOURCE_IP_PORT.

listeners

body

array

A list of listener IDs.

loadbalancers

body

array

A list of load balancer IDs.

members

body

array

A list of member IDs.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol

body

string

The protocol for the resource. One of HTTP, HTTPS, PROXY, PROXYV2, SCTP, TCP, or UDP.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

session_persistence

body

object

A JSON object specifying the session persistence for the pool or null for no session persistence. See Pool Session Persistence. Default is null.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

tls_ciphers

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_container_ref

body

string

The reference to the key manager service secret containing a PKCS12 format certificate/key bundle for tls_enabled pools for TLS client authentication to the member servers.

New in version 2.8

tls_enabled

body

boolean

When true connections to backend member servers will use TLS encryption. Default is false.

New in version 2.8

tls_versions

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "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",
            "tags": ["test_tag"],
            "tls_container_ref": "http://198.51.100.10:9311/v1/containers/4073846f-1d5e-42e1-a4cf-a7046419d0e6",
            "ca_tls_container_ref": "http://198.51.100.10:9311/v1/containers/5f0d5540-fae6-4646-85d6-8a84883807fb",
            "crl_container_ref": "http://198.51.100.10:9311/v1/containers/6faf0a01-6892-454c-aaac-650282820c0b",
            "tls_enabled": true,
            "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
            "tls_versions": ["TLSv1.2", "TLSv1.3"],
            "alpn_protocols": ["http/1.1", "http/1.0"]
        }
    ]
}
POST
/v2/lbaas/pools

Create Pool

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 provisioning status is ACTIVE, PENDING_CREATE, or ERROR.

If the status is PENDING_CREATE, issue GET /v2/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, PROXYV2, SCTP, TCP, or UDP.

  • lb_algorithm The load-balancer algorithm, such as ROUND_ROBIN, LEAST_CONNECTIONS, SOURCE_IP and SOURCE_IP_PORT, 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.

SOURCE_IP_PORT algorithm is available from version 2.13.

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

503 - Service Unavailable

The service cannot handle the request right now.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

alpn_protocols (Optional)

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.24

ca_tls_container_ref (Optional)

body

string

The reference of the key manager service secret containing a PEM format CA certificate bundle for tls_enabled pools.

New in version 2.8

crl_container_ref (Optional)

body

string

The reference of the key manager service secret containing a PEM format CA revocation list file for tls_enabled pools.

description (Optional)

body

string

A human-readable description for the resource.

lb_algorithm

body

string

The load balancing algorithm for the pool. One of LEAST_CONNECTIONS, ROUND_ROBIN, SOURCE_IP, or SOURCE_IP_PORT.

listener_id (Optional)

body

uuid

The ID of the listener for the pool. Either listener_id or loadbalancer_id must be specified. The listener has some restrictions, See Protocol Combinations (Listener/Pool).

loadbalancer_id (Optional)

body

uuid

The ID of the load balancer for the pool. Either listener_id or loadbalancer_id must be specified.

name (Optional)

body

string

Human-readable name of the resource.

project_id (Optional)

body

string

The ID of the project owning this resource. (deprecated)

protocol

body

string

The protocol for the resource. One of HTTP, HTTPS, PROXY, PROXYV2, SCTP, TCP, or UDP.

session_persistence (Optional)

body

object

A JSON object specifying the session persistence for the pool or null for no session persistence. See Pool Session Persistence. Default is null.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

tls_enabled (Optional)

body

boolean

When true connections to backend member servers will use TLS encryption. Default is false.

New in version 2.8

tls_ciphers (Optional)

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_container_ref (Optional)

body

string

The reference to the key manager service secret containing a PKCS12 format certificate/key bundle for tls_enabled pools for TLS client authentication to the member servers.

New in version 2.8

tls_versions (Optional)

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

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

Name

In

Type

Description

type

body

string

Session persistence type for the pool. One of APP_COOKIE, HTTP_COOKIE, or SOURCE_IP.

cookie_name (Optional)

body

string

The name of the cookie to use for session persistence. Only applicable to the APP_COOKIE session persistence type where it is required.

persistence_timeout (Optional)

body

integer

The timeout, in seconds, after which a SCTP or UDP flow may be rescheduled to a different member. Currently only applies to SCTP or UDP pools with session persistence of SOURCE_IP. Default is 360.

New in version 2.2

persistence_granularity (Optional)

body

string

The netmask used to determine SCTP or UDP session persistence. Currently only valid for SCTP or UDP pools with session persistence of SOURCE_IP. Default netmask is 255.255.255.255, meaning per client full IP.

New in version 2.2

Pool Session Persistence Object Example
{"cookie_name": "my_app_cookie", "type": "APP_COOKIE"}

Request Example

{
    "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",
        "tags": ["test_tag"],
        "tls_container_ref": "http://198.51.100.10:9311/v1/containers/4073846f-1d5e-42e1-a4cf-a7046419d0e6",
        "ca_tls_container_ref": "http://198.51.100.10:9311/v1/containers/5f0d5540-fae6-4646-85d6-8a84883807fb",
        "crl_container_ref": "http://198.51.100.10:9311/v1/containers/6faf0a01-6892-454c-aaac-650282820c0b",
        "tls_enabled": true,
        "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
        "tls_versions": ["TLSv1.2", "TLSv1.3"],
        "alpn_protocols": ["http/1.1", "http/1.0"]
    }
}

Curl Example

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","tags":["test_tag"],"tls_container_ref":"http://198.51.100.10:9311/v1/containers/4073846f-1d5e-42e1-a4cf-a7046419d0e6","ca_tls_container_ref":"http://198.51.100.10:9311/v1/containers/5f0d5540-fae6-4646-85d6-8a84883807fb","crl_container_ref":"http://198.51.100.10:9311/v1/containers/6faf0a01-6892-454c-aaac-650282820c0b","tls_enabled":true,"tls_ciphers":"ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256", "tls_versions": ["TLSv1.2", "TLSv1.3"], "alpn_protocols": ["http/1.1", "http/1.0"]}}' http://198.51.100.10:9876/v2/lbaas/pools

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

alpn_protocols

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.24

ca_tls_container_ref

body

string

The reference of the key manager service secret containing a PEM format CA certificate bundle for tls_enabled pools.

New in version 2.8

created_at

body

string

The UTC date and timestamp when the resource was created.

crl_container_ref

body

string

The reference of the key manager service secret containing a PEM format CA revocation list file for tls_enabled pools.

description

body

string

A human-readable description for the resource.

healthmonitor_id

body

uuid

The associated health monitor ID.

id

body

uuid

The ID of the pool.

lb_algorithm

body

string

The load balancing algorithm for the pool. One of LEAST_CONNECTIONS, ROUND_ROBIN, SOURCE_IP, or SOURCE_IP_PORT.

listeners

body

array

A list of listener IDs.

loadbalancers

body

array

A list of load balancer IDs.

members

body

array

A list of member IDs.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol

body

string

The protocol for the resource. One of HTTP, HTTPS, PROXY, PROXYV2, SCTP, TCP, or UDP.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

session_persistence

body

object

A JSON object specifying the session persistence for the pool or null for no session persistence. See Pool Session Persistence. Default is null.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

tls_enabled

body

boolean

When true connections to backend member servers will use TLS encryption. Default is false.

New in version 2.8

tls_ciphers

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_container_ref

body

string

The reference to the key manager service secret containing a PKCS12 format certificate/key bundle for tls_enabled pools for TLS client authentication to the member servers.

New in version 2.8

tls_versions

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "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",
        "tags": ["test_tag"],
        "tls_container_ref": "http://198.51.100.10:9311/v1/containers/4073846f-1d5e-42e1-a4cf-a7046419d0e6",
        "ca_tls_container_ref": "http://198.51.100.10:9311/v1/containers/5f0d5540-fae6-4646-85d6-8a84883807fb",
        "crl_container_ref": "http://198.51.100.10:9311/v1/containers/6faf0a01-6892-454c-aaac-650282820c0b",
        "tls_enabled": true,
        "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
        "tls_versions": ["TLSv1.2", "TLSv1.3"],
        "alpn_protocols": ["http/1.1", "http/1.0"]
    }
}
GET
/v2/lbaas/pools/{pool_id}

Show Pool details

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.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

pool_id

path

uuid

The ID of the pool to query.

Curl Example

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

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

alpn_protocols

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.24

ca_tls_container_ref

body

string

The reference of the key manager service secret containing a PEM format CA certificate bundle for tls_enabled pools.

New in version 2.8

created_at

body

string

The UTC date and timestamp when the resource was created.

crl_container_ref

body

string

The reference of the key manager service secret containing a PEM format CA revocation list file for tls_enabled pools.

description

body

string

A human-readable description for the resource.

healthmonitor_id

body

uuid

The associated health monitor ID.

id

body

uuid

The ID of the pool.

lb_algorithm

body

string

The load balancing algorithm for the pool. One of LEAST_CONNECTIONS, ROUND_ROBIN, SOURCE_IP, or SOURCE_IP_PORT.

listeners

body

array

A list of listener IDs.

loadbalancers

body

array

A list of load balancer IDs.

members

body

array

A list of member IDs.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol

body

string

The protocol for the resource. One of HTTP, HTTPS, PROXY, PROXYV2, SCTP, TCP, or UDP.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

session_persistence

body

object

A JSON object specifying the session persistence for the pool or null for no session persistence. See Pool Session Persistence. Default is null.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

tls_enabled

body

boolean

When true connections to backend member servers will use TLS encryption. Default is false.

New in version 2.8

tls_ciphers

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_container_ref

body

string

The reference to the key manager service secret containing a PKCS12 format certificate/key bundle for tls_enabled pools for TLS client authentication to the member servers.

New in version 2.8

tls_versions

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "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",
        "tags": ["test_tag"],
        "tls_container_ref": "http://198.51.100.10:9311/v1/containers/4073846f-1d5e-42e1-a4cf-a7046419d0e6",
        "ca_tls_container_ref": "http://198.51.100.10:9311/v1/containers/5f0d5540-fae6-4646-85d6-8a84883807fb",
        "crl_container_ref": "http://198.51.100.10:9311/v1/containers/6faf0a01-6892-454c-aaac-650282820c0b",
        "tls_enabled": false,
        "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
        "tls_versions": ["TLSv1.2", "TLSv1.3"],
        "alpn_protocols": ["http/1.1", "http/1.0"]
    }
}
PUT
/v2/lbaas/pools/{pool_id}

Update a Pool

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.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

alpn_protocols (Optional)

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.24

ca_tls_container_ref (Optional)

body

string

The reference of the key manager service secret containing a PEM format CA certificate bundle for tls_enabled pools.

New in version 2.8

crl_container_ref (Optional)

body

string

The reference of the key manager service secret containing a PEM format CA revocation list file for tls_enabled pools.

description (Optional)

body

string

A human-readable description for the resource.

lb_algorithm (Optional)

body

string

The load balancing algorithm for the pool. One of LEAST_CONNECTIONS, ROUND_ROBIN, or SOURCE_IP.

name (Optional)

body

string

Human-readable name of the resource.

pool_id

path

uuid

The ID of the pool to query.

session_persistence (Optional)

body

object

A JSON object specifying the session persistence for the pool or null for no session persistence. See Pool Session Persistence. Default is null.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

tls_enabled (Optional)

body

boolean

When true connections to backend member servers will use TLS encryption. Default is false.

New in version 2.8

tls_ciphers (Optional)

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_container_ref (Optional)

body

string

The reference to the key manager service secret containing a PKCS12 format certificate/key bundle for tls_enabled pools for TLS client authentication to the member servers.

New in version 2.8

tls_versions (Optional)

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

Request Example

{
    "pool": {
        "lb_algorithm": "LEAST_CONNECTIONS",
        "session_persistence": {
            "type": "SOURCE_IP"
        },
        "description": "Super Least Connections Pool",
        "name": "super-least-conn-pool",
        "tags": ["updated_tag"],
        "tls_container_ref": "http://198.51.100.10:9311/v1/containers/c1cd501d-3cf9-4873-a11b-a74bebcde929",
        "ca_tls_container_ref": null,
        "crl_container_ref": null,
        "tls_enabled": false,
        "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
        "tls_versions": ["TLSv1.2", "TLSv1.3"],
        "alpn_protocols": ["http/1.1", "http/1.0"]
    }
}

Curl Example

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","tags":["updated_tag"],"tls_container_ref":"http://198.51.100.10:9311/v1/containers/c1cd501d-3cf9-4873-a11b-a74bebcde929","ca_tls_container_ref":null,"crl_container_ref":null,"tls_enabled":false,"tls_ciphers":"ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256", "tls_versions": ["TLSv1.2", "TLSv1.3"], "alpn_protocols": ["http/1.1", "http/1.0"]}}' http://198.51.100.10:9876/v2/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

alpn_protocols

body

array

A list of ALPN protocols. Available protocols: http/1.0, http/1.1, h2

New in version 2.24

ca_tls_container_ref

body

string

The reference of the key manager service secret containing a PEM format CA certificate bundle for tls_enabled pools.

New in version 2.8

created_at

body

string

The UTC date and timestamp when the resource was created.

crl_container_ref

body

string

The reference of the key manager service secret containing a PEM format CA revocation list file for tls_enabled pools.

description

body

string

A human-readable description for the resource.

healthmonitor_id

body

uuid

The associated health monitor ID.

id

body

uuid

The ID of the pool.

lb_algorithm

body

string

The load balancing algorithm for the pool. One of LEAST_CONNECTIONS, ROUND_ROBIN, SOURCE_IP, or SOURCE_IP_PORT.

listeners

body

array

A list of listener IDs.

loadbalancers

body

array

A list of load balancer IDs.

members

body

array

A list of member IDs.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol

body

string

The protocol for the resource. One of HTTP, HTTPS, PROXY, PROXYV2, SCTP, TCP, or UDP.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

session_persistence

body

object

A JSON object specifying the session persistence for the pool or null for no session persistence. See Pool Session Persistence. Default is null.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

tls_enabled

body

boolean

When true connections to backend member servers will use TLS encryption. Default is false.

New in version 2.8

tls_ciphers

body

string

List of ciphers in OpenSSL format (colon-separated). See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html

New in version 2.15

tls_container_ref

body

string

The reference to the key manager service secret containing a PKCS12 format certificate/key bundle for tls_enabled pools for TLS client authentication to the member servers.

New in version 2.8

tls_versions

body

array

A list of TLS protocol versions. Available versions: SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3

New in version 2.17

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "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": "PENDING_UPDATE",
        "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",
        "tags": ["updated_tag"],
        "tls_container_ref": "http://198.51.100.10:9311/v1/containers/c1cd501d-3cf9-4873-a11b-a74bebcde929",
        "ca_tls_container_ref": null,
        "crl_container_ref": null,
        "tls_enabled": false,
        "tls_ciphers": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256",
        "tls_versions": ["TLSv1.2", "TLSv1.3"],
        "alpn_protocols": ["http/1.1", "http/1.0"]
    }
}
DELETE
/v2/lbaas/pools/{pool_id}

Remove a Pool

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.

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

pool_id

path

uuid

The ID of the pool to query.

Curl Example

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

Response

There is no body content for the response of a successful DELETE request.

Members

GET
/v2/lbaas/pools/{pool_id}/members

List 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 Filtering and column selection.

Administrative users can specify a project ID that is different than their own to list members for other projects.

The list might be empty.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

pool_id

path

uuid

The ID of the pool to query.

project_id (Optional)

query

string

The ID of the project to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/pools/24a43e68-36de-45f6-89cf-c03df583131d/members?project_id=e3cd678b11784734bc366148aa37580e

Response Parameters

Name

In

Type

Description

address

body

string

The IP address of the backend member server.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

backup

body

boolean

Is the member a backup? Backup members only receive traffic when all non-backup members are down.

New in version 2.1

created_at

body

string

The UTC date and timestamp when the resource was created.

id

body

uuid

The ID of the member.

monitor_address

body

string

An alternate IP address used for health monitoring a backend member. Default is null which monitors the member address.

monitor_port

body

integer

An alternate protocol port used for health monitoring a backend member. Default is null which monitors the member protocol_port.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol_port

body

integer

The protocol port number the backend member server is listening on.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

subnet_id

body

uuid

The subnet ID the member service is accessible from.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

weight

body

integer

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.

Response Example

{
    "members": [
        {
            "monitor_port": 8080,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "name": "web-server-1",
            "weight": 20,
            "backup": false,
            "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",
            "tags": ["test_tag"]
        }
    ]
}
POST
/v2/lbaas/pools/{pool_id}/members

Create Member

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 provisioning status is ACTIVE, PENDING_CREATE, or ERROR.

If the status is PENDING_CREATE, issue GET /v2/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.

  • backup. Default is false.

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

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

503 - Service Unavailable

The service cannot handle the request right now.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

address

body

string

The IP address of the resource.

backup (Optional)

body

boolean

Is the member a backup? Backup members only receive traffic when all non-backup members are down.

New in version 2.1

monitor_address (Optional)

body

string

An alternate IP address used for health monitoring a backend member. Default is null which monitors the member address.

monitor_port (Optional)

body

integer

An alternate protocol port used for health monitoring a backend member. Default is null which monitors the member protocol_port.

name (Optional)

body

string

Human-readable name of the resource.

pool_id

path

uuid

The ID of the pool to query.

project_id (Optional)

body

string

The ID of the project owning this resource. (deprecated)

protocol_port

body

integer

The protocol port number for the resource.

subnet_id (Optional)

body

uuid

The subnet ID the member service is accessible from.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

weight (Optional)

body

integer

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.

Request Example

{
    "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,
        "backup": false,
        "tags": ["test_tag"]
    }
}

Curl Example

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,"backup":false,"tags":["test_tag"]}}' http://198.51.100.10:9876/v2/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd/members

Response Parameters

Name

In

Type

Description

address

body

string

The IP address of the backend member server.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

backup

body

boolean

Is the member a backup? Backup members only receive traffic when all non-backup members are down.

New in version 2.1

created_at

body

string

The UTC date and timestamp when the resource was created.

id

body

uuid

The ID of the member.

monitor_address

body

string

An alternate IP address used for health monitoring a backend member. Default is null which monitors the member address.

monitor_port

body

integer

An alternate protocol port used for health monitoring a backend member. Default is null which monitors the member protocol_port.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol_port

body

integer

The protocol port number the backend member server is listening on.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

subnet_id

body

uuid

The subnet ID the member service is accessible from.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

weight

body

integer

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.

Response Example

{
    "member": {
        "monitor_port": 8080,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "name": "web-server-1",
        "weight": 20,
        "backup": false,
        "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",
        "tags": ["test_tag"]
    }
}
GET
/v2/lbaas/pools/{pool_id}/members/{member-id}

Show Member details

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.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

member_id

path

uuid

The ID of the member to query.

pool_id

path

uuid

The ID of the pool to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/pools/24a43e68-36de-45f6-89cf-c03df583131d/members/957a1ace-1bd2-449b-8455-820b6e4b63f3

Response Parameters

Name

In

Type

Description

address

body

string

The IP address of the backend member server.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

backup

body

boolean

Is the member a backup? Backup members only receive traffic when all non-backup members are down.

New in version 2.1

created_at

body

string

The UTC date and timestamp when the resource was created.

id

body

uuid

The ID of the member.

monitor_address

body

string

An alternate IP address used for health monitoring a backend member. Default is null which monitors the member address.

monitor_port

body

integer

An alternate protocol port used for health monitoring a backend member. Default is null which monitors the member protocol_port.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol_port

body

integer

The protocol port number the backend member server is listening on.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

subnet_id

body

uuid

The subnet ID the member service is accessible from.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

weight

body

integer

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.

Response Example

{
    "member": {
        "monitor_port": 8080,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "name": "web-server-1",
        "weight": 20,
        "backup": false,
        "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",
        "tags": ["test_tag"]
    }
}
PUT
/v2/lbaas/pools/{pool_id}/members/{member_id}

Update a Member

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.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

backup (Optional)

body

boolean

Is the member a backup? Backup members only receive traffic when all non-backup members are down.

New in version 2.1

member_id

path

uuid

The ID of the member to query.

monitor_address (Optional)

body

string

An alternate IP address used for health monitoring a backend member. Default is null which monitors the member address.

monitor_port (Optional)

body

integer

An alternate protocol port used for health monitoring a backend member. Default is null which monitors the member protocol_port.

name (Optional)

body

string

Human-readable name of the resource.

pool_id

path

uuid

The ID of the pool to query.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

weight (Optional)

body

integer

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.

Request Example

{
    "member": {
        "name": "web-server-1-2",
        "weight": "0",
        "admin_state_up": "true",
        "monitor_address": "192.0.2.40",
        "monitor_port": 8888,
        "backup": false,
        "tags": ["updated_tag"]
    }
}

Curl Example

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,"backup":false,"tags":["updated_tag"]}}' http://198.51.100.10:9876/v2/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd/members/957a1ace-1bd2-449b-8455-820b6e4b63f3

Response Parameters

Name

In

Type

Description

address

body

string

The IP address of the backend member server.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

backup

body

boolean

Is the member a backup? Backup members only receive traffic when all non-backup members are down.

New in version 2.1

created_at

body

string

The UTC date and timestamp when the resource was created.

id

body

uuid

The ID of the member.

monitor_address

body

string

An alternate IP address used for health monitoring a backend member. Default is null which monitors the member address.

monitor_port

body

integer

An alternate protocol port used for health monitoring a backend member. Default is null which monitors the member protocol_port.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

protocol_port

body

integer

The protocol port number the backend member server is listening on.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

subnet_id

body

uuid

The subnet ID the member service is accessible from.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

weight

body

integer

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.

Response Example

{
    "member": {
        "monitor_port": 8080,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "name": "web-server-1",
        "weight": 20,
        "backup": false,
        "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",
        "tags": ["updated_tag"]
    }
}
PUT
/v2/lbaas/pools/{pool_id}/members

Batch Update Members

Set the state of members for a pool in one API call. This may include creating new members, deleting old members, and updating existing members. Existing members are matched based on address/port combination.

For example, assume a pool currently has two members. These members have the following address/port combinations: ‘192.0.2.15:80’ and ‘192.0.2.16:80’. Now assume a PUT request is made that includes members with address/port combinations: ‘192.0.2.16:80’ and ‘192.0.2.17:80’.

The member ‘192.0.2.15:80’ will be deleted, because it was not in the request.

The member ‘192.0.2.16:80’ will be updated to match the request data for that member, because it was matched.

The member ‘192.0.2.17:80’ will be created, because no such member existed.

The optional parameter additive_only when defined as true will skip deletions for members missing from the provided list. If this were set in the above example, the member ‘192.0.2.15:80’ would have remained in the pool.

If the request is valid, the service returns the Accepted (202) response code. To confirm the updates, check that the member provisioning statuses are ACTIVE for new or updated members, and that any unspecified members were correctly deleted. If the statuses are PENDING_UPDATE or PENDING_DELETE, use GET to poll the member objects for changes.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

503 - Service Unavailable

The service cannot handle the request right now.

Request

Name

In

Type

Description

additive_only (Optional)

query

boolean

If true no members will be deleted during the batch operation.

New in version 2.11

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

address

body

string

The IP address of the resource.

backup (Optional)

body

boolean

Is the member a backup? Backup members only receive traffic when all non-backup members are down.

New in version 2.1

monitor_address (Optional)

body

string

An alternate IP address used for health monitoring a backend member. Default is null which monitors the member address.

monitor_port (Optional)

body

integer

An alternate protocol port used for health monitoring a backend member. Default is null which monitors the member protocol_port.

name (Optional)

body

string

Human-readable name of the resource.

pool_id

path

uuid

The ID of the pool to query.

project_id (Optional)

body

string

The ID of the project owning this resource. (deprecated)

protocol_port

body

integer

The protocol port number for the resource.

subnet_id (Optional)

body

uuid

The subnet ID the member service is accessible from.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

weight (Optional)

body

integer

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.

Request Example

{
    "members": [
        {
            "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,
            "tags": ["updated_tag"]
        },
        {
            "name": "web-server-2",
            "weight": 10,
            "admin_state_up": true,
            "subnet_id": "bbb35f84-35cc-4b2f-84c2-a6a29bba68aa",
            "address": "192.0.2.17",
            "protocol_port": 80,
            "monitor_port": 8080,
            "tags": ["updated_tag"]
        }
    ]
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"members":[{"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,"tags":["updated_tag"]},{"name":"web-server-2","weight":"10","admin_state_up":true,"subnet_id":"bbb35f84-35cc-4b2f-84c2-a6a29bba68aa","address":"192.0.2.17","protocol_port":"80","monitor_port":8080,"tags":["updated_tag"]}]}' http://198.51.100.10:9876/v2/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd/members

Response

There is no body content for the response of a successful PUT request.

DELETE
/v2/lbaas/pools/{pool_id}/members/{member_id}

Remove a Member

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.

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

member_id

path

uuid

The ID of the member to query.

pool_id

path

uuid

The ID of the pool to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/pools/4029d267-3983-4224-a3d0-afb3fe16a2cd/members/957a1ace-1bd2-449b-8455-820b6e4b63f3

Response

There is no body content for the response of a successful DELETE request.

Health Monitor

GET
/v2/lbaas/healthmonitors

List Health Monitors

Lists all health monitors 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 Filtering and column selection.

Administrative users can specify a project ID that is different than their own to list health monitors for other projects.

The list might be empty.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

project_id (Optional)

query

string

The ID of the project to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/healthmonitors?project_id=e3cd678b11784734bc366148aa37580e

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

created_at

body

string

The UTC date and timestamp when the resource was created.

delay

body

integer

The time, in seconds, between sending probes to members.

domain_name

body

string

The domain name, which be injected into the HTTP Host Header to the backend server for HTTP health check.

New in version 2.10

expected_codes

body

string

The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values:

  • A single value, such as 200

  • A list, such as 200, 202

  • A range, such as 200-204

http_method

body

string

The HTTP method that the health monitor uses for requests. One of CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, or TRACE.

http_version

body

float

The HTTP version. One of 1.0 or 1.1. The default is 1.0.

New in version 2.10

id

body

uuid

The associated health monitor ID.

max_retries

body

integer

The number of successful checks before changing the operating status of the member to ONLINE. A valid value is from 1 to 10.

max_retries_down

body

integer

The number of allowed check failures before changing the operating status of the member to ERROR. A valid value is from 1 to 10.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

pool_id

body

uuid

The ID of the pool.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout

body

integer

The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.

type

body

string

The type of health monitor. One of HTTP, HTTPS, PING, SCTP, TCP, TLS-HELLO, or UDP-CONNECT.

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

url_path

body

string

The HTTP URL path of the request sent by the monitor to test the health of a backend member. Must be a string that begins with a forward slash (/).

Response Example

{
    "healthmonitors": [
        {
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "name": "super-pool-health-monitor",
            "admin_state_up": true,
            "pools": [
                {
                    "id": "4029d267-3983-4224-a3d0-afb3fe16a2cd"
                }
            ],
            "created_at": "2017-05-11T23:53:47",
            "provisioning_status": "ACTIVE",
            "updated_at": "2017-05-11T23:53:47",
            "delay": 10,
            "expected_codes": "200",
            "max_retries": 1,
            "http_method": "GET",
            "timeout": 5,
            "max_retries_down": 3,
            "url_path": "/",
            "type": "HTTP",
            "id": "8ed3c5ac-6efa-420c-bedb-99ba14e58db5",
            "operating_status": "ONLINE",
            "tags": ["test_tag"],
            "http_version": 1.0,
            "domain_name": null
        }
    ]
}
POST
/v2/lbaas/healthmonitors

Create Health Monitor

Creates a health monitor on a pool.

Health monitors define how the load balancer monitors backend servers to determine if they are available to service requests.

This operation provisions a new health monitor 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 health monitor.

In the response, the health monitor provisioning status is ACTIVE, PENDING_CREATE, or ERROR.

If the status is PENDING_CREATE, issue GET /v2/lbaas/healthmonitors/{healthmonitor_id} to view the progress of the provisioning operation. When the health monitor status changes to ACTIVE, the health monitor 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 is deprecated. The health monitor will inherit the project_id of the parent load balancer.

At a minimum, you must specify these health monitor attributes:

  • delay The interval, in seconds, between health checks.

  • max_retries The number of successful checks before changing the operating status of the member to ONLINE.

  • pool_id The pool to monitor.

  • timeout The time, in seconds, after which a health check times out.

  • type The type of health monitor. One of HTTP, HTTPS, PING, SCTP, TCP, TLS-HELLO, or UDP-CONNECT.

Some attributes receive default values if you omit them from the request:

  • admin_state_up The default is true.

  • expected_codes The expected HTTP status codes to get from a successful health check. The default is 200.

  • http_method The default is GET.

  • http_version The default is 1.0.

  • max_retries_down The default is 3.

  • url_path The default is /.

To create a health monitor, the parent load balancer must have an ACTIVE provisioning status.

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

503 - Service Unavailable

The service cannot handle the request right now.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

delay

body

integer

The time, in seconds, between sending probes to members.

domain_name (Optional)

body

string

The domain name, which be injected into the HTTP Host Header to the backend server for HTTP health check.

New in version 2.10

expected_codes (Optional)

body

string

The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values:

  • A single value, such as 200

  • A list, such as 200, 202

  • A range, such as 200-204

The default is 200.

http_method (Optional)

body

string

The HTTP method that the health monitor uses for requests. One of CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, or TRACE. The default is GET.

http_version (Optional)

body

float

The HTTP version. One of 1.0 or 1.1. The default is 1.0.

New in version 2.10

name (Optional)

body

string

Human-readable name of the resource.

max_retries

body

integer

The number of successful checks before changing the operating status of the member to ONLINE. A valid value is from 1 to 10.

max_retries_down (Optional)

body

integer

The number of allowed check failures before changing the operating status of the member to ERROR. A valid value is from 1 to 10. The default is 3.

pool_id

body

uuid

The ID of the pool.

project_id (Optional)

body

string

The ID of the project owning this resource. (deprecated)

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout

body

integer

The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.

type

body

string

The type of health monitor. One of HTTP, HTTPS, PING, SCTP, TCP, TLS-HELLO, or UDP-CONNECT.

url_path (Optional)

body

string

The HTTP URL path of the request sent by the monitor to test the health of a backend member. Must be a string that begins with a forward slash (/). The default URL path is /.

Request Example

{
    "healthmonitor": {
        "name": "super-pool-health-monitor",
        "admin_state_up": true,
        "pool_id": "4029d267-3983-4224-a3d0-afb3fe16a2cd",
        "delay": "10",
        "expected_codes": "200",
        "max_retries": "1",
        "http_method": "GET",
        "timeout": "5",
        "url_path": "/",
        "type": "HTTP",
        "max_retries_down": 3,
        "tags": ["test_tag"],
        "http_version": 1.1,
        "domain_name": "testlab.com"
    }
}

Curl Example

curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"healthmonitor":{"name":"super-pool-health-monitor","admin_state_up":true,"pool_id":"4029d267-3983-4224-a3d0-afb3fe16a2cd","delay":"10","expected_codes":"200","max_retries":"1","http_method":"GET","timeout":"5","url_path":"/","type":"HTTP","max_retries_down":3,"tags":["test_tag"],"http_version":1.1,"domain_name":"testlab.com"}}' http://198.51.100.10:9876/v2/lbaas/healthmonitors

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

created_at

body

string

The UTC date and timestamp when the resource was created.

delay

body

integer

The time, in seconds, between sending probes to members.

domain_name

body

string

The domain name, which be injected into the HTTP Host Header to the backend server for HTTP health check.

New in version 2.10

expected_codes

body

string

The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values:

  • A single value, such as 200

  • A list, such as 200, 202

  • A range, such as 200-204

http_method

body

string

The HTTP method that the health monitor uses for requests. One of CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, or TRACE.

http_version

body

float

The HTTP version. One of 1.0 or 1.1. The default is 1.0.

New in version 2.10

id

body

uuid

The associated health monitor ID.

max_retries

body

integer

The number of successful checks before changing the operating status of the member to ONLINE. A valid value is from 1 to 10.

max_retries_down

body

integer

The number of allowed check failures before changing the operating status of the member to ERROR. A valid value is from 1 to 10.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

pool_id

body

uuid

The ID of the pool.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout

body

integer

The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.

type

body

string

The type of health monitor. One of HTTP, HTTPS, PING, SCTP, TCP, TLS-HELLO, or UDP-CONNECT.

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

url_path

body

string

The HTTP URL path of the request sent by the monitor to test the health of a backend member. Must be a string that begins with a forward slash (/).

Response Example

{
    "healthmonitor": {
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "name": "super-pool-health-monitor",
        "admin_state_up": true,
        "pools": [
            {
                "id": "4029d267-3983-4224-a3d0-afb3fe16a2cd"
            }
        ],
        "created_at": "2017-05-11T23:53:47",
        "provisioning_status": "ACTIVE",
        "updated_at": "2017-05-11T23:53:47",
        "delay": 10,
        "expected_codes": "200",
        "max_retries": 1,
        "http_method": "GET",
        "timeout": 5,
        "max_retries_down": 3,
        "url_path": "/",
        "type": "HTTP",
        "id": "8ed3c5ac-6efa-420c-bedb-99ba14e58db5",
        "operating_status": "ONLINE",
        "tags": ["test_tag"],
        "http_version": 1.1,
        "domain_name": "testlab.com"
    }
}
GET
/v2/lbaas/healthmonitors/{healthmonitor_id}

Show Health Monitor details

Shows the details of a health monitor.

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.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

healthmonitor_id

path

uuid

The ID of the health monitor to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/healthmonitors/8ed3c5ac-6efa-420c-bedb-99ba14e58db5

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

created_at

body

string

The UTC date and timestamp when the resource was created.

delay

body

integer

The time, in seconds, between sending probes to members.

domain_name

body

string

The domain name, which be injected into the HTTP Host Header to the backend server for HTTP health check.

New in version 2.10

expected_codes

body

string

The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values:

  • A single value, such as 200

  • A list, such as 200, 202

  • A range, such as 200-204

http_method

body

string

The HTTP method that the health monitor uses for requests. One of CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, or TRACE.

http_version

body

float

The HTTP version. One of 1.0 or 1.1. The default is 1.0.

New in version 2.10

id

body

uuid

The associated health monitor ID.

max_retries

body

integer

The number of successful checks before changing the operating status of the member to ONLINE. A valid value is from 1 to 10.

max_retries_down

body

integer

The number of allowed check failures before changing the operating status of the member to ERROR. A valid value is from 1 to 10.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

pool_id

body

uuid

The ID of the pool.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout

body

integer

The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.

type

body

string

The type of health monitor. One of HTTP, HTTPS, PING, SCTP, TCP, TLS-HELLO, or UDP-CONNECT.

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

url_path

body

string

The HTTP URL path of the request sent by the monitor to test the health of a backend member. Must be a string that begins with a forward slash (/).

Response Example

{
    "healthmonitor": {
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "name": "super-pool-health-monitor",
        "admin_state_up": true,
        "pools": [
            {
                "id": "4029d267-3983-4224-a3d0-afb3fe16a2cd"
            }
        ],
        "created_at": "2017-05-11T23:53:47",
        "provisioning_status": "ACTIVE",
        "updated_at": "2017-05-11T23:53:47",
        "delay": 10,
        "expected_codes": "200",
        "max_retries": 1,
        "http_method": "GET",
        "timeout": 5,
        "max_retries_down": 3,
        "url_path": "/",
        "type": "HTTP",
        "id": "8ed3c5ac-6efa-420c-bedb-99ba14e58db5",
        "operating_status": "ONLINE",
        "tags": ["test_tag"],
        "http_version": 1.0,
        "domain_name": null
    }
}
PUT
/v2/lbaas/healthmonitors/{healthmonitor_id}

Update a Health Monitor

Update an existing health monitor.

If the request is valid, the service returns the Accepted (202) response code. To confirm the update, check that the health monitor provisioning status is ACTIVE. If the status is PENDING_UPDATE, use a GET operation to poll the health monitor object for changes.

This operation returns the updated health monitor object with the ACTIVE, PENDING_UPDATE, or ERROR provisioning status.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

delay (Optional)

body

integer

The time, in seconds, between sending probes to members.

domain_name (Optional)

body

string

The domain name, which be injected into the HTTP Host Header to the backend server for HTTP health check.

New in version 2.10

expected_codes (Optional)

body

string

The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values:

  • A single value, such as 200

  • A list, such as 200, 202

  • A range, such as 200-204

The default is 200.

healthmonitor_id

path

uuid

The ID of the health monitor to query.

http_method (Optional)

body

string

The HTTP method that the health monitor uses for requests. One of CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, or TRACE. The default is GET.

http_version (Optional)

body

float

The HTTP version. One of 1.0 or 1.1. The default is 1.0.

New in version 2.10

max_retries (Optional)

body

integer

The number of successful checks before changing the operating status of the member to ONLINE. A valid value is from 1 to 10.

max_retries_down (Optional)

body

integer

The number of allowed check failures before changing the operating status of the member to ERROR. A valid value is from 1 to 10. The default is 3.

name (Optional)

body

string

Human-readable name of the resource.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout (Optional)

body

integer

The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.

url_path (Optional)

body

string

The HTTP URL path of the request sent by the monitor to test the health of a backend member. Must be a string that begins with a forward slash (/). The default URL path is /.

Request Example

{
    "healthmonitor": {
        "name": "super-pool-health-monitor-updated",
        "admin_state_up": true,
        "delay": 5,
        "expected_codes": "200",
        "http_method": "HEAD",
        "timeout": 2,
        "url_path": "/index.html",
        "max_retries": 2,
        "max_retries_down": 2,
        "tags": ["updated_tag"],
        "http_version": 1.1
    }
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"healthmonitor":{"name":"super-pool-health-monitor-updated","admin_state_up":true,"delay":5,"expected_codes":"200","http_method":"HEAD","timeout":2,"url_path":"/index.html","max_retries":2,"max_retries_down":2,"tags":["updated_tag"],"http_version":1.1}}' http://198.51.100.10:9876/v2/lbaas/healthmonitors/8ed3c5ac-6efa-420c-bedb-99ba14e58db5

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

created_at

body

string

The UTC date and timestamp when the resource was created.

delay

body

integer

The time, in seconds, between sending probes to members.

domain_name

body

string

The domain name, which be injected into the HTTP Host Header to the backend server for HTTP health check.

New in version 2.10

expected_codes

body

string

The list of HTTP status codes expected in response from the member to declare it healthy. Specify one of the following values:

  • A single value, such as 200

  • A list, such as 200, 202

  • A range, such as 200-204

http_method

body

string

The HTTP method that the health monitor uses for requests. One of CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, or TRACE.

http_version

body

float

The HTTP version. One of 1.0 or 1.1. The default is 1.0.

New in version 2.10

id

body

uuid

The associated health monitor ID.

max_retries

body

integer

The number of successful checks before changing the operating status of the member to ONLINE. A valid value is from 1 to 10.

max_retries_down

body

integer

The number of allowed check failures before changing the operating status of the member to ERROR. A valid value is from 1 to 10.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

pool_id

body

uuid

The ID of the pool.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

timeout

body

integer

The maximum time, in seconds, that a monitor waits to connect before it times out. This value must be less than the delay value.

type

body

string

The type of health monitor. One of HTTP, HTTPS, PING, SCTP, TCP, TLS-HELLO, or UDP-CONNECT.

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

url_path

body

string

The HTTP URL path of the request sent by the monitor to test the health of a backend member. Must be a string that begins with a forward slash (/).

Response Example

{
    "healthmonitor": {
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "name": "super-pool-health-monitor-updated",
        "admin_state_up": true,
        "pools": [
            {
                "id": "4029d267-3983-4224-a3d0-afb3fe16a2cd"
            }
        ],
        "created_at": "2017-05-11T23:53:47",
        "provisioning_status": "PENDING_UPDATE",
        "updated_at": "2017-05-11T23:53:47",
        "delay": 5,
        "expected_codes": "200",
        "max_retries": 2,
        "http_method": "HEAD",
        "timeout": 2,
        "max_retries_down": 2,
        "url_path": "/index.html",
        "type": "HTTP",
        "id": "8ed3c5ac-6efa-420c-bedb-99ba14e58db5",
        "operating_status": "ONLINE",
        "tags": ["updated_tag"],
        "http_version": 1.1,
        "domain_name": null
    }
}
DELETE
/v2/lbaas/healthmonitors/{healthmonitor_id}

Remove a Health Monitor

Removes a health monitor 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.

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

healthmonitor_id

path

uuid

The ID of the health monitor to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/healthmonitors/8ed3c5ac-6efa-420c-bedb-99ba14e58db5

Response

There is no body content for the response of a successful DELETE request.

L7 Policies

GET
/v2/lbaas/l7policies

List L7 Policies

Lists all L7 policies 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 Filtering and column selection.

Administrative users can specify a project ID that is different than their own to list L7 policies for other projects.

The list might be empty.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

project_id (Optional)

query

string

The ID of the project to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/l7policies?project_id=e3cd678b11784734bc366148aa37580e

Response Parameters

Name

In

Type

Description

action

body

string

The L7 policy action. One of REDIRECT_PREFIX, REDIRECT_TO_POOL, REDIRECT_TO_URL, or REJECT.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

created_at

body

string

The UTC date and timestamp when the resource was created.

description

body

string

A human-readable description for the resource.

id

body

uuid

The ID of the L7 policy.

listener_id

body

uuid

The ID of the listener.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

position

body

integer

The position of this policy on the listener. Positions start at 1.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

redirect_http_code

body

integer

Requests matching this policy will be redirected to the specified URL or Prefix URL with the HTTP response code. Valid if action is REDIRECT_TO_URL or REDIRECT_PREFIX. Valid options are: 301, 302, 303, 307, or 308. Default is 302.

New in version 2.9

redirect_pool_id

body

uuid

Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL. The pool has some restrictions, See Protocol Combinations (Listener/Pool).

redirect_prefix

body

string

Requests matching this policy will be redirected to this Prefix URL. Only valid if action is REDIRECT_PREFIX.

redirect_url

body

string

Requests matching this policy will be redirected to this URL. Only valid if action is REDIRECT_TO_URL.

rules

body

array

List of associated L7 rule IDs.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "l7policies": [
        {
            "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
            "description": "Redirect requests to example.com",
            "admin_state_up": true,
            "rules": [
                {
                    "id": "efd6a3f8-73bf-47f0-8ae6-503ebda57372"
                }
            ],
            "created_at": "2017-06-24T23:25:14",
            "provisioning_status": "ACTIVE",
            "updated_at": "2017-06-24T23:30:05",
            "redirect_http_code": 302,
            "redirect_pool_id": null,
            "redirect_prefix": null,
            "redirect_url": "http://www.example.com",
            "action": "REDIRECT_TO_URL",
            "position": 1,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "id": "8a1412f0-4c32-4257-8b07-af4770b604fd",
            "operating_status": "ONLINE",
            "name": "redirect-example.com",
            "tags": ["test_tag"]
        }
    ]
}
POST
/v2/lbaas/l7policies

Create an L7 Policy

Creates a L7 policy.

This operation provisions a new L7 policy 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 L7 policy.

In the response, the L7 policy provisioning status is ACTIVE, PENDING_CREATE, or ERROR.

If the status is PENDING_CREATE, issue GET /v2/lbaas/l7policies/{l7policy_id} to view the progress of the provisioning operation. When the L7 policy status changes to ACTIVE, the L7 policy 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.

All the rules associated with a given policy are logically ANDed together. A request must match all the policy’s rules to match the policy.

If you need to express a logical OR operation between rules, then do this by creating multiple policies with the same action.

If a new policy is created with a position that matches that of an existing policy, then the new policy is inserted at the given position.

L7 policies with action of REDIRECT_TO_URL will return the default HTTP Found (302) response code with the redirect_url. Also, specify redirect_http_code to configure the needed HTTP response code, such as, 301, 302, 303, 307 and 308.

L7 policies with action of REJECT will return a Forbidden (403) response code to the requester.

Note

Pools of type SCTP, TCP or UDP cannot be used in L7 policies at this time.

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

503 - Service Unavailable

The service cannot handle the request right now.

Request

Name

In

Type

Description

action

body

string

The L7 policy action. One of REDIRECT_PREFIX, REDIRECT_TO_POOL, REDIRECT_TO_URL, or REJECT.

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

description (Optional)

body

string

A human-readable description for the resource.

listener_id

body

uuid

The ID of the listener.

name (Optional)

body

string

Human-readable name of the resource.

position (Optional)

body

integer

The position of this policy on the listener. Positions start at 1.

project_id (Optional)

body

string

The ID of the project owning this resource.

redirect_http_code (Optional)

body

integer

Requests matching this policy will be redirected to the specified URL or Prefix URL with the HTTP response code. Valid if action is REDIRECT_TO_URL or REDIRECT_PREFIX. Valid options are: 301, 302, 303, 307, or 308. Default is 302.

New in version 2.9

redirect_pool_id (Optional)

body

uuid

Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL. The pool has some restrictions, See Protocol Combinations (Listener/Pool).

redirect_prefix (Optional)

body

string

Requests matching this policy will be redirected to this Prefix URL. Only valid if action is REDIRECT_PREFIX.

redirect_url (Optional)

body

string

Requests matching this policy will be redirected to this URL. Only valid if action is REDIRECT_TO_URL.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

Request Example

{
    "l7policy": {
        "description": "Redirect requests to example.com",
        "admin_state_up": true,
        "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
        "redirect_url": "http://www.example.com",
        "redirect_http_code": 301,
        "name": "redirect-example.com",
        "action": "REDIRECT_TO_URL",
        "position": 1,
        "tags": ["test_tag"]
    }
}

Curl Example

curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"l7policy":{"description":"Redirect requests to example.com","admin_state_up":true,"listener_id":"023f2e34-7806-443b-bfae-16c324569a3d","redirect_http_code":301,"redirect_url":"http://www.example.com","name":"redirect-example.com","action":"REDIRECT_TO_URL","position":1,"tags":["test_tag"]}}' http://198.51.100.10:9876/v2/lbaas/l7policies

Response Parameters

Name

In

Type

Description

action

body

string

The L7 policy action. One of REDIRECT_PREFIX, REDIRECT_TO_POOL, REDIRECT_TO_URL, or REJECT.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

created_at

body

string

The UTC date and timestamp when the resource was created.

description

body

string

A human-readable description for the resource.

id

body

uuid

The ID of the L7 policy.

listener_id

body

uuid

The ID of the listener.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

position

body

integer

The position of this policy on the listener. Positions start at 1.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

redirect_http_code

body

integer

Requests matching this policy will be redirected to the specified URL or Prefix URL with the HTTP response code. Valid if action is REDIRECT_TO_URL or REDIRECT_PREFIX. Valid options are: 301, 302, 303, 307, or 308. Default is 302.

New in version 2.9

redirect_pool_id

body

uuid

Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL. The pool has some restrictions, See Protocol Combinations (Listener/Pool).

redirect_prefix

body

string

Requests matching this policy will be redirected to this Prefix URL. Only valid if action is REDIRECT_PREFIX.

redirect_url

body

string

Requests matching this policy will be redirected to this URL. Only valid if action is REDIRECT_TO_URL.

rules

body

array

List of associated L7 rule IDs.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "l7policy": [
        {
            "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
            "description": "Redirect requests to example.com",
            "admin_state_up": true,
            "rules": [
                {
                    "id": "efd6a3f8-73bf-47f0-8ae6-503ebda57372"
                }
            ],
            "created_at": "2017-06-24T23:25:14",
            "provisioning_status": "PENDING_CREATE",
            "updated_at": "2017-06-24T23:30:05",
            "redirect_http_code": 301,
            "redirect_pool_id": null,
            "redirect_prefix": null,
            "redirect_url": "http://www.example.com",
            "action": "REDIRECT_TO_URL",
            "position": 1,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "id": "8a1412f0-4c32-4257-8b07-af4770b604fd",
            "operating_status": "OFFLINE",
            "name": "redirect-example.com",
            "tags": ["test_tag"]
        }
    ]
}
GET
/v2/lbaas/l7policies/{l7policy_id}

Show L7 Policy details

Shows the details of a L7 policy.

If you are not an administrative user and the L7 policy object does not belong to your project, the service returns the HTTP Forbidden (403) response code.

This operation does not require a request body.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

l7policy_id

path

uuid

The ID of the L7 policy to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd

Response Parameters

Name

In

Type

Description

action

body

string

The L7 policy action. One of REDIRECT_PREFIX, REDIRECT_TO_POOL, REDIRECT_TO_URL, or REJECT.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

created_at

body

string

The UTC date and timestamp when the resource was created.

description

body

string

A human-readable description for the resource.

id

body

uuid

The ID of the L7 policy.

listener_id

body

uuid

The ID of the listener.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

position

body

integer

The position of this policy on the listener. Positions start at 1.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

redirect_http_code

body

integer

Requests matching this policy will be redirected to the specified URL or Prefix URL with the HTTP response code. Valid if action is REDIRECT_TO_URL or REDIRECT_PREFIX. Valid options are: 301, 302, 303, 307, or 308. Default is 302.

New in version 2.9

redirect_pool_id

body

uuid

Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL. The pool has some restrictions, See Protocol Combinations (Listener/Pool).

redirect_prefix

body

string

Requests matching this policy will be redirected to this Prefix URL. Only valid if action is REDIRECT_PREFIX.

redirect_url

body

string

Requests matching this policy will be redirected to this URL. Only valid if action is REDIRECT_TO_URL.

rules

body

array

List of associated L7 rule IDs.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "l7policy":
        {
            "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
            "description": "Redirect requests to example.com",
            "admin_state_up": true,
            "rules": [
                {
                    "id": "efd6a3f8-73bf-47f0-8ae6-503ebda57372"
                }
            ],
            "created_at": "2017-06-24T23:25:14",
            "provisioning_status": "ACTIVE",
            "updated_at": "2017-06-24T23:30:05",
            "redirect_http_code": 302,
            "redirect_pool_id": null,
            "redirect_prefix": null,
            "redirect_url": "http://www.example.com",
            "action": "REDIRECT_TO_URL",
            "position": 1,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "id": "8a1412f0-4c32-4257-8b07-af4770b604fd",
            "operating_status": "ONLINE",
            "name": "redirect-example.com",
            "tags": ["test_tag"]
        }
}
PUT
/v2/lbaas/l7policies/{l7policy_id}

Update a L7 Policy

Updates a L7 policy.

If the request is valid, the service returns the Accepted (202) response code. To confirm the update, check that the L7 policy provisioning status is ACTIVE. If the status is PENDING_UPDATE, use a GET operation to poll the L7 policy object for changes.

This operation returns the updated L7 policy object with the ACTIVE, PENDING_UPDATE, or ERROR provisioning status.

If a policy is updated with a position that matches that of an existing policy, then the updated policy is inserted at the given position.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

action (Optional)

body

string

The L7 policy action. One of REDIRECT_PREFIX, REDIRECT_TO_POOL, REDIRECT_TO_URL, or REJECT.

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

description (Optional)

body

string

A human-readable description for the resource.

l7policy_id

path

uuid

The ID of the L7 policy to query.

name (Optional)

body

string

Human-readable name of the resource.

position (Optional)

body

integer

The position of this policy on the listener. Positions start at 1.

redirect_http_code (Optional)

body

integer

Requests matching this policy will be redirected to the specified URL or Prefix URL with the HTTP response code. Valid if action is REDIRECT_TO_URL or REDIRECT_PREFIX. Valid options are: 301, 302, 303, 307, or 308. Default is 302.

New in version 2.9

redirect_pool_id (Optional)

body

uuid

Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL. The pool has some restrictions, See Protocol Combinations (Listener/Pool).

redirect_prefix (Optional)

body

string

Requests matching this policy will be redirected to this Prefix URL. Only valid if action is REDIRECT_PREFIX.

redirect_url (Optional)

body

string

Requests matching this policy will be redirected to this URL. Only valid if action is REDIRECT_TO_URL.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

Request Example

{
    "l7policy": {
        "description": "Redirect requests to images.example.com",
        "admin_state_up": true,
        "redirect_http_code": 301,
        "redirect_url": "http://images.example.com",
        "name": "redirect-images.example.com",
        "action": "REDIRECT_TO_URL",
        "position": 1,
        "tags": ["updated_tag"]
    }
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"l7policy":{"description":"Redirect requests to images.example.com","admin_state_up":true,"redirect_http_code":301,"redirect_url":"http://images.example.com","name":"redirect-images.example.com","action":"REDIRECT_TO_URL","position":1,"tags":["updated_tag"]}}' http://198.51.100.10:9876/v2/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd

Response Parameters

Name

In

Type

Description

action

body

string

The L7 policy action. One of REDIRECT_PREFIX, REDIRECT_TO_POOL, REDIRECT_TO_URL, or REJECT.

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

created_at

body

string

The UTC date and timestamp when the resource was created.

description

body

string

A human-readable description for the resource.

id

body

uuid

The ID of the L7 policy.

listener_id

body

uuid

The ID of the listener.

name

body

string

Human-readable name of the resource.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

position

body

integer

The position of this policy on the listener. Positions start at 1.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

redirect_http_code

body

integer

Requests matching this policy will be redirected to the specified URL or Prefix URL with the HTTP response code. Valid if action is REDIRECT_TO_URL or REDIRECT_PREFIX. Valid options are: 301, 302, 303, 307, or 308. Default is 302.

New in version 2.9

redirect_pool_id

body

uuid

Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL. The pool has some restrictions, See Protocol Combinations (Listener/Pool).

redirect_prefix

body

string

Requests matching this policy will be redirected to this Prefix URL. Only valid if action is REDIRECT_PREFIX.

redirect_url

body

string

Requests matching this policy will be redirected to this URL. Only valid if action is REDIRECT_TO_URL.

rules

body

array

List of associated L7 rule IDs.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

Response Example

{
    "l7policy":
        {
            "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
            "description": "Redirect requests to example.com",
            "admin_state_up": true,
            "rules": [
                {
                    "id": "efd6a3f8-73bf-47f0-8ae6-503ebda57372"
                }
            ],
            "created_at": "2017-06-24T23:25:14",
            "provisioning_status": "PENDING_UPDATE",
            "updated_at": "2017-06-24T23:30:05",
            "redirect_http_code": 301,
            "redirect_pool_id": null,
            "redirect_prefix": null,
            "redirect_url": "http://www.example.com",
            "action": "REDIRECT_TO_URL",
            "position": 1,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "id": "8a1412f0-4c32-4257-8b07-af4770b604fd",
            "operating_status": "ONLINE",
            "name": "redirect-example.com",
            "tags": ["updated_tag"]
        }
}
DELETE
/v2/lbaas/l7policies/{l7policy_id}

Remove a L7 Policy

Removes a L7 policy 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.

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

l7policy_id

path

uuid

The ID of the L7 policy to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd

Response

There is no body content for the response of a successful DELETE request.

L7 Rules

GET
/v2/lbaas/l7policies/{l7policy_id}/rules

List L7 Rules

Lists all L7 rules 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 Filtering and column selection.

Administrative users can specify a project ID that is different than their own to list L7 policies for other projects.

The list might be empty.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

l7policy_id

path

uuid

The ID of the L7 policy to query.

project_id (Optional)

query

string

The ID of the project to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

compare_type

body

string

The comparison type for the L7 rule. One of CONTAINS, ENDS_WITH, EQUAL_TO, REGEX, or STARTS_WITH.

created_at

body

string

The UTC date and timestamp when the resource was created.

id

body

uuid

The ID of the L7 rule.

invert

body

boolean

When true the logic of the rule is inverted. For example, with invert true, equal to would become not equal to.

key

body

string

The key to use for the comparison. For example, the name of the cookie to evaluate.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

type

body

string

The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, PATH, SSL_CONN_HAS_CERT, SSL_VERIFY_RESULT, or SSL_DN_FIELD.

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

value

body

string

The value to use for the comparison. For example, the file type to compare.

Response Example

{
    "rules": [
        {
            "created_at": "2017-06-27T15:52:27",
            "compare_type": "REGEX",
            "provisioning_status": "ACTIVE",
            "invert": false,
            "admin_state_up": true,
            "updated_at": "2017-06-27T15:52:28",
            "value": "/images*",
            "key": null,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "type": "PATH",
            "id": "16621dbb-a736-4888-a57a-3ecd53df784c",
            "operating_status": "ONLINE",
            "tags": ["test_tag"]
        }
    ]
}
POST
/v2/lbaas/l7policies/{l7policy_id}/rules

Create an L7 Rule

Creates a L7 rule.

This operation provisions a new L7 rule 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 L7 rule.

In the response, the L7 rule provisioning status is ACTIVE, PENDING_CREATE, or ERROR.

If the status is PENDING_CREATE, issue GET /v2/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id} to view the progress of the provisioning operation. When the L7 rule status changes to ACTIVE, the L7 rule 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.

All the rules associated with a given policy are logically ANDed together. A request must match all the policy’s rules to match the policy.

If you need to express a logical OR operation between rules, then do this by creating multiple policies with the same action.

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

503 - Service Unavailable

The service cannot handle the request right now.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

compare_type

body

string

The comparison type for the L7 rule. One of CONTAINS, ENDS_WITH, EQUAL_TO, REGEX, or STARTS_WITH.

invert (Optional)

body

boolean

When true the logic of the rule is inverted. For example, with invert true, equal to would become not equal to. Default is false.

key (Optional)

body

string

The key to use for the comparison. For example, the name of the cookie to evaluate.

l7policy_id

path

uuid

The ID of the L7 policy to query.

project_id (Optional)

body

string

The ID of the project owning this resource.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

type

body

string

The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, PATH, SSL_CONN_HAS_CERT, SSL_VERIFY_RESULT, or SSL_DN_FIELD.

value

body

string

The value to use for the comparison. For example, the file type to compare.

Request Example

{
    "rule": {
        "compare_type": "REGEX",
        "invert": false,
        "type": "PATH",
        "value": "/images*",
        "admin_state_up": true,
        "tags": ["test_tag"]
    }
}

Curl Example

curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"rule":{"compare_type":"REGEX","invert":false,"type":"PATH","value":"/images*","admin_state_up":true,"tags":["test_tag"]}}' http://198.51.100.10:9876/v2/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

compare_type

body

string

The comparison type for the L7 rule. One of CONTAINS, ENDS_WITH, EQUAL_TO, REGEX, or STARTS_WITH.

created_at

body

string

The UTC date and timestamp when the resource was created.

id

body

uuid

The ID of the L7 rule.

invert

body

boolean

When true the logic of the rule is inverted. For example, with invert true, equal to would become not equal to.

key

body

string

The key to use for the comparison. For example, the name of the cookie to evaluate.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

type

body

string

The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, PATH, SSL_CONN_HAS_CERT, SSL_VERIFY_RESULT, or SSL_DN_FIELD.

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

value

body

string

The value to use for the comparison. For example, the file type to compare.

Response Example

{
    "rule":
        {
            "created_at": "2017-06-27T15:52:27",
            "compare_type": "REGEX",
            "provisioning_status": "PENDING_CREATE",
            "invert": false,
            "admin_state_up": true,
            "updated_at": "2017-06-27T15:52:28",
            "value": "/images*",
            "key": null,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "type": "PATH",
            "id": "16621dbb-a736-4888-a57a-3ecd53df784c",
            "operating_status": "OFFLINE",
            "tags": ["test_tag"]
        }
}
GET
/v2/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id}

Show L7 Rule details

Shows the details of a L7 rule.

If you are not an administrative user and the L7 rule object does not belong to your project, the service returns the HTTP Forbidden (403) response code.

This operation does not require a request body.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

l7policy_id

path

uuid

The ID of the L7 policy to query.

l7rule_id

path

uuid

The ID of the L7 rule to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

compare_type

body

string

The comparison type for the L7 rule. One of CONTAINS, ENDS_WITH, EQUAL_TO, REGEX, or STARTS_WITH.

created_at

body

string

The UTC date and timestamp when the resource was created.

id

body

uuid

The ID of the L7 rule.

invert

body

boolean

When true the logic of the rule is inverted. For example, with invert true, equal to would become not equal to.

key

body

string

The key to use for the comparison. For example, the name of the cookie to evaluate.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

type

body

string

The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, PATH, SSL_CONN_HAS_CERT, SSL_VERIFY_RESULT, or SSL_DN_FIELD.

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

value

body

string

The value to use for the comparison. For example, the file type to compare.

Response Example

{
    "rule":
        {
            "created_at": "2017-06-27T15:52:27",
            "compare_type": "REGEX",
            "provisioning_status": "ACTIVE",
            "invert": false,
            "admin_state_up": true,
            "updated_at": "2017-06-27T15:52:28",
            "value": "/images*",
            "key": null,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "type": "PATH",
            "id": "16621dbb-a736-4888-a57a-3ecd53df784c",
            "operating_status": "ONLINE",
            "tags": ["test_tag"]
        }
}
PUT
/v2/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id}

Update a L7 Rule

Updates a L7 rule.

If the request is valid, the service returns the Accepted (202) response code. To confirm the update, check that the L7 rule provisioning status is ACTIVE. If the status is PENDING_UPDATE, use a GET operation to poll the L7 rule object for changes.

This operation returns the updated L7 rule object with the ACTIVE, PENDING_UPDATE, or ERROR provisioning status.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

admin_state_up (Optional)

body

boolean

The administrative state of the resource, which is up (true) or down (false). Default is true.

compare_type (Optional)

body

string

The comparison type for the L7 rule. One of CONTAINS, ENDS_WITH, EQUAL_TO, REGEX, or STARTS_WITH.

invert (Optional)

body

boolean

When true the logic of the rule is inverted. For example, with invert true, equal to would become not equal to. Default is false.

key (Optional)

body

string

The key to use for the comparison. For example, the name of the cookie to evaluate.

l7policy_id

path

uuid

The ID of the L7 policy to query.

l7rule_id

path

uuid

The ID of the L7 rule to query.

tags (Optional)

body

array

A list of simple strings assigned to the resource.

New in version 2.5

type (Optional)

body

string

The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, PATH, SSL_CONN_HAS_CERT, SSL_VERIFY_RESULT, or SSL_DN_FIELD.

value (Optional)

body

string

The value to use for the comparison. For example, the file type to compare.

Request Example

{
    "rule": {
        "compare_type": "REGEX",
        "invert": true,
        "type": "PATH",
        "value": "/images/special*",
        "admin_state_up": true,
        "tags": ["updated_tag"]
    }
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"rule":{"compare_type":"REGEX","invert":true,"type":"PATH","value":"/images/special*","admin_state_up":true,"tags":["updated_tag"]}}' http://198.51.100.10:9876/v2/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c

Response Parameters

Name

In

Type

Description

admin_state_up

body

boolean

The administrative state of the resource, which is up (true) or down (false).

compare_type

body

string

The comparison type for the L7 rule. One of CONTAINS, ENDS_WITH, EQUAL_TO, REGEX, or STARTS_WITH.

created_at

body

string

The UTC date and timestamp when the resource was created.

id

body

uuid

The ID of the L7 rule.

invert

body

boolean

When true the logic of the rule is inverted. For example, with invert true, equal to would become not equal to.

key

body

string

The key to use for the comparison. For example, the name of the cookie to evaluate.

operating_status

body

string

The operating status of the resource. See Operating Status Codes.

project_id

body

string

The ID of the project owning this resource.

provisioning_status

body

string

The provisioning status of the resource. See Provisioning Status Codes.

tags

body

array

A list of simple strings assigned to the resource.

New in version 2.5

type

body

string

The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, PATH, SSL_CONN_HAS_CERT, SSL_VERIFY_RESULT, or SSL_DN_FIELD.

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

value

body

string

The value to use for the comparison. For example, the file type to compare.

Response Example

{
    "rule":
        {
            "created_at": "2017-06-27T15:52:27",
            "compare_type": "REGEX",
            "provisioning_status": "PENDING_UPDATE",
            "invert": true,
            "admin_state_up": true,
            "updated_at": "2017-06-27T15:58:28",
            "value": "/images/special*",
            "key": null,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "type": "PATH",
            "id": "16621dbb-a736-4888-a57a-3ecd53df784c",
            "operating_status": "ONLINE",
            "tags": ["updated_tag"]
        }
}
DELETE
/v2/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id}

Remove a L7 Rule

Removes a L7 rule 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.

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

l7policy_id

path

uuid

The ID of the L7 policy to query.

l7rule_id

path

uuid

The ID of the L7 rule to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c

Response

There is no body content for the response of a successful DELETE request.

Quotas

GET
/v2/lbaas/quotas

List Quota

Lists all quotas 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 Filtering and column selection.

Administrative users can specify a project ID that is different than their own to list quotas for other projects.

If the quota is listed as null the quota is using the deployment default quota settings.

A quota of -1 means the quota is unlimited.

The list might be empty.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

project_id (Optional)

query

string

The ID of the project to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/quotas?project_id=e3cd678b11784734bc366148aa37580e

Response Parameters

Name

In

Type

Description

healthmonitor

body

integer

The configured health monitor quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

l7policy

body

integer

The configured l7policy quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

l7rule

body

integer

The configured l7rule quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

listener

body

integer

The configured listener quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

loadbalancer

body

integer

The configured load balancer quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

member

body

integer

The configured member quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

pool

body

integer

The configured pool quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

project_id

body

string

The ID of the project owning this resource.

Response Example

{
    "quotas": [
        {
            "loadbalancer": 5,
            "member": 50,
            "healthmonitor": -1,
            "listener": null,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "pool": null,
            "l7policy": 3,
            "l7rule": null
        }
    ]
}
GET
/v2/lbaas/quotas/defaults

Show Quota Defaults

Show the quota defaults configured for the deployment.

A quota of -1 means the quota is unlimited.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

There are no request parameters for the show quota defaults API.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/quotas/defaults

Response Parameters

Name

In

Type

Description

healthmonitor

body

integer

The configured health monitor quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

l7policy

body

integer

The configured l7policy quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

l7rule

body

integer

The configured l7rule quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

listener

body

integer

The configured listener quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

loadbalancer

body

integer

The configured load balancer quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

member

body

integer

The configured member quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

pool

body

integer

The configured pool quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

Response Example

{
    "quota": {
        "loadbalancer": 50,
        "listener": -1,
        "member": -1,
        "pool": -1,
        "healthmonitor": -1,
        "l7policy": -1,
        "l7rule": -1
    }
}
GET
/v2/lbaas/quotas/{project_id}

Show Project Quota

Show the quota 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 Filtering and column selection.

Administrative users can specify a project ID that is different than their own to show quota for other projects.

A quota of -1 means the quota is unlimited.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

project_id

path

string

The ID of the project to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/quotas/e3cd678b11784734bc366148aa37580e

Response Parameters

Name

In

Type

Description

healthmonitor

body

integer

The configured health monitor quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

l7policy

body

integer

The configured l7policy quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

l7rule

body

integer

The configured l7rule quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

listener

body

integer

The configured listener quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

loadbalancer

body

integer

The configured load balancer quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

member

body

integer

The configured member quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

pool

body

integer

The configured pool quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

Response Example

{
    "quota": {
        "loadbalancer": 5,
        "listener": -1,
        "member": 50,
        "pool": -1,
        "healthmonitor": -1,
        "l7policy": 20,
        "l7rule": -1
    }
}
PUT
/v2/lbaas/quotas/{project_id}

Update a Quota

Updates a quota for a project.

If the request is valid, the service returns the Accepted (202) response code.

This operation returns the updated quota object.

If the quota is specified as null the quota will use the deployment default quota settings.

Specifying a quota of -1 means the quota is unlimited.

Specifying a quota of 0 means the project cannot create any of the resource.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

healthmonitor (Optional)

body

integer

The configured health monitor quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

l7policy (Optional)

body

integer

The configured l7policy quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

l7rule (Optional)

body

integer

The configured l7rule quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

listener

body

integer

The configured listener quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

loadbalancer

body

integer

The configured load balancer quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

member

body

integer

The configured member quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

pool

body

integer

The configured pool quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

project_id

path

string

The ID of the project to query.

Request Example

{
    "quota": {
        "loadbalancer": 10,
        "listener": -1,
        "member": 50,
        "pool": -1,
        "healthmonitor": -1,
        "l7policy": 15,
        "l7rule": 25
    }
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"quota":{"loadbalancer":10,"listener":-1,"member":50,"pool":-1,"healthmonitor":-1,"l7policy":15,"l7rule":25}}' http://198.51.100.10:9876/v2/lbaas/quotas/e3cd678b11784734bc366148aa37580e

Response Parameters

Name

In

Type

Description

healthmonitor

body

integer

The configured health monitor quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

l7policy

body

integer

The configured l7policy quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

l7rule

body

integer

The configured l7rule quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

listener

body

integer

The configured listener quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

loadbalancer

body

integer

The configured load balancer quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

member

body

integer

The configured member quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

pool

body

integer

The configured pool quota limit. A setting of null means it is using the deployment default quota. A setting of -1 means unlimited.

Response Example

{
    "quota": {
        "loadbalancer": 10,
        "listener": -1,
        "member": 50,
        "pool": -1,
        "healthmonitor": -1,
        "l7policy": 15,
        "l7rule": 25
    }
}
DELETE
/v2/lbaas/quotas/{project_id}

Reset a Quota

Resets a project quota to use the deployment default quota.

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

project_id

path

string

The ID of the project to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/quotas/e3cd678b11784734bc366148aa37580e

Response

There is no body content for the response of a successful DELETE request.

Providers

GET
/v2/lbaas/providers

List Providers

Lists all enabled provider drivers.

Use the fields query parameter to control which fields are returned in the response body.

The list might be empty.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/providers

Response Parameters

Name

In

Type

Description

name

body

string

Provider name.

description

body

string

Provider description.

Response Example

{
    "providers": [
        {
            "name": "amphora",
            "description": "The Octavia Amphora driver."
        },
        {
            "name": "octavia",
            "description": "Deprecated alias of the Octavia Amphora driver."
        }
    ]
}
GET
/v2/lbaas/providers/{provider}/flavor_capabilities

Show Provider Flavor Capabilities

Shows the provider driver flavor capabilities. These are the features of the provider driver that can be configured in an Octavia flavor. This API returns a list of dictionaries with the name and description of each flavor capability of the provider.

The list might be empty and a provider driver may not implement this feature.

New in version 2.6

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

provider

path

string

The provider to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/providers/amphora/flavor_capabilities

Response Parameters

Name

In

Type

Description

flavor_capabilities

body

object

The provider flavor capabilities dictonary object.

name

body

string

The provider flavor capability name.

description

body

string

The provider flavor capability description.

Response Example

{
  "flavor_capabilities": [
    {
      "name": "loadbalancer_topology",
      "description": "The load balancer topology. One of: SINGLE - One amphora per load balancer. ACTIVE_STANDBY - Two amphora per load balancer."
    }
  ]
}
GET
/v2/lbaas/providers/{provider}/availability_zone_capabilities

Show Provider Availability Zone Capabilities

Shows the provider driver availability zone capabilities. These are the features of the provider driver that can be configured in an Octavia availability zone. This API returns a list of dictionaries with the name and description of each availability zone capability of the provider.

The list might be empty and a provider driver may not implement this feature.

New in version 2.14

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

provider

path

string

The provider to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/lbaas/providers/amphora/availability_zone_capabilities

Response Parameters

Name

In

Type

Description

availability_zone_capabilities

body

object

The provider availability zone capabilities dictonary object.

name

body

string

The provider availability zone capability name.

description

body

string

The provider availability zone capability description.

Response Example

{
  "availability_zone_capabilities": [
    {
      "name": "compute_zone",
      "description": "The compute availability zone."
    }
  ]
}

Flavors

GET
/v2.0/lbaas/flavors

List Flavors

List all available flavors.

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 Filtering and column selection.

The list might be empty.

New in version 2.6

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/flavors

Response Parameters

Name

In

Type

Description

description

body

string

A human-readable description for the resource.

enabled

body

boolean

If the resource is available for use.

flavor_profile_id

body

uuid

The ID of the flavor profile.

flavors

body

array

A list of flavor objects.

id

body

uuid

The ID of the flavor.

name

body

string

Human-readable name of the resource.

Response Example

{
    "flavors": [
        {
            "id": "8f94060c-8d5b-4472-9cfd-e8a2b909481d",
            "name": "Basic",
            "description": "A basic standalone Octavia load balancer.",
            "enabled": true,
            "flavor_profile_id": "5712097e-0092-45dc-bff0-ab68b61ad51a"
        }
    ]
}
POST
/v2.0/lbaas/flavors

Create Flavor

Creates a flavor.

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.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.6

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

description (Optional)

body

string

A human-readable description for the resource.

enabled (Optional)

body

boolean

If the resource is available for use. The default is True.

flavor

body

object

A flavor object.

flavor_profile_id

body

uuid

The ID of the flavor profile.

name

body

string

Human-readable name of the resource.

Request Example

{
    "flavor": {
        "name": "Basic",
        "description": "A basic standalone Octavia load balancer.",
        "enabled": true,
        "flavor_profile_id": "5712097e-0092-45dc-bff0-ab68b61ad51a"
    }
}

Curl Example

curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"flavor":{"name":"Basic","description":"A basic standalone Octavia load balancer.","enabled":true,"flavor_profile_id":"5712097e-0092-45dc-bff0-ab68b61ad51a"}}' http://198.51.100.10:9876/v2.0/lbaas/flavors

Response Parameters

Name

In

Type

Description

description

body

string

A human-readable description for the resource.

enabled

body

boolean

If the resource is available for use.

flavor_profile_id

body

uuid

The ID of the flavor profile.

flavor

body

object

A flavor object.

id

body

uuid

The ID of the flavor.

name

body

string

Human-readable name of the resource.

Response Example

{
    "flavor": {
            "id": "8f94060c-8d5b-4472-9cfd-e8a2b909481d",
            "name": "Basic",
            "description": "A basic standalone Octavia load balancer.",
            "enabled": true,
            "flavor_profile_id": "5712097e-0092-45dc-bff0-ab68b61ad51a"
    }
}
GET
/v2.0/lbaas/flavors/{flavor_id}

Show Flavor Details

Shows the details of a flavor.

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 Filtering and column selection.

This operation does not require a request body.

New in version 2.6

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

flavor_id

path

uuid

The ID of the flavor to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/flavors/8f94060c-8d5b-4472-9cfd-e8a2b909481d

Response Parameters

Name

In

Type

Description

description

body

string

A human-readable description for the resource.

enabled

body

boolean

If the resource is available for use.

flavor_profile_id

body

uuid

The ID of the flavor profile.

flavor

body

object

A flavor object.

id

body

uuid

The ID of the flavor.

name

body

string

Human-readable name of the resource.

Response Example

{
    "flavor": {
            "id": "8f94060c-8d5b-4472-9cfd-e8a2b909481d",
            "name": "Basic",
            "description": "A basic standalone Octavia load balancer.",
            "enabled": true,
            "flavor_profile_id": "5712097e-0092-45dc-bff0-ab68b61ad51a"
    }
}
PUT
/v2.0/lbaas/flavors/{flavor_id}

Update a Flavor

Update a flavor.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.6

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

description (Optional)

body

string

A human-readable description for the resource.

enabled (Optional)

body

boolean

If the resource is available for use. The default is True.

flavor

body

object

A flavor object.

flavor_id

path

uuid

The ID of the flavor to query.

name (Optional)

body

string

Human-readable name of the resource.

Request Example

{
    "flavor": {
        "name": "Basic",
        "description": "A basic standalone Octavia load balancer.",
        "enabled": false
    }
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"flavor":{"name":"Basic","description":"A basic standalone Octavia load balancer.","enabled":false}}' http://198.51.100.10:9876/v2.0/lbaas/flavors/8f94060c-8d5b-4472-9cfd-e8a2b909481d

Response Parameters

Name

In

Type

Description

description

body

string

A human-readable description for the resource.

enabled

body

boolean

If the resource is available for use.

flavor_profile_id

body

uuid

The ID of the flavor profile.

flavor

body

object

A flavor object.

id

body

uuid

The ID of the flavor.

name

body

string

Human-readable name of the resource.

Response Example

{
    "flavor": {
            "id": "8f94060c-8d5b-4472-9cfd-e8a2b909481d",
            "name": "Basic",
            "description": "A basic standalone Octavia load balancer.",
            "enabled": false,
            "flavor_profile_id": "5712097e-0092-45dc-bff0-ab68b61ad51a"
    }
}
DELETE
/v2.0/lbaas/flavors/{flavor_id}

Remove a Flavor

Remove a flavor and its associated configuration.

If any load balancers are using this flavor the service returns the HTTP Conflict (409) response code.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.6

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

flavor_id

path

uuid

The ID of the flavor to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/flavors/8f94060c-8d5b-4472-9cfd-e8a2b909481d

Response

There is no body content for the response of a successful DELETE request.

Flavor Profiles

GET
/v2.0/lbaas/flavorprofiles

List Flavor Profiles

List all available flavor profiles.

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 Filtering and column selection.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

The list might be empty.

New in version 2.6

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/flavorprofiles

Response Parameters

Name

In

Type

Description

flavor_data

body

string

The JSON string containing the flavor metadata.

flavorprofiles

body

array

A list of flavorprofile objects.

id

body

uuid

The ID of the flavor profile.

name

body

string

Human-readable name of the resource.

provider_name

body

string

Provider name.

Response Example

{
    "flavorprofiles": [
        {
            "id": "5712097e-0092-45dc-bff0-ab68b61ad51a",
            "name": "amphora-act-stdby",
            "provider_name": "amphora",
            "flavor_data": "{\"loadbalancer_topology\": \"ACTIVE_STANDBY\"}"
        }
    ]
}
POST
/v2.0/lbaas/flavorprofiles

Create Flavor Profile

Creates a flavor profile.

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.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.6

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

flavor_data

body

string

The JSON string containing the flavor metadata.

flavorprofile

body

object

A flavorprofile object.

name

body

string

Human-readable name of the resource.

provider_name

body

string

Provider name.

Request Example

{
    "flavorprofile":
        {
            "name": "amphora-act-stdby",
            "provider_name": "amphora",
            "flavor_data": "{\"loadbalancer_topology\": \"ACTIVE_STANDBY\"}"
        }
}

Curl Example

curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"flavorprofile":{"name":"amphora-act-stdby","provider_name":"amphora","flavor_data":"{\"loadbalancer_topology\": \"ACTIVE_STANDBY\"}"}}' http://198.51.100.10:9876/v2.0/lbaas/flavorprofiles

Response Parameters

Name

In

Type

Description

flavor_data

body

string

The JSON string containing the flavor metadata.

flavorprofile

body

object

A flavorprofile object.

id

body

uuid

The ID of the flavor profile.

name

body

string

Human-readable name of the resource.

provider_name

body

string

Provider name.

Response Example

{
    "flavorprofile":
        {
            "id": "5712097e-0092-45dc-bff0-ab68b61ad51a",
            "name": "amphora-act-stdby",
            "provider_name": "amphora",
            "flavor_data": "{\"loadbalancer_topology\": \"ACTIVE_STANDBY\"}"
        }
}
GET
/v2.0/lbaas/flavorprofiles/{flavorprofile_id}

Show Flavor Profile Details

Shows the details of a flavor profile.

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 Filtering and column selection.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

This operation does not require a request body.

New in version 2.6

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

flavorprofile_id

path

uuid

The ID of the flavor profile to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/flavorprofiles/5712097e-0092-45dc-bff0-ab68b61ad51a

Response Parameters

Name

In

Type

Description

flavor_data

body

string

The JSON string containing the flavor metadata.

flavorprofile

body

object

A flavorprofile object.

id

body

uuid

The ID of the flavor profile.

name

body

string

Human-readable name of the resource.

provider_name

body

string

Provider name.

Response Example

{
    "flavorprofile":
        {
            "id": "5712097e-0092-45dc-bff0-ab68b61ad51a",
            "name": "amphora-act-stdby",
            "provider_name": "amphora",
            "flavor_data": "{\"loadbalancer_topology\": \"ACTIVE_STANDBY\"}"
        }
}
PUT
/v2.0/lbaas/flavorprofiles/{flavorprofile_id}

Update a Flavor Profile

Update a flavor profile.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.6

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

flavor_data (Optional)

body

string

The JSON string containing the flavor metadata.

flavorprofile

body

object

A flavorprofile object.

flavorprofile_id

path

uuid

The ID of the flavor profile to query.

name (Optional)

body

string

Human-readable name of the resource.

provider_name (Optional)

body

string

Provider name.

Request Example

{
    "flavorprofile":
        {
            "name": "amphora-standalone",
            "provider_name": "amphora",
            "flavor_data": "{\"loadbalancer_topology\": \"SINGLE\"}"
        }
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"flavorprofile":{"name":"amphora-standalone","provider_name":"amphora","flavor_data":"{\"loadbalancer_topology\": \"SINGLE\"}"}}' http://198.51.100.10:9876/v2.0/lbaas/flavorprofiles/5712097e-0092-45dc-bff0-ab68b61ad51a

Response Parameters

Name

In

Type

Description

flavor_data

body

string

The JSON string containing the flavor metadata.

flavorprofile

body

object

A flavorprofile object.

id

body

uuid

The ID of the flavor profile.

name

body

string

Human-readable name of the resource.

provider_name

body

string

Provider name.

Response Example

{
    "flavorprofile":
        {
            "id": "5712097e-0092-45dc-bff0-ab68b61ad51a",
            "name": "amphora-standalone",
            "provider_name": "amphora",
            "flavor_data": "{\"loadbalancer_topology\": \"SINGLE\"}"
        }
}
DELETE
/v2.0/lbaas/flavorprofiles/{flavorprofile_id}

Remove a Flavor Profile

Remove a flavor profile and its associated configuration.

If any flavors using this flavor profile the service returns the HTTP Conflict (409) response code.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.6

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

flavorprofile_id

path

uuid

The ID of the flavor profile to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/flavorprofiles/5712097e-0092-45dc-bff0-ab68b61ad51a

Response

There is no body content for the response of a successful DELETE request.

Availability Zones

GET
/v2.0/lbaas/availabilityzones

List Availability Zones

List all available availability zones.

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 Filtering and column selection.

The list might be empty.

New in version 2.14

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/availabilityzones

Response Parameters

Name

In

Type

Description

description

body

string

A human-readable description for the resource.

enabled

body

boolean

If the resource is available for use.

availability_zone_profile_id

body

uuid

The ID of the availability zone profile.

availability_zones

body

array

A list of availability zone objects.

name

body

string

Human-readable name of the resource.

Response Example

{
    "availability_zones": [
        {
            "name": "my_az",
            "description": "My availability zone.",
            "enabled": true,
            "availability_zone_profile_id": "5712097e-0092-45dc-bff0-ab68b61ad51a"
        }
    ]
}
POST
/v2.0/lbaas/availabilityzones

Create Availability Zone

Creates an availability zone.

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.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.14

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

description (Optional)

body

string

A human-readable description for the resource.

enabled (Optional)

body

boolean

If the resource is available for use. The default is True.

availability_zone

body

object

An availability zone object.

availability_zone_profile_id

body

uuid

The ID of the availability zone profile.

name

body

string

Human-readable name of the resource.

Request Example

{
    "availability_zone": {
        "name": "my_az",
        "description": "My availability zone.",
        "enabled": true,
        "availability_zone_profile_id": "5712097e-0092-45dc-bff0-ab68b61ad51a"
    }
}

Curl Example

curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"availability_zone":{"name":"my_az","description":"My availability zone.","enabled":true,"availability_zone_profile_id":"5712097e-0092-45dc-bff0-ab68b61ad51a"}}' http://198.51.100.10:9876/v2.0/lbaas/availabilityzones

Response Parameters

Name

In

Type

Description

description

body

string

A human-readable description for the resource.

enabled

body

boolean

If the resource is available for use.

availability_zone_profile_id

body

uuid

The ID of the availability zone profile.

availability_zone

body

object

An availability zone object.

name

body

string

Human-readable name of the resource.

Response Example

{
    "availability_zone": {
        "name": "my_az",
        "description": "My availability zone.",
        "enabled": true,
        "availability_zone_profile_id": "5712097e-0092-45dc-bff0-ab68b61ad51a"
    }
}
GET
/v2.0/lbaas/availabilityzones/{availability_zone_name}

Show Availability Zone Details

Shows the details of an availability zone.

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 Filtering and column selection.

This operation does not require a request body.

New in version 2.14

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

availability_zone_name

path

string

The name of the availability zone to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/availabilityzones/my_az

Response Parameters

Name

In

Type

Description

description

body

string

A human-readable description for the resource.

enabled

body

boolean

If the resource is available for use.

availability_zone_profile_id

body

uuid

The ID of the availability zone profile.

availability_zone

body

object

An availability zone object.

name

body

string

Human-readable name of the resource.

Response Example

{
    "availability_zone": {
        "name": "my_az",
        "description": "My availability zone.",
        "enabled": true,
        "availability_zone_profile_id": "5712097e-0092-45dc-bff0-ab68b61ad51a"
    }
}
PUT
/v2.0/lbaas/availabilityzones/{availability_zone_name}

Update an Availability Zone

Update an availability zone.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.14

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

description (Optional)

body

string

A human-readable description for the resource.

enabled (Optional)

body

boolean

If the resource is available for use. The default is True.

availability_zone

body

object

An availability zone object.

availability_zone_name

path

string

The name of the availability zone to query.

Request Example

{
    "availability_zone": {
        "description": "My availability zone.",
        "enabled": false
    }
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"availability_zone":{"description":"My availability zone.","enabled":false}}' http://198.51.100.10:9876/v2.0/lbaas/availabilityzones/my_az

Response Parameters

Name

In

Type

Description

description

body

string

A human-readable description for the resource.

enabled

body

boolean

If the resource is available for use.

availability_zone_profile_id

body

uuid

The ID of the availability zone profile.

availability_zone

body

object

An availability zone object.

name

body

string

Human-readable name of the resource.

Response Example

{
    "availability_zone": {
        "name": "my_az",
        "description": "My availability zone.",
        "enabled": false,
        "availability_zone_profile_id": "5712097e-0092-45dc-bff0-ab68b61ad51a"
    }
}
DELETE
/v2.0/lbaas/availabilityzones/{availability_zone_name}

Remove an Availability Zone

Remove an availability zone and its associated configuration.

If any load balancers are using this availability zone the service returns the HTTP Conflict (409) response code.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.14

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

availability_zone_name

path

string

The name of the availability zone to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/availabilityzones/my_az

Response

There is no body content for the response of a successful DELETE request.

Availability Zone Profiles

GET
/v2.0/lbaas/availabilityzoneprofiles

List Availability Zone Profiles

List all available Availability Zone Profiles.

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 Filtering and column selection.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

The list might be empty.

New in version 2.14

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/availabilityzoneprofiles

Response Parameters

Name

In

Type

Description

availability_zone_data

body

string

The JSON string containing the availability zone metadata.

availability_zone_profiles

body

array

A list of availability zone profile objects.

id

body

uuid

The ID of the availability zone profile.

name

body

string

Human-readable name of the resource.

provider_name

body

string

Provider name.

Response Example

{
    "availability_zone_profiles": [
        {
            "id": "5712097e-0092-45dc-bff0-ab68b61ad51a",
            "name": "some_az",
            "provider_name": "amphora",
            "availability_zone_data": "{\"compute_zone\": \"az1\"}"
        }
    ]
}
POST
/v2.0/lbaas/availabilityzoneprofiles

Create Availability Zone Profile

Creates a Availability Zone Profile.

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.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.14

Success

Code

Reason

201 - Created

Request has been fulfilled and new resource created.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

availability_zone_data

body

string

The JSON string containing the availability zone metadata.

availability_zone_profile

body

object

An availability zone profile object.

name

body

string

Human-readable name of the resource.

provider_name

body

string

Provider name.

Request Example

{
    "availability_zone_profile":
        {
            "name": "some_az",
            "provider_name": "amphora",
            "availability_zone_data": "{\"compute_zone\": \"az1\"}"
        }
}

Curl Example

curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"availability_zone_profile":{"name":"some_az","provider_name":"amphora","availability_zone_data":"{\"compute_zone\": \"az1\"}"}}' http://198.51.100.10:9876/v2.0/lbaas/availabilityzoneprofiles

Response Parameters

Name

In

Type

Description

availability_zone_data

body

string

The JSON string containing the availability zone metadata.

availability_zone_profile

body

object

An availability zone profile object.

id

body

uuid

The ID of the availability zone profile.

name

body

string

Human-readable name of the resource.

provider_name

body

string

Provider name.

Response Example

{
    "availability_zone_profile":
        {
            "id": "5712097e-0092-45dc-bff0-ab68b61ad51a",
            "name": "some_az",
            "provider_name": "amphora",
            "availability_zone_data": "{\"compute_zone\": \"az1\"}"
        }
}
GET
/v2.0/lbaas/availabilityzoneprofiles/{availability_zone_profile_id}

Show Availability Zone Profile Details

Shows the details of a Availability Zone Profile.

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 Filtering and column selection.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

This operation does not require a request body.

New in version 2.14

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

availability_zone_profile_id

path

uuid

The ID of the availability zone profile to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/availabilityzoneprofiles/5712097e-0092-45dc-bff0-ab68b61ad51a

Response Parameters

Name

In

Type

Description

availability_zone_data

body

string

The JSON string containing the availability zone metadata.

availability_zone_profile

body

object

An availability zone profile object.

id

body

uuid

The ID of the availability zone profile.

name

body

string

Human-readable name of the resource.

provider_name

body

string

Provider name.

Response Example

{
    "availability_zone_profile":
        {
            "id": "5712097e-0092-45dc-bff0-ab68b61ad51a",
            "name": "some_az",
            "provider_name": "amphora",
            "availability_zone_data": "{\"compute_zone\": \"az1\"}"
        }
}
PUT
/v2.0/lbaas/availabilityzoneprofiles/{availability_zone_profile_id}

Update a Availability Zone Profile

Update a Availability Zone Profile.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.14

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

availability_zone_data (Optional)

body

string

The JSON string containing the availability zone metadata.

availability_zone_profile

body

object

An availability zone profile object.

availability_zone_profile_id

path

uuid

The ID of the availability zone profile to query.

name (Optional)

body

string

Human-readable name of the resource.

provider_name (Optional)

body

string

Provider name.

Request Example

{
    "availability_zone_profile":
        {
            "name": "other_az",
            "provider_name": "amphora",
            "availability_zone_data": "{\"compute_zone\": \"az2\"}"
        }
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"availability_zone_profile":{"name":"other_az","provider_name":"amphora","availability_zone_data":"{\"compute_zone\": \"az2\"}"}}' http://198.51.100.10:9876/v2.0/lbaas/availabilityzoneprofiles/5712097e-0092-45dc-bff0-ab68b61ad51a

Response Parameters

Name

In

Type

Description

availability_zone_data

body

string

The JSON string containing the availability zone metadata.

availability_zone_profile

body

object

An availability zone profile object.

id

body

uuid

The ID of the availability zone profile.

name

body

string

Human-readable name of the resource.

provider_name

body

string

Provider name.

Response Example

{
    "availability_zone_profile":
        {
            "id": "5712097e-0092-45dc-bff0-ab68b61ad51a",
            "name": "other_az",
            "provider_name": "amphora",
            "availability_zone_data": "{\"compute_zone\": \"az2\"}"
        }
}
DELETE
/v2.0/lbaas/availabilityzoneprofiles/{availability_zone_profile_id}

Remove a Availability Zone Profile

Remove a Availability Zone Profile and its associated configuration.

If any availability zone is using this Availability Zone Profile the service returns the HTTP Conflict (409) response code.

If you are not an administrative user the service returns the HTTP Forbidden (403) response code.

New in version 2.14

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

availability_zone_profile_id

path

uuid

The ID of the availability zone profile to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/availabilityzoneprofiles/5712097e-0092-45dc-bff0-ab68b61ad51a

Response

There is no body content for the response of a successful DELETE request.

Amphorae

GET
/v2/octavia/amphorae

List Amphora

Lists all amphora for the project.

If you are not an administrative user, the service returns the HTTP Forbidden (403) response code.

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 Filtering and column selection.

The list might be empty.

Note

The field cached_zone should be used for quick filtering and reference only, as it may out of date. If an up-to-date zone is vital, we recommend retrieving details directly from the compute service.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/octavia/amphorae?loadbalancer_id=09eedfc6-2c55-41a8-a75c-2cd4e95212ca

Response Parameters

Name

In

Type

Description

id

body

uuid

The associated amphora ID.

loadbalancer_id

body

uuid

The ID of the load balancer.

compute_id

body

uuid

The ID of the amphora resource in the compute system.

lb_network_ip

body

string

The management IP of the amphora.

vrrp_ip

body

string

The address of the vrrp port on the amphora.

ha_ip

body

string

The IP address of the Virtual IP (VIP).

vrrp_port_id

body

uuid

The vrrp port’s ID in the networking system.

ha_port_id

body

uuid

The ID of the Virtual IP (VIP) port.

cert_expiration

body

string

The date the certificate for the amphora expires.

cert_busy

body

string

Whether the certificate is in the process of being replaced.

role

body

string

The role of the amphora. One of STANDALONE, MASTER, BACKUP.

status

body

string

The status of the amphora. One of: BOOTING, ALLOCATED, READY, PENDING_CREATE, PENDING_DELETE, DELETED, ERROR.

vrrp_interface

body

string

The bound interface name of the vrrp port on the amphora.

vrrp_id

body

string

The vrrp group’s ID for the amphora.

vrrp_priority

body

string

The priority of the amphora in the vrrp group.

cached_zone

body

string

The availability zone of a compute instance, cached at create time. This is not guaranteed to be current. May be an empty-string if the compute service does not use zones.

created_at

body

string

The UTC date and timestamp when the resource was created.

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

image_id

body

uuid

The ID of the glance image used for the amphora.

New in version 2.1

compute_flavor

body

string

The ID of the compute flavor used for the amphora.

New in version 2.3

Response Example

{
    "amphorae": [
        {
            "id": "6bd55cd3-802e-447e-a518-1e74e23bb106",
            "load_balancer_id": "09eedfc6-2c55-41a8-a75c-2cd4e95212ca",
            "compute_id": "f0f79f90-733d-417a-8d70-cc6be62cd54d",
            "lb_network_ip": "192.168.1.2",
            "vrrp_ip": "192.168.1.5",
            "ha_ip": "192.168.1.10",
            "vrrp_port_id": "ab2a8add-76a9-44bb-89f8-88430193cc83",
            "ha_port_id": "19561fd3-5da5-46cc-bdd3-99bbdf7246e6",
            "cert_expiration": "2019-09-19 00:34:51",
            "cert_busy": 0,
            "role": "MASTER",
            "status": "ALLOCATED",
            "vrrp_interface": "eth1",
            "vrrp_id": 1,
            "vrrp_priority": 100,
            "cached_zone": "zone1",
            "created_at": "2017-05-10T18:14:44",
            "updated_at": "2017-05-10T23:08:12",
            "image_id": "c1c2ad6f-1c1e-4744-8d1a-d0ef36289e74",
            "compute_flavor": "5446a14a-abec-4455-bc0e-a34e5ff001a3"
        },
        {
            "id": "89c186a3-cb16-497b-b099-c4bd40316642",
            "load_balancer_id": "09eedfc6-2c55-41a8-a75c-2cd4e95212ca",
            "compute_id": "24b1cb54-122d-4960-9035-083642f5c2bb",
            "lb_network_ip": "192.168.1.3",
            "vrrp_ip": "192.168.1.6",
            "ha_ip": "192.168.1.10",
            "vrrp_port_id": "cae421f6-dcf0-4866-9438-d0c682645799",
            "ha_port_id": "19561fd3-5da5-46cc-bdd3-99bbdf7246e6",
            "cert_expiration": "2019-09-19 00:34:51",
            "cert_busy": 0,
            "role": "BACKUP",
            "status": "ALLOCATED",
            "vrrp_interface": "eth1",
            "vrrp_id": 1,
            "vrrp_priority": 200,
            "cached_zone": "zone2",
            "created_at": "2017-06-11T19:15:45",
            "updated_at": "2017-06-11T24:09:13",
            "image_id": "1014292d-cbaa-4ad6-b38b-2e138389f87f",
            "compute_flavor": "5446a14a-abec-4455-bc0e-a34e5ff001a3"
        }
    ]
}
GET
/v2/octavia/amphorae/{amphora_id}

Show Amphora details

Shows the details of an amphora.

If you are not an administrative user, the service returns the HTTP Forbidden (403) response code.

This operation does not require a request body.

Note

The field cached_zone should be used for quick filtering and reference only, as it may out of date. If an up-to-date zone is vital, we recommend retrieving details directly from the compute service.

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

amphora_id

path

uuid

The ID of the amphora to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/octavia/amphorae/6bd55cd3-802e-447e-a518-1e74e23bb106

Response Parameters

Name

In

Type

Description

id

body

uuid

The associated amphora ID.

loadbalancer_id

body

uuid

The ID of the load balancer.

compute_id

body

uuid

The ID of the amphora resource in the compute system.

lb_network_ip

body

string

The management IP of the amphora.

vrrp_ip

body

string

The address of the vrrp port on the amphora.

ha_ip

body

string

The IP address of the Virtual IP (VIP).

vrrp_port_id

body

uuid

The vrrp port’s ID in the networking system.

ha_port_id

body

uuid

The ID of the Virtual IP (VIP) port.

cert_expiration

body

string

The date the certificate for the amphora expires.

cert_busy

body

string

Whether the certificate is in the process of being replaced.

role

body

string

The role of the amphora. One of STANDALONE, MASTER, BACKUP.

status

body

string

The status of the amphora. One of: BOOTING, ALLOCATED, READY, PENDING_CREATE, PENDING_DELETE, DELETED, ERROR.

vrrp_interface

body

string

The bound interface name of the vrrp port on the amphora.

vrrp_id

body

string

The vrrp group’s ID for the amphora.

vrrp_priority

body

string

The priority of the amphora in the vrrp group.

cached_zone

body

string

The availability zone of a compute instance, cached at create time. This is not guaranteed to be current. May be an empty-string if the compute service does not use zones.

created_at

body

string

The UTC date and timestamp when the resource was created.

updated_at

body

string

The UTC date and timestamp when the resource was last updated.

image_id

body

uuid

The ID of the glance image used for the amphora.

New in version 2.1

compute_flavor

body

string

The ID of the compute flavor used for the amphora.

New in version 2.3

Response Example

{
    "amphora": {
        "id": "6bd55cd3-802e-447e-a518-1e74e23bb106",
        "load_balancer_id": "09eedfc6-2c55-41a8-a75c-2cd4e95212ca",
        "compute_id": "f0f79f90-733d-417a-8d70-cc6be62cd54d",
        "lb_network_ip": "192.168.1.2",
        "vrrp_ip": "192.168.1.5",
        "ha_ip": "192.168.1.10",
        "vrrp_port_id": "ab2a8add-76a9-44bb-89f8-88430193cc83",
        "ha_port_id": "19561fd3-5da5-46cc-bdd3-99bbdf7246e6",
        "cert_expiration": "2019-09-19 00:34:51",
        "cert_busy": 0,
        "role": "MASTER",
        "status": "ALLOCATED",
        "vrrp_interface": "eth1",
        "vrrp_id": 1,
        "vrrp_priority": 100,
        "cached_zone": "zone1",
        "created_at": "2017-05-10T18:14:44",
        "updated_at": "2017-05-10T23:08:12",
        "image_id": "c1c2ad6f-1c1e-4744-8d1a-d0ef36289e74",
        "compute_flavor": "5446a14a-abec-4455-bc0e-a34e5ff001a3"
    }
}
GET
/v2/octavia/amphorae/{amphora_id}/stats

Show Amphora Statistics

Show the statistics for an amphora.

If you are not an administrative user, the service returns the HTTP Forbidden (403) response code.

Use the fields query parameter to control which fields are returned in the response body.

New in version 2.3

Success

Code

Reason

200 - OK

Request was successful.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

amphora_id

path

uuid

The ID of the amphora to query.

fields (Optional)

query

string

The fields that you want the server to return. If no fields query parameter is specified, the octavia API returns all attributes allowed by the policy settings. By using the fields parameter, the API returns only the requested set of attributes. The fields parameter can be specified multiple times. For example, if you specify fields=id&fields=name in the request URL, only the id and name attributes will be returned.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/octavia/amphorae/63d8349e-c4d7-4156-bc94-29260607b04f/stats

Response Parameters

Name

In

Type

Description

active_connections

body

integer

The currently active connections.

amphora_stats

body

array

A list of amphora statistics objects, one per listener.

New in version 2.3

bytes_in

body

integer

The total bytes received.

bytes_out

body

integer

The total bytes sent.

id

body

uuid

The associated amphora ID.

listener_id

body

uuid

The ID of the listener.

loadbalancer_id

body

uuid

The ID of the load balancer.

request_errors

body

integer

The total requests that were unable to be fulfilled.

total_connections

body

integer

The total connections handled.

Response Example

{
    "amphora_stats": [
        {
            "active_connections": 48629,
            "bytes_in": 65671420,
            "bytes_out": 774771186,
            "id": "63d8349e-c4d7-4156-bc94-29260607b04f",
            "listener_id": "bbe44114-cda2-4fe0-b192-d9e24ce661db",
            "loadbalancer_id": "65b5a7c3-1437-4909-84cf-cec9f7e371ea",
            "request_errors": 0,
            "total_connections": 26189172
        },
        {
            "active_connections": 0,
            "bytes_in": 5,
            "bytes_out": 100,
            "id": "63d8349e-c4d7-4156-bc94-29260607b04f",
            "listener_id": "af45a658-4eeb-4ce9-8b7e-16b0e5676f87",
            "loadbalancer_id": "65b5a7c3-1437-4909-84cf-cec9f7e371ea",
            "request_errors": 0,
            "total_connections": 1
        }
    ]
}
PUT
/v2/octavia/amphorae/{amphora_id}/config

Configure Amphora

Update the amphora agent configuration. This will push the new configuration to the amphora agent and will update the configuration options that are mutatable.

If you are not an administrative user, the service returns the HTTP Forbidden (403) response code.

This operation does not require a request body.

New in version 2.7

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

amphora_id

path

uuid

The ID of the amphora to query.

Curl Example

curl -X PUT -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/octavia/amphorae/6bd55cd3-802e-447e-a518-1e74e23bb106/config

Response

There is no body content for the response of a successful PUT request.

PUT
/v2/octavia/amphorae/{amphora_id}/failover

Failover Amphora

Force an amphora to failover.

If you are not an administrative user, the service returns the HTTP Forbidden (403) response code.

This operation does not require a request body.

Success

Code

Reason

202 - Accepted

Request is accepted, but processing may take some time.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

amphora_id

path

uuid

The ID of the amphora to query.

Curl Example

curl -X PUT -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/octavia/amphorae/6bd55cd3-802e-447e-a518-1e74e23bb106/failover

Response

There is no body content for the response of a successful PUT request.

DELETE
/v2/octavia/amphorae/{amphora_id}

Remove an Amphora

Removes an amphora and its associated configuration.

The API immediately purges any and all configuration data, depending on the configuration settings. You cannot recover it.

New in version 2.20

Success

Code

Reason

204 - No Content

Request fulfilled but service does not return anything.

Error

Code

Reason

400 - Bad Request

Some content in the request was invalid.

401 - Unauthorized

Access is denied due to invalid credentials.

403 - Forbidden

Policy does not allow current user to do this operation.

404 - Not Found

The requested resource could not be found.

409 - Conflict

This resource has an action in progress that would conflict with this request.

500 - Internal Server Error

Something went wrong with the service which prevents it from fulfilling the request.

Request

Name

In

Type

Description

amphora_id

path

uuid

The ID of the amphora to query.

Curl Example

curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2/octavia/amphorae/1a032adb-d6ac-4dbb-a04a-c1126bc547c7

Response

There is no body content for the response of a successful DELETE request.