OpenStack API Documentation

Octavia API v2.0 (Current)

General API Overview

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

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.0/lbaas/loadbalancers is http://198.51.100.10:9876/v2.0/lbaas/loadbalancers.

Depending on the deployment, the load-balancer endpoint URL might be http or https, a custom port, a custom path, and include your 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.0/lbaas/loadbalancers really means GET {your_load-balancer_endpoint_URL}/v2.0/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.0 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.0 supports JSON data serialization request and response formats only.

Request format

The Octavia API v2.0 only accepts requests with the JSON data serialization format. The Content-Type header is ignored.

Response format

The Octavia API v2.0 always responds with the JSON data serialization format. The Accept header is ignored.

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.0 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.0/lbaas/loadbalancers?name=foobar

When you specify multiple filters, the Octavia API v2.0 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.

By default, Octavia returns all attributes for any show or list call. The Octavia API v2.0 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.0.

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

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

Synchronous versus asynchronous plug-in behavior

The Octavia API v2.0 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.0 API does not support bulk create. You cannot create more than one load balancer per API call.

The Octavia v2.0 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.

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.0 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.0 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.0 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.0 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 occuring 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
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.

Load Balancers

GET
/v2.0/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.0/lbaas/loadbalancers?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.
description body string A human-readable description for the resource.
flavor body string The ID of the flavor.
id body string 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.
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 string The ID of the network for the Virtual IP (VIP).
vip_port_id body string The ID of the Virtual IP (VIP) port.
vip_subnet_id body string The ID of the subnet for the Virtual IP (VIP).

Response Example

{
    "loadbalancers": [
        {
            "description": "My favorite load balancer",
            "admin_state_up": true,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "provisioning_status": "ACTIVE",
            "flavor": "a7ae5d5a-d855-4f9a-b187-af66b53f4d04",
            "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",
            "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"
        }
    ]
}
POST
/v2.0/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.0/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.

There are three ways to specify a Virtual IP (VIP) network for the load balancer: provide a vip_port_id, supply a vip_subnet_id, or provide a vip_network_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. 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. Finally, when a vip_network_ip is specified octavia will select a subnet from the network, preferring IPv4 over IPv6 subnets.

An optional flavor 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.

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 and a provider will result in a conflict error.

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
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.
flavor (Optional) body string 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.
vip_address (Optional) body string The IP address of the Virtual IP (VIP).
vip_network_id (Optional) body string 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 string The ID of the Virtual IP (VIP) port. One of vip_network_id, vip_port_id, or vip_subnet_id must be specified.
vip_subnet_id (Optional) body string 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",
        "provider": "octavia",
        "name": "best_load_balancer"
    }
}

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": "a7ae5d5a-d855-4f9a-b187-af66b53f4d04", "vip_subnet_id": "d4af86e1-0051-488c-b7a0-527f97490c9a", "vip_address": "203.0.113.50", "provider": "octavia", "name": "best_load_balancer"}}' http://198.51.100.10:9876/v2.0/lbaas/loadbalancers

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.
description body string A human-readable description for the resource.
flavor body string The ID of the flavor.
id body string 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.
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 string The ID of the network for the Virtual IP (VIP).
vip_port_id body string The ID of the Virtual IP (VIP) port.
vip_subnet_id body string The ID of the subnet for the Virtual IP (VIP).

Response Example

{
    "loadbalancer": {
        "description": "My favorite load balancer",
        "admin_state_up": true,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "provisioning_status": "PENDING_CREATE",
        "flavor": "",
        "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",
        "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"
    }
}

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": "",
        "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"
                }
            },
            {
                "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"
    }
}

Response Example

{
    "loadbalancer": {
        "description": "My favorite load balancer",
        "admin_state_up": true,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "provisioning_status": "ACTIVE",
        "flavor": "",
        "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"
            },
            {
                "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",
        "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"
    }
}
GET
/v2.0/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 string 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.0/lbaas/loadbalancers/8a562351-f0fb-424c-a0af-513461424ea5

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.
description body string A human-readable description for the resource.
flavor body string The ID of the flavor.
id body string 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.
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 string The ID of the network for the Virtual IP (VIP).
vip_port_id body string The ID of the Virtual IP (VIP) port.
vip_subnet_id body string The ID of the subnet for the Virtual IP (VIP).

Response Example

{
    "loadbalancer": {
        "description": "My favorite load balancer",
        "admin_state_up": true,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "provisioning_status": "PENDING_CREATE",
        "flavor": "",
        "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",
        "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"
    }
}
PUT
/v2.0/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 string The ID of the load balancer to query.
name (Optional) body string Human-readable name of the resource.

Request Example

{
    "loadbalancer": {
        "description": "Temporarily disabled load balancer",
        "admin_state_up": false,
        "name": "disabled_load_balancer"
    }
}

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"}' http://198.51.100.10:9876/v2.0/lbaas/loadbalancers/8b6fc468-07d5-4d8b-a0b9-695060e72c31

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.
description body string A human-readable description for the resource.
flavor body string The ID of the flavor.
id body string 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.
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 string The ID of the network for the Virtual IP (VIP).
vip_port_id body string The ID of the Virtual IP (VIP) port.
vip_subnet_id body string The ID of the subnet for the Virtual IP (VIP).

Response Example

{
    "loadbalancer": {
        "description": "Temporarily disabled load balancer",
        "admin_state_up": false,
        "project_id": "e3cd678b11784734bc366148aa37580e",
        "provisioning_status": "PENDING_UPDATE",
        "flavor": "",
        "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",
        "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"
    }
}
DELETE
/v2.0/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 string 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.0/lbaas/loadbalancers/4b9b652c-537a-44bf-bbe8-85a690625597

Response

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

GET
/v2.0/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 string 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.0/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.0/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 string 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.0/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 string 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"
        }
    }
}

Listeners

GET
/v2.0/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.0/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).
connection_limit body integer The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections.
created_at body string The UTC date and timestamp when the resource was created.
default_pool_id body string The ID of the pool used by the listener if no L7 policies match.
default_tls_container_ref body string The URI to the key manager service secrets container containing the certificate and key for TERMINATED_TLS listeners.
description body string A human-readable description for the resource.
id body string 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 integer The protocol for the resource. One of HTTP, HTTPS, TCP, or TERMINATED_HTTPS.
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 containers containing the certificates and keys for TERMINATED_TLS the listener using Server Name Indication.
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"
        }
    ]
}
POST
/v2.0/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.0/lbaas/listeners/{listener_id} to view the progress of the provisioning operation. When the listener status changes to ACTIVE, the listener is successfully provisioned and is ready for further configuration.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

Specifying a project_id 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.
connection_limit (Optional) body integer The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections.
default_pool (Optional) body object A pool object.
default_pool_id (Optional) body string The ID of the pool used by the listener if no L7 policies match.
default_tls_container_ref (Optional) body string The URI to the key manager service secrets container containing the certificate and key for TERMINATED_TLS listeners.
description (Optional) body string A human-readable description for the resource.
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 string 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 integer The protocol for the resource. One of HTTP, HTTPS, TCP, or TERMINATED_HTTPS.
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 containers containing the certificates and keys for TERMINATED_TLS the listener using Server Name Indication.

Supported HTTP Header Insertions

Note

Both the key and the values are always specified as strings when specifying header insertions.

Key Value Description
X-Forwarded-For boolean When true a X-Forwarded-For header is inserted into the request to the backend member that specifies the client IP address.
X-Forwarded-Port integer A X-Forwarded-Port header is inserted into the request to the backend member that specifies the integer provided. Typically this is used to indicate the port the client connected to on the load balancer.

Request Example

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

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"]}}' http://198.51.100.10:9876/v2.0/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).
connection_limit body integer The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections.
created_at body string The UTC date and timestamp when the resource was created.
default_pool_id body string The ID of the pool used by the listener if no L7 policies match.
default_tls_container_ref body string The URI to the key manager service secrets container containing the certificate and key for TERMINATED_TLS listeners.
description body string A human-readable description for the resource.
id body string 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 integer The protocol for the resource. One of HTTP, HTTPS, TCP, or TERMINATED_HTTPS.
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 containers containing the certificates and keys for TERMINATED_TLS the listener using Server Name Indication.
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"
    }
}
GET
/v2.0/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 string The ID of the listener to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/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).
connection_limit body integer The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections.
created_at body string The UTC date and timestamp when the resource was created.
default_pool_id body string The ID of the pool used by the listener if no L7 policies match.
default_tls_container_ref body string The URI to the key manager service secrets container containing the certificate and key for TERMINATED_TLS listeners.
description body string A human-readable description for the resource.
id body string 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 integer The protocol for the resource. One of HTTP, HTTPS, TCP, or TERMINATED_HTTPS.
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 containers containing the certificates and keys for TERMINATED_TLS the listener using Server Name Indication.
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"
    }
}
PUT
/v2.0/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.
connection_limit (Optional) body integer The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections.
default_pool_id (Optional) body string The ID of the pool used by the listener if no L7 policies match.
default_tls_container_ref (Optional) body string The URI to the key manager service secrets container containing the certificate and key for TERMINATED_TLS listeners.
description (Optional) body string A human-readable description for the resource.
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 string 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 containers containing the certificates and keys for TERMINATED_TLS the listener using Server Name Indication.

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

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"]}}' http://198.51.100.10:9876/v2.0/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).
connection_limit body integer The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections.
created_at body string The UTC date and timestamp when the resource was created.
default_pool_id body string The ID of the pool used by the listener if no L7 policies match.
default_tls_container_ref body string The URI to the key manager service secrets container containing the certificate and key for TERMINATED_TLS listeners.
description body string A human-readable description for the resource.
id body string 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 integer The protocol for the resource. One of HTTP, HTTPS, TCP, or TERMINATED_HTTPS.
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 containers containing the certificates and keys for TERMINATED_TLS the listener using Server Name Indication.
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"
    }
}
DELETE
/v2.0/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 string The ID of the listener to query.

Curl Example

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

Response

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

GET
/v2.0/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 string The ID of the listener to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/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.0/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.0/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).
created_at body string The UTC date and timestamp when the resource was created.
description body string A human-readable description for the resource.
healthmonitor_id body string The associated health monitor ID.
id body string The ID of the pool.
lb_algorithm body string The load balancing algorithm for the pool. One of LEAST_CONNECTIONS, ROUND_ROBIN, or SOURCE_IP.
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, or TCP.
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.
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"
        }
    ]
}
POST
/v2.0/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.0/lbaas/pools/{pool_id} to view the progress of the provisioning operation. When the pool status changes to ACTIVE, the pool is successfully provisioned and is ready for further configuration.

At a minimum, you must specify these pool attributes:

  • protocol The protocol for which this pool and its members listen. A valid value is HTTP, HTTPS, PROXY, or TCP.

  • lb_algorithm The load-balancer algorithm, such as ROUND_ROBIN, LEAST_CONNECTIONS, and SOURCE_IP, that distributes traffic to the pool members. The load-balancer provider must support this algorithm.

  • listener_id The ID of the listener in which this pool becomes the default pool. Each listener has only one default pool.

    —OR—

  • loadbalancer_id The ID of the load balancer under which this pool will be created. Each load balancer can have zero or more pools associated with it. These pools can be used for L7policies.

Note

Either listener_id or loadbalancer_id must be specified.

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

  • admin_state_up Default is true.
  • name Default is an empty string.
  • description Default is an empty string.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

Specifying a project_id is deprecated. The pool will inherit the project_id of the parent load balancer.

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

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

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.
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, or SOURCE_IP.
listener_id (Optional) body string The ID of the listener for the pool. Either listener_id or loadbalancer_id must be specified.
loadbalancer_id (Optional) body string 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, or TCP.
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.

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, 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.
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"
    }
}

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"}}' http://198.51.100.10:9876/v2.0/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).
created_at body string The UTC date and timestamp when the resource was created.
description body string A human-readable description for the resource.
healthmonitor_id body string The associated health monitor ID.
id body string The ID of the pool.
lb_algorithm body string The load balancing algorithm for the pool. One of LEAST_CONNECTIONS, ROUND_ROBIN, or SOURCE_IP.
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, or TCP.
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.
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"
    }
}
GET
/v2.0/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 string The ID of the pool to query.

Curl Example

curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/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).
created_at body string The UTC date and timestamp when the resource was created.
description body string A human-readable description for the resource.
healthmonitor_id body string The associated health monitor ID.
id body string The ID of the pool.
lb_algorithm body string The load balancing algorithm for the pool. One of LEAST_CONNECTIONS, ROUND_ROBIN, or SOURCE_IP.
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, or TCP.
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.
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"
    }
}
PUT
/v2.0/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.
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 string 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.

Request Example

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

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"}}' http://198.51.100.10:9876/v2.0/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).
created_at body string The UTC date and timestamp when the resource was created.
description body string A human-readable description for the resource.
healthmonitor_id body string The associated health monitor ID.
id body string The ID of the pool.
lb_algorithm body string The load balancing algorithm for the pool. One of LEAST_CONNECTIONS, ROUND_ROBIN, or SOURCE_IP.
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, or TCP.
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.
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"
    }
}
DELETE
/v2.0/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 string The ID of the pool to query.

Curl Example

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

Response

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

Members

GET
/v2.0/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 string 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.0/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).
created_at body string The UTC date and timestamp when the resource was created.
id body string 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 string The subnet ID the member service is accessible from.
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,
            "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"
        }
    ]
}
POST
/v2.0/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.0/lbaas/pools/{pool_id}/members/{member_id} to view the progress of the provisioning operation. When the member status changes to ACTIVE, the member is successfully provisioned and is ready for further configuration.

If the API cannot fulfill the request due to insufficient data or data that is not valid, the service returns the HTTP Bad Request (400) response code with information about the failure in the response body. Validation errors require that you correct the error and submit the request again.

At a minimum, you must specify these member attributes:

  • address. The IP address of the backend member to receive traffic from the load balancer.
  • protocol_port The port on which the backend member listens for traffic.

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

  • admin_state_up. Default is true.
  • weight. Default is 1.

If you omit the subnet_id parameter, the vip_subnet_id for the parent load balancer will be used for the member subnet UUID.

The member address does not necessarily need to be a member of the subnet_id subnet. Members can be routable from the subnet specified either via the default route or by using host_routes defined on the subnet.

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

monitor_address and/or monitor_port can be used to have the health monitor, if one is configured for the pool, connect to an alternate IP address and port when executing a health check on the member.

To create a member, the load balancer must have an ACTIVE provisioning status.

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.
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 string 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 string The subnet ID the member service is accessible from.
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
    }
}

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}}' http://198.51.100.10:9876/v2.0/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).
created_at body string The UTC date and timestamp when the resource was created.
id body string 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 string The subnet ID the member service is accessible from.
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,
        "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"
    }
}
GET
/v2.0/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 string The ID of the member to query.
pool_id path string The ID of the pool to query.

Curl Example

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

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).
created_at body string The UTC date and timestamp when the resource was created.
id body string 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 string The subnet ID the member service is accessible from.
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,
        "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"
    }
}
PUT
/v2.0/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.
member_id path string 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 string The ID of the pool to query.
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
    }
}

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}}' http://198.51.100.10:9876/v2.0/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).
created_at body string The UTC date and timestamp when the resource was created.
id body string 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 string The subnet ID the member service is accessible from.
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,
        "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"
    }
}
DELETE
/v2.0/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 string The ID of the member to query.
pool_id path string The ID of the pool to query.

Curl Example

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

Response

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

Health Monitor

GET
/v2.0/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.0/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.
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.
id body string 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 string 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.
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, TCP, or TLS-HELLO.
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"
        }
    ]
}
POST
/v2.0/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.0/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, TCP, or TLS-HELLO.

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.
  • 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.
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.
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 string The ID of the pool.
project_id (Optional) body string The ID of the project owning this resource. (deprecated)
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, TCP, or TLS-HELLO.
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
    }
}

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}}' http://198.51.100.10:9876/v2.0/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.
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.
id body string 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 string 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.
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, TCP, or TLS-HELLO.
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"
    }
}
GET
/v2.0/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 string 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.0/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.
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.
id body string 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 string 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.
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, TCP, or TLS-HELLO.
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"
    }
}
PUT
/v2.0/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.
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 string 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.
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.
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
    }
}

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}}' http://198.51.100.10:9876/v2.0/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.
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.
id body string 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 string 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.
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, TCP, or TLS-HELLO.
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"
    }
}
DELETE
/v2.0/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 string 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.0/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.0/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.0/lbaas/l7policies?project_id=e3cd678b11784734bc366148aa37580e

Response Parameters

Name In Type Description
action body string The L7 policy action. One of 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 string The ID of the L7 policy.
listener_id body string 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_pool_id body string Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL.
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.
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_pool_id": 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"
        }
    ]
}
POST
/v2.0/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.0/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.

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_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 string 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_pool_id (Optional) body string Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL.
redirect_url (Optional) body string Requests matching this policy will be redirected to this URL. Only valid if action is REDIRECT_TO_URL.

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",
        "name": "redirect-example.com",
        "action": "REDIRECT_TO_URL",
        "position": 1
    }
}

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_url":"http://www.example.com","name":"redirect-example.com","action":"REDIRECT_TO_URL","position":1}}' http://198.51.100.10:9876/v2.0/lbaas/l7policies

Response Parameters

Name In Type Description
action body string The L7 policy action. One of 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 string The ID of the L7 policy.
listener_id body string 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_pool_id body string Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL.
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.
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_pool_id": 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"
        }
    ]
}
GET
/v2.0/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 string 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.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd

Response Parameters

Name In Type Description
action body string The L7 policy action. One of 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 string The ID of the L7 policy.
listener_id body string 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_pool_id body string Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL.
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.
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_pool_id": 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"
        }
}
PUT
/v2.0/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_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 string 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_pool_id (Optional) body string Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL.
redirect_url (Optional) body string Requests matching this policy will be redirected to this URL. Only valid if action is REDIRECT_TO_URL.

Request Example

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

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_url":"http://images.example.com","name":"redirect-images.example.com","action":"REDIRECT_TO_URL","position":1}}' http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd

Response Parameters

Name In Type Description
action body string The L7 policy action. One of 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 string The ID of the L7 policy.
listener_id body string 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_pool_id body string Requests matching this policy will be redirected to the pool with this ID. Only valid if action is REDIRECT_TO_POOL.
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.
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_pool_id": 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"
        }
}
DELETE
/v2.0/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 string 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.0/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.0/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 string 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.0/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 string 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.
type body string The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, or PATH.
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"
        }
    ]
}
POST
/v2.0/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.0/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 string The ID of the L7 policy to query.
project_id (Optional) body string The ID of the project owning this resource.
type body string The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, or PATH.
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
    }
}

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}}' http://198.51.100.10:9876/v2.0/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 string 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.
type body string The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, or PATH.
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"
        }
}
GET
/v2.0/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 string The ID of the L7 policy to query.
l7rule_id path string 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.0/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 string 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.
type body string The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, or PATH.
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"
        }
}
PUT
/v2.0/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 string The ID of the L7 policy to query.
l7rule_id path string The ID of the L7 rule to query.
type (Optional) body string The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, or PATH.
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
    }
}

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}}' http://198.51.100.10:9876/v2.0/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 string 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.
type body string The L7 rule type. One of COOKIE, FILE_TYPE, HEADER, HOST_NAME, or PATH.
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"
        }
}
DELETE
/v2.0/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 string The ID of the L7 policy to query.
l7rule_id path string 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.0/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.0/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.0/lbaas/quotas?project_id=e3cd678b11784734bc366148aa37580e

Response Parameters

Name In Type Description
health_monitor 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.
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.
load_balancer 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": [
        {
            "load_balancer": 5,
            "member": 50,
            "health_monitor": -1,
            "listener": null,
            "project_id": "e3cd678b11784734bc366148aa37580e",
            "pool": null
        }
    ]
}
GET
/v2.0/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.0/lbaas/quotas/defaults

Response Parameters

Name In Type Description
health_monitor 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.
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.
load_balancer 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": {
        "load_balancer": 50,
        "listener": -1,
        "member": -1,
        "pool": -1,
        "health_monitor": -1
    }
}
GET
/v2.0/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.0/lbaas/quotas/e3cd678b11784734bc366148aa37580e

Response Parameters

Name In Type Description
health_monitor 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.
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.
load_balancer 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": {
        "load_balancer": 5,
        "listener": -1,
        "member": 50,
        "pool": -1,
        "health_monitor": -1
    }
}
PUT
/v2.0/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
health_monitor (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.
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.
load_balancer 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": {
        "load_balancer": 10,
        "listener": -1,
        "member": 50,
        "pool": -1,
        "health_monitor": -1
    }
}

Curl Example

curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"quota":{"load_balancer":10,"listener":-1,"member":50,"pool":-1,"health_monitor":-1}}' http://198.51.100.10:9876/v2.0/lbaas/quotas/e3cd678b11784734bc366148aa37580e

Response Parameters

Name In Type Description
health_monitor 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.
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.
load_balancer 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": {
        "load_balancer": 10,
        "listener": -1,
        "member": 50,
        "pool": -1,
        "health_monitor": -1
    }
}
DELETE
/v2.0/lbaas/quotas/{project_id}

Remove 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.0/lbaas/quotas/e3cd678b11784734bc366148aa37580e

Response

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

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.