openstack/octavia
Code Issues Proposed changes
76d88d2b94
octavia/doc/source/api/octaviaapi.rst
Trevor Vardeman 7d933da31e Add quota support to Octavia 
Octavia has no quota definitions, but needs them for parity with Neutron LBaaS.
This will provide an endpoint and support for retrieving, updating, and deleting
quotas for projects, as well as adding enforcement of those those quotas.

Adds scenario test that simply validates quotas in a lb graph.

Co-Authored-By: Michael Johnson <johnsomor@gmail.com>
Co-Authored-By: Phillip Toohill <phillip.toohill@rackspace.com>
Co-Authored-By: Adam Harwell <flux.adam@gmail.com>

Change-Id: Ia1d85dcd931a57a2fa3f6276d3fe6dabfeadd15e
Closes-Bug: #1596652
2017-01-13 02:45:14 +00:00

92 KiB
Raw Blame History

Octavia API

Authentication

Using the version 1 API

For the purpose of examples, assume there is an Octavia API server running at the URL http://octavia.example.com on the default port 80.

Note: Requests to update any resource on a load balancer in an immutable state will fail with a response code 409.

Available Statuses on Entities

Status type Statuses
Operating Status ONLINE, OFFLINE, DEGRADED, ERROR, NO_MONITOR
Provisioning Status ACTIVE, DELETED, ERROR, PENDING_DELETE, PENDING_UPDATE, PENDING_CREATE

Response Codes

  • 200 - The synchronous request was successful
  • 202 - The asynchronous request was accepted and is being processed
  • 400 - The request could not be understood
    • Example: Malformed JSON in request body
  • 401 - Unauthorized: Access is denied due to invalid credentials
  • 403 - The project is over quota for the request
  • 404 - The requested resource does not exist
  • 409 - The request has a conflict with existing resources
    • Example: Protocol for listener does not match protocol on pool
  • 500 - The request encountered an unexpected failure
  • 503 - The project is busy with other requests, try again later

Load Balancers

Fully Populated Load Balancer Object
Parameters | Type | Description

+=====================+============+====================================+ | id | UUID | Load Balancer ID | +---------------------+------------+------------------------------------+ | vip | VIP Object | JSON VIP object below | +---------------------+------------+------------------------------------+ | project_id | UUID | UUID for project | +---------------------+------------+------------------------------------+ | name | String | String for load balancer name | +---------------------+------------+------------------------------------+ | description | String | String detailing information | | | | about the load balancer | +---------------------+------------+------------------------------------+ | enabled | Boolean | Whether or not the load | | | | balancer should be online | | | | immediately | +---------------------+------------+------------------------------------+ | operating_status | String | Network status of a load balancer | +---------------------+------------+------------------------------------+ | provisioning_status | String | Physical status of a load balancer | +---------------------+------------+------------------------------------+

Virtual IP

The following table lists the attributes of a VIP. If only port_id is provided then the network_id will be populated. If only network_id is provided then a port will be created and the port_id will be returned. If an ip_address is provided then that IP will be attempted to be assigned to the VIP as long as port_id or network_id is provided as well.

Fully Populated VIP Object
Parameters | Type | Description

+========================+==========+==================================+ | ip_address | IPv(4 Frontend IP of load balancer | +------------------------+----------+----------------------------------+ | port_id | UUID | UUID for port | | | | (equivalent to neutron port) | +------------------------+----------+----------------------------------+ | network_id | UUID | UUID for network | | | | (equivalent to neutron subnet) | +------------------------+----------+----------------------------------+

List Load Balancers

Retrieve a list of load balancers.

Request Type GET
Endpoint URL/v1/loadbalancers
Response Codes +

Success | 200

---------+---------------------+

Error | 400, 401, 404, 500

Response Example:

[
    {
        "id": "bdd6532c-28ff-4ab9-b582-8b10f1ae5551",
        "vip": {
            "port_id": "f6c2fd2e-d9c2-404d-9886-759b034c04ad",
            "network_id": "e1a4880d-6d9f-4784-9a03-5cc7a81990a7",
            "ip_address": "192.0.2.1"
        },
        "name": "lb_name",
        "description": "lb_description",
        "enabled": true,
        "provisioning_status": "ACTIVE",
        "operating_status": "ONLINE"
    }
]

List Load Balancer Details

Retrieve details of a load balancer.

Request Type GET
Endpoint URL/v1/loadbalancers/{lb_id}
Response Codes +

Success | 200

---------+------------------------+

Error | 401, 404, 500

Response Example:

{
    "id": "ea200d0d-d3fd-4033-8a3c-e6fcd02bf288",
    "vip":{
        "port_id": "9d4b829b-10f6-4119-8cce-33e59e5016f8",
        "network_id": "5c124402-fe20-48c6-927f-1c0eda152449",
        "ip_address": "192.0.2.1"
    },
    "name": "lb_name",
    "description": "lb_description",
    "enabled": true,
    "provisioning_status": "ACTIVE",
    "operating_status": "ONLINE"
}

List Load Balancer Statistics

Retrieve the stats of a load balancer.

Request Type GET
Endpoint URL/v1/loadbalancers/{lb_id}/stats
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

{
    "loadbalancer": {
        "bytes_in": 0,
        "bytes_out": 0,
        "active_connections": 0,
        "total_connections": 0,
        "request_errors": 0,
        "listeners": [{
            "id": "9222e04d-5f40-441b-89ff-fdad75c91d51"
            "bytes_in": 0,
            "bytes_out": 0,
            "active_connections": 0,
            "total_connections": 0,
            "request_errors": 0,
        }]
    }
}

Create Load Balancer

Create a load balancer.

Request Type POST
Endpoint URL/v1/loadbalancers
Response Codes +

Success | 202

---------+------------------------------+

Error | 400, 401, 403, 404, 500, 503
Request Parameters
Parameters | Required

+=============+==========+ | vip | yes | +-------------+----------+ | project_id | no | +-------------+----------+ | name | no | +-------------+----------+ | description | no | +-------------+----------+ | enabled | no | +-------------+----------+

Request Example:

{
    "vip": {
        "subnet_id": "81c49c61-a655-4aa0-9af5-65bbe8347eb1"
    },
    "name": "lb_name",
    "description": "lb_description",
}

Response Example:

{
    "id": "98066b41-f328-412e-b7f5-e8cac8d8974f",
    "vip":{
        "port_id": "1f1716a1-997f-4bfe-a08d-9c895b6f206e",
        "subnet_id": "81c49c61-a655-4aa0-9af5-65bbe8347eb1",
        "ip_address": "192.0.2.1"
    },
    "name": "lb_name",
    "description": "lb_description",
    "enabled": true,
    "provisioning_status": "PENDING_CREATE",
    "operating_status": "OFFLINE"
}

Create Fully Populated Load Balancer

Create a load balancer including listeners, sni containers, pools, health monitors, l7 policies, and l7 rules.

Refer to the appropriate objects details for available attributes.

Request Example:

{
    "vip": {
        "subnet_id": "d144b932-9566-4871-bfb3-00ecda4816b1"
    },
    "name": "lb_name",
    "description": "lb_description",
    "listeners": [{
        "protocol": "HTTP",
        "protocol_port": 80,
        "connection_limit": 10,
        "name": "listener_name",
        "description": "listener_description",
        "enabled": true,
        "l7policies": [{
            "action": "REDIRECT_TO_POOL",
            "redirect_pool": {
                "protocol": "HTTP",
                "lb_algorithm": "ROUND_ROBIN",
                "session_persistence": {
                   "type": "HTTP_COOKIE",
                   "cookie_name": "cookie_name"
                },
                "name": "redirect_pool",
                "description": "redirect_pool_description",
                "enabled": true
            }
        }],
        "default_pool": {
            "protocol": "HTTP",
            "lb_algorithm": "ROUND_ROBIN",
            "session_persistence": {
               "type": "HTTP_COOKIE",
               "cookie_name": "cookie_name"
            },
            "name": "pool_name",
            "description": "pool_description",
            "enabled": true,
            "members": [{
                "ip_address": "10.0.0.1",
                "protocol_port": 80,
                "weight": 10,
                "subnet_id": "f3894f9d-e034-44bb-a966-dc6609956c6d",
                "enabled": true
            }],
            "health_monitor":{
                "type": "HTTP",
                "delay": 10,
                "timeout": 10,
                "fall_threshold": 10,
                "rise_threshold": 10,
                "http_method": "GET",
                "url_path": "/some/custom/path",
                "expected_codes": "200",
                "enabled": true
            }
        }
    }]
}

Response Example:

{
    "description": "lb_description",
    "provisioning_status": "PENDING_CREATE",
    "enabled": true,
    "listeners": [{
        "tls_certificate_id": null,
        "protocol": "HTTP",
        "description": "listener_description",
        "provisioning_status": "PENDING_CREATE",
        "default_pool": {
            "lb_algorithm": "ROUND_ROBIN",
            "protocol": "HTTP",
            "description": "pool_description",
            "health_monitor": {
                "project_id": "2020619d-e409-4277-8169-832de678f4e8",
                "expected_codes": "200",
                "enabled": true,
                "delay": 10,
                "fall_threshold": 10,
                "http_method": "GET",
                "rise_threshold": 10,
                "timeout": 10,
                "url_path": "/some/custom/path",
                "type": "HTTP"
            },
            "enabled": true,
            "session_persistence": {
                "cookie_name": "cookie_name",
                "type": "HTTP_COOKIE"
            },
            "members": [{
                "project_id": "2020619d-e409-4277-8169-832de678f4e8",
                "weight": 10,
                "subnet_id": "f3894f9d-e034-44bb-a966-dc6609956c6d",
                "enabled": true,
                "protocol_port": 80,
                "ip_address": "10.0.0.1",
                "id": "bd105645-e444-4dd4-b207-7b4270b980ef",
                "operating_status": "OFFLINE"
            }],
            "project_id": "2020619d-e409-4277-8169-832de678f4e8",
            "id": "49f1fbad-a9f8-434f-9e7f-41ed4bf330db",
            "operating_status": "OFFLINE",
            "name": "pool_name"
        },
        "connection_limit": 10,
        "enabled": true,
        "project_id": "2020619d-e409-4277-8169-832de678f4e8",
        "default_pool_id": "49f1fbad-a9f8-434f-9e7f-41ed4bf330db",
        "l7policies": [{
            "redirect_pool_id": "uuid",
            "description": null,
            "redirect_pool": {
                "lb_algorithm": "ROUND_ROBIN",
                "protocol": "HTTP",
                "description": "redirect_pool_description",
                "enabled": true,
                "session_persistence": {
                    "cookie_name": "cookie_name",
                    "type": "HTTP_COOKIE"
                },
                "members": [],
                "project_id": "2020619d-e409-4277-8169-832de678f4e8",
                "id": "49f1fbad-a9f8-434f-9e7f-41ed4bf330db",
                "operating_status": "OFFLINE",
                "name": "redirect_pool"
            },
            "l7rules": [],
            "enabled": true,
            "redirect_url": null,
            "action": "REDIRECT_TO_POOL",
            "position": 1,
            "id": "b69b041c-0fa7-4682-b04f-c0383178a9a7",
            "name": null
        }],
        "sni_containers": [],
        "protocol_port": 80,
        "id": "6249f94f-c936-4e69-9635-8f1b82c99d54",
        "operating_status": "OFFLINE",
        "name": "listener_name"
    }],
    "vip": {
        "subnet_id": "d144b932-9566-4871-bfb3-00ecda4816b1",
        "port_id": null,
        "ip_address": null
    },
    "project_id": "2020619d-e409-4277-8169-832de678f4e8",
    "id": "65e2ee4f-8aca-486a-88d4-0b9e7023795f",
    "operating_status": "OFFLINE",
    "name": "lb_name"
}

Update Load Balancer

Modify mutable fields of a load balancer.

Request Type PUT
Endpoint URL/v1/loadbalancers/{lb_id}
Response Codes +

Success | 202

---------+-------------------------+

Error | 400, 401, 404, 409, 500
Parameters Required
name no
description no
enabled no

Request Example:

{
    "name": "diff_lb_name",
    "description": "diff_lb_description",
    "enabled": false
}

Response Example:

{
    "id": "6853b957-4bc6-471c-8f50-aeee8a9533ec",
    "vip":{
        "port_id": "uuid",
        "network_id": "uuid",
        "ip_address": "192.0.2.1"
    },
    "name": "diff_lb_name",
    "description": "diff_lb_description",
    "enabled": true,
    "provisioning_status": "PENDING_CREATE",
    "operating_status": "OFFLINE"
}

Delete Load Balancer

Delete a load balancer.

Request Type DELETE
Endpoint URL/v1/loadbalancers/{lb_id}
Response Codes +

Success | 202

---------+------------------------+

Error | 401, 404, 409, 500

No request/response body

Delete Load Balancer Cascade

Delete a load balancer and all the underlying resources (e.g. listener, pool).

Request Type DELETE
Endpoint URL/v1/loadbalancers/{lb_id}/delete_cascade
Response Codes +

Success | 202

---------+---------------------------------------+

Error | 401, 404, 409, 500

No request/response body

Listeners

Fully Populated Listener Object
Parameters | Type | Description

+=====================+============+=====================================+ | id | UUID | Listener ID | +---------------------+------------+-------------------------------------+ | protocol | String | Network protocol from the | | | | following: TCP, HTTP, | | | | HTTPS | +---------------------+------------+-------------------------------------+ | protocol_port | UUID | Port the protocol will listen on | +---------------------+------------+-------------------------------------+ | connection_limit | String | Number of connections allowed at | | | | any given time | +---------------------+------------+-------------------------------------+ | default_tls | String | Barbican UUID for TLS container | | _container_id | | | +---------------------+------------+-------------------------------------+ | default_pool_id | UUID | UUID of the pool to which | | | | requests will be routed by default | +---------------------+------------+-------------------------------------+ | project_id | String | UUID for project | +---------------------+------------+-------------------------------------+ | name | String | String detailing the name of the | | | | listener | +---------------------+------------+-------------------------------------+ | description | String | String detailing information | | | | about the listener | +---------------------+------------+-------------------------------------+ | enabled | Boolean | Whether or not the listener | | | | should be online immediately | +---------------------+------------+-------------------------------------+ | operating_status | String | Network status of a listener | +---------------------+------------+-------------------------------------+ | provisioning_status | String | Physical status of a listener | +---------------------+------------+-------------------------------------+ | insert_headers | Dictionary | Dictionary of additional headers | | | | insertion into HTTP header | +---------------------+------------+-------------------------------------+

List Listeners

Retrieve a list of listeners.

Request Type GET
Endpoint URL/v1/loadbalancers/{lb_id}/listeners
Response Codes +

Success | 200

---------+----------------------------------+

Error | 401, 404, 500

Response Example:

[
    {
        "tls_certificate_id": null,
        "protocol": "HTTP",
        "description": "listener_description",
        "provisioning_status": "ACTIVE",
        "connection_limit": 10,
        "enabled": true,
        "sni_containers": [],
        "protocol_port": 80,
        "id": "0cc73a2d-8673-4476-bc02-8d7e1f9b7f07",
        "operating_status": "ONLINE",
        "name": "listener_name",
        "default_pool_id": "6c32713a-de18-45a5-b547-63740ec20efb"
    }
］

List Listener Details

Retrieve details of a listener.

Request Type GET
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}
Response Codes +

Success | 200

---------+------------------------------------------------+

Error | 401, 404, 500

Response Example:

{
     "tls_certificate_id": null,
     "protocol": "HTTP",
     "description": "listener_description",
     "provisioning_status": "ACTIVE",
     "connection_limit": 10,
     "enabled": true,
     "sni_containers": [],
     "protocol_port": 80,
     "id": "uuid",
     "operating_status": "ONLINE",
     "name": "listener_name",
     "default_pool_id": "e195954b-78eb-45c2-8a9c-2acfe6a65368"
}

List Listener Statistics

Retrieve the stats of a listener.

Request Type GET
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/stats
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

{
    "listener": {
        "bytes_in": 1000,
        "bytes_out": 1000,
        "active_connections": 1,
        "total_connections": 1,
        "request_errors": 0
    }
}

Create Listener

Create a listener.

Request Type POST
Endpoint URL/v1/loadbalancers/{lb_id}/listeners
Response Codes +

Success | 202

---------+-----------------------------------+

Error | 400, 401, 403, 404, 409, 500, 503
Parameters Required
protocol yes
protocol_port yes
connection_limit no
default_tls_container_id no
project_id no
name no
description no
default_pool_id no
enabled no
insert_headers no

Request Example:

{
    "protocol": "HTTPS",
    "protocol_port": 88,
    "connection_limit": 10,
    "default_tls_container_id": "uuid",
    "name": "listener_name",
    "description": "listener_description",
    "default_pool_id": "c50bd338-dd67-41f8-ab97-fdb42ee9080b",
    "enabled": true,
    "insert_headers": {"X-Forwarded-For": "true", "X-Forwarded-Port": "true"}
}

Response Example:

{
     "tls_certificate_id": null,
     "protocol": "HTTPS",
     "description": "listener_description",
     "provisioning_status": "PENDING_CREATE",
     "connection_limit": 10,
     "enabled": true,
     "sni_containers": [],
     "protocol_port": 88,
     "id": "e4c463d7-f21e-4b82-b2fd-813656824d90",
     "operating_status": "OFFLINE",
     "name": "listener_name",
     "default_pool_id": "c50bd338-dd67-41f8-ab97-fdb42ee9080b"
}

Update Listener

Modify mutable fields of a listener.

Request Type PUT
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}
Response Codes +

Success | 202

---------+------------------------------------------------+

Error | 400, 401, 404, 409, 500
Parameters Required
protocol no
protocol_port no
connection_limit no
tls_certificate_id no
name no
description no
default_pool_id no
enabled no

Request Example:

{
    "protocol": "HTTPS",
    "protocol_port": 88,
    "connection_limit": 10,
    "tls_certificate_id": "af4783a7-1bae-4dc3-984a-1bdf98639ef1",
    "name": "listener_name",
    "description": "listener_description",
    "default_pool_id": "262d81d4-3672-4a63-beb9-0b851063d480",
    "enabled": true
}

Response Example:

{
    "tls_certificate_id": "af4783a7-1bae-4dc3-984a-1bdf98639ef1",
    "protocol": "HTTPS",
    "description": "listener_description",
    "provisioning_status": "ACTIVE",
    "connection_limit": 10,
    "enabled": true,
    "sni_containers": [],
    "protocol_port": 88,
    "id": "15d69c9b-c87c-4155-a88f-f8bbe4298590",
    "operating_status": "ONLINE",
    "name": "listener_name",
    "default_pool_id": "262d81d4-3672-4a63-beb9-0b851063d480"
}

Delete Listener

Delete a listener.

Request Type DELETE
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}
Response Codes +

Success | 202

---------+------------------------------------------------+

Error | 401, 404, 409, 500

No request/response body

Pools

Fully Populated Pool Object
Parameters | Type | Description

+=====================+===============+====================================+ | id | UUID | Pool ID | +---------------------+---------------+------------------------------------+ | protocol | String | Network protocol from the | | | | following: TCP, HTTP, | | | | HTTPS | +---------------------+---------------+------------------------------------+ | lb_algorithm | UUID | Load balancing algorithm from | | | | the following: | | | | LEAST_CONNECTIONS, | | | | SOURCE_IP, ROUND_ROBIN | +---------------------+---------------+------------------------------------+ | session_persistence | Session | JSON Session Persistence object | | | Persistence | (see below) | | | Object | | +---------------------+---------------+------------------------------------+ | name | String | String for pool name | +---------------------+---------------+------------------------------------+ | description | String | String detailing information | | | | about the pool | +---------------------+---------------+------------------------------------+ | enabled | Boolean | Whether or not the pool | | | | should be online immediately | +---------------------+---------------+------------------------------------+

Fully Populated Session Persistence Object
Parameters | Type | Description
type | String | Type of session persistence from the | | following: HTTP_COOKIE, SOURCE_IP
cookie_name | String | The name of the cookie. (Only | | required for HTTP_COOKIE)

List Pools

Retrieve a list of pools on a loadbalancer. This API endpoint will list all pools on a loadbalancer or optionally all the active pools on a listener, depending on whether the listener_id query string is appended below.

Request Type GET
Endpoints

URL/v1/loadbalancers/{lb_id}/pools[?listener_id={listener_id}]

DEPRECATED URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

[
   {
       "id": "520367bf-0b09-4b91-8a2a-9a5996503bdc",
       "protocol": "HTTP",
       "lb_algorithm": "ROUND_ROBIN",
       "session_persistence": {
            "type": "HTTP_COOKIE",
            "cookie_name": "cookie_name"
       },
       "name": "pool_name",
       "description": "pool_description",
       "enabled": true,
       "operating_status": "ONLINE"
   }
]

List Pool Details

Retrieve details of a pool.

Request Type GET
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

{
    "id": "46c1d8da-bb98-4922-8262-5b36dc11017f",
    "protocol": "HTTP",
    "lb_algorithm": "ROUND_ROBIN",
    "session_persistence": {
        "type": "HTTP_COOKIE",
        "cookie_name": "cookie_name"
    },
    "name": "pool_name",
    "description": "pool_description",
    "enabled": true,
    "operating_status": "ONLINE"
}

Create Pool

Create a pool.

Request Type POST
Endpoint

URL/v1/loadbalancers/{lb_id}/pools

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 403, 404, 500, 503
Parameters Required
protocol yes
lb_algorithm yes
session_persistence no
name no
description no
enabled no

Request Example:

{
    "protocol": "HTTP",
    "lb_algorithm": "ROUND_ROBIN",
    "session_persistence": {
       "type": "HTTP_COOKIE",
       "cookie_name": "cookie_name"
    },
    "name": "pool_name",
    "description": "pool_description",
    "enabled": true
}

Response Example:

{
    "lb_algorithm": "ROUND_ROBIN",
    "protocol": "HTTP",
    "description": "pool_description",
    "enabled": true,
    "session_persistence": {
        "cookie_name": "cookie_name",
        "type": "HTTP_COOKIE"
    },
    "id": "6ed2783b-2d87-488d-8452-9b5dfa804728",
    "operating_status": "OFFLINE",
    "name": "pool_name"
}

Update Pool

Modify mutable attributes of a pool.

Request Type PUT
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 404, 409, 500
Parameters Required
protocol no
lb_algorithm yes
session_persistence no
name no
description no
enabled no

Request Example:

{
    "protocol": "HTTP",
    "lb_algorithm": "ROUND_ROBIN",
    "session_persistence": {
        "type": "HTTP_COOKIE",
        "cookie_name": "cookie_name"
    },
    "name": "diff_pool_name",
    "description": "pool_description",
    "enabled": true
}

Response Example:

{
    "id": "44034c98-47c9-48b3-8648-2024eeafdb53",
    "protocol": "HTTP",
    "lb_algorithm": "ROUND_ROBIN",
    "session_persistence": {
        "type": "HTTP_COOKIE",
        "cookie_name": "cookie_name"
    },
    "name": "diff_pool_name",
    "description": "pool_description",
    "enabled": true,
    "operating_status": "ONLINE"
}

Delete Pool

Delete a pool.

Request Type DELETE
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 401, 404, 409, 500

No request/response body

Health Monitors

Fully Populated Health Monitor Object
Parameters | Type | Description

+================+=========+======================================+ | type | String | Type of health monitoring from | | | | the following: PING, TCP, | | | | HTTP, HTTPS | +----------------+---------+--------------------------------------+ | delay | Integer | Delay between health checks | +----------------+---------+--------------------------------------+ | timeout | Integer | Timeout to decide whether or not | | | | a health check fails | +----------------+---------+--------------------------------------+ | fall_threshold | Integer | Number of health checks that can | | | | fail before the pool member is | | | | moved from ONLINE to OFFLINE | +----------------+---------+--------------------------------------+ | rise_threshold | Integer | Number of health checks that can | | | | pass before the pool member is | | | | moved from OFFLINE to ONLINE | +----------------+---------+--------------------------------------+ | http_method | String | HTTP protocol method to use for | | | | the health check request | +----------------+---------+--------------------------------------+ | url_path | String | URL endpoint to hit for the | | | | health check request | +----------------+---------+--------------------------------------+ | expected_codes | String | Comma separated list of expected | | | | response codes during the health | | | | check | +----------------+---------+--------------------------------------+ | enabled | Boolean | Enable/Disable health monitoring | +----------------+---------+--------------------------------------+

List Health Monitor Details

Retrieve details of a health monitor.

Request Type GET
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}/healthmonitor

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}/healthmonitor
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

{
    "type": "HTTP",
    "delay": 10,
    "timeout": 10,
    "fall_threshold": 10,
    "rise_threshold": 10,
    "http_method": "GET",
    "url_path": "/some/custom/path",
    "expected_codes": "200",
    "enabled": true
}

Create Health Monitor

Create a health monitor.

Request Type POST
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}/healthmonitor

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}/healthmonitor
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 403, 404, 500, 503
Parameters Required
type yes
delay yes
timeout yes
fall_threshold yes
rise_threshold yes
http_method no
url_path no
expected_codes no
enabled no

Request Example:

{
    "type": "HTTP",
    "delay": 10,
    "timeout": 10,
    "fall_threshold": 10,
    "rise_threshold": 10,
    "http_method": "GET",
    "url_path": "/some/custom/path",
    "expected_codes": "200",
    "enabled": true
}

Response Example:

{
    "type": "HTTP",
    "delay": 10,
    "timeout": 10,
    "fall_threshold": 10,
    "rise_threshold": 10,
    "http_method": "GET",
    "url_path": "/some/custom/path",
    "expected_codes": "200",
    "enabled": true
}

Update Health Monitor

Modify mutable attributes of a health monitor.

Request Type PUT
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}/healthmonitor

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}/healthmonitor
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 404, 409, 500
Parameters Required
type no
delay no
timeout no
fall_threshold no
rise_threshold no
http_method no
url_path no
expected_codes no
enabled no

Request Example:

{
    "type": "HTTP",
    "delay": 10,
    "timeout": 10,
    "fall_threshold": 10,
    "rise_threshold": 10,
    "http_method": "GET",
    "url_path": "/some/custom/path",
    "expected_codes": "200",
    "enabled": true
}

Response Example:

{
    "type": "HTTP",
    "delay": 10,
    "timeout": 10,
    "fall_threshold": 10,
    "rise_threshold": 10,
    "http_method": "GET",
    "url_path": "/some/custom/path",
    "expected_codes": "200",
    "enabled": true
}

Delete Health Monitor

Delete a health monitor.

Request Type DELETE
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}/healthmonitor

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}/healthmonitor
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 401, 404, 409, 500

Pool Members

Fully Populated Pool Member Object
Parameters | Type | Description

+==================+=========+====================================+ | id | UUID | Pool member ID | +------------------+---------+------------------------------------+ | ip_address | String | IP address of the pool member | +------------------+---------+------------------------------------+ | protocol_port | String | Port for the protocol to listen on | +------------------+---------+------------------------------------+ | weight | String | Weight of the pool member | +------------------+---------+------------------------------------+ | subnet_id | UUID | UUID of the subnet this pool | | | | member lives on | +------------------+---------+------------------------------------+ | enabled | Boolean | Whether or not the pool member | | | | should be online immediately | +------------------+---------+------------------------------------+ | operating_status | String | Network status of the pool member | +------------------+---------+------------------------------------+

List Members

Retrieve a list of pool members.

Request Type GET
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}/members

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}/members
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

[
   {
      "id": "8b8056dc-89ff-4d08-aa5d-6f8d6c2a44ec",
      "ip_address": "10.0.0.1",
      "protocol_port": 80,
      "weight": 10,
      "subnet_id": "6fd8cb41-f56d-49f0-bf19-db3dbf3191dc",
      "enabled": true,
      "operating_status": "ONLINE"
   }
]

List Member Details

Retrieve details of a pool member.

Request Type GET
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}/members/{member_id}

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}/members/{member_id}
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

{
    "id": "1caf31b6-e36d-4664-959f-472c51c37439",
    "ip_address": "10.0.0.1",
    "protocol_port": 80,
    "weight": 10,
    "subnet_id": "9e58c7ae-9da2-45f2-9a2a-97e39d3ad69e",
    "enabled": true,
    "operating_status": "ONLINE"
}

Create Member

Create a pool member.

Request Type POST
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}/members

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}/members
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 403, 404, 500, 503
Parameters Required
ip_address yes
protocol_port yes
weight yes
subnet_id no
enabled no

Request Example:

{
    "ip_address": "10.0.0.1",
    "protocol_port": 80,
    "weight": 10,
    "subnet_id": "f9c3a146-a3e3-406d-9f38-e7cd1847a670",
    "enabled": true
}

Response Example:

{
    "id": "80b0841b-0ce9-403a-bfb3-391feb299cd5",
    "ip_address": "10.0.0.1",
    "protocol_port": 80,
    "weight": 10,
    "subnet_id": "f9c3a146-a3e3-406d-9f38-e7cd1847a670",
    "enabled": true,
    "operating_status": "ONLINE"
}

Update Member

Modify mutable attributes of a pool member.

Request Type PUT
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}/members/{member_id}

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}/members/{member_id}
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 404, 409, 500
Parameters Required
protocol_port no
weight no
enabled no

Request Example:

{
    "protocol_port": 80,
    "weight": 10,
    "enabled": true
}

Response Example:

{
    "id": "1e9fd5bb-3285-4346-b1c8-b13e08fdae57",
    "ip_address": "10.0.0.1",
    "protocol_port": 80,
    "weight": 10,
    "subnet_id": "c91661f3-3831-4799-9c2c-681554196d62",
    "enabled": true,
    "operating_status": "ONLINE"
}

Delete Member

Delete a pool member.

Request Type DELETE
Endpoint

URL/v1/loadbalancers/{lb_id}/pools/{pool_id}/members/{member_id}

DEPRECATED: URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/pools/{pool_id}/members/{member_id}
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 401, 404, 409, 500

Layer 7 Policies

Layer 7 policies can be used to alter the behavior of the load balancing service such that some action can be taken other than sending requests to the listener's default_pool. If a given request matches all the layer 7 rules associated with a layer 7 policy, that layer 7 policy's action will be taken instead of the default behavior.

Fully Populated L7Policy Object
Parameters | Type | Description

+==================+=============+=======================================+ | id | UUID | L7 Policy ID | +------------------+-------------+---------------------------------------+ | name | String | String detailing the name of the | | | | l7policy | +------------------+-------------+---------------------------------------+ | description | String | String detailing information | | | | about the l7policy | +------------------+-------------+---------------------------------------+ | action | String | What action to take if the l7policy | | | | is matched | +------------------+-------------+---------------------------------------+ | redirect_pool_id | UUID | ID of the pool to which requests | | | | should be sent if action is | | | | REDIRECT_TO_POOL | +------------------+-------------+---------------------------------------+ | redirect_url | String | URL to which requests should be | | | | redirected if action is | | | | REDIRECT_TO_URL | +------------------+-------------+---------------------------------------+ | position | Integer | Sequence number of this L7 Policy. | | | | L7 Policies are evaluated in order | | | | starting with 1. | +------------------+-------------+---------------------------------------+ | enabled | Boolean | Whether or not the l7policy | | | | should be online immediately | +------------------+-------------+---------------------------------------+

Layer 7 Policy actions

L7 policy action Description
REJECT Requests matching this policy will be blocked.
REDIRECT_TO_POOL Requests matching this policy will be sent to the pool referenced by redirect_pool_id
REDIRECT_TO_URL Requests matching this policy will be redirected to the URL referenced by redirect_url

List L7 Policies

Retrieve a list of layer 7 policies.

Request Type GET
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/l7policies
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

[
    {
        "id": "1aaf9f08-eb34-41f4-afaa-bf5a8f73635d",
        "name": "Policy Name",
        "description": "Policy Description",
        "action": "REDIRECT_TO_POOL",
        "redirect_pool_id": "bab7f36c-e931-4cc3-a19d-96707fbb0a92",
        "redirect_url": None,
        "position": 1,
        "enabled": True,
    },
    {
        "id": "b5e5c33b-a1fa-44fc-8890-b546af64cf55",
        "name": "Policy Name 2",
        "description": "Policy Description 2",
        "action": "REDIRECT_TO_URL",
        "redirect_pool_id": None,
        "redirect_url": "http://www.example.com",
        "position": 2,
        "enabled": True,
    }
]

List L7 Policy Details

Retrieve details of a layer 7 policy.

Request Type GET
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/l7policies/{l7policy_id}
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

{
    "id": "6d6ebf41-d492-4eff-b392-f8099feb23b6",
    "name": "Policy Name",
    "description": "Policy Description",
    "action": "REDIRECT_TO_POOL",
    "redirect_pool_id": "3295874d-ed51-4c4d-9876-350591946713",
    "redirect_url": None,
    "position": 1,
    "enabled": True,
}

Create Layer 7 Policy

Create a layer 7 policy.

Request Type POST
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/l7policies
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 404, 500
Parameters Required
name no
description no
action yes
redirect_pool_id only if action == REDIRECT_TO_POOL
redirect_url only if action == REDIRECT_TO_URL
position no (defaults to append to list)
enabled no (defaults to True)

Request Example:

{
    "action": "REDIRECT_TO_POOL",
    "redirect_pool_id": "341c0015-d7ed-44a6-a5e4-b1af94094f7b"
}

Response Example:

{
    "id": "23d24092-fe03-42b5-8ff4-c500767468d6",
    "name": None,
    "description": None,
    "action": "REDIRECT_TO_POOL",
    "redirect_pool_id": "341c0015-d7ed-44a6-a5e4-b1af94094f7b",
    "redirect_url": None,
    "position": 1,
    "enabled": True
}

Update Layer 7 Policy

Modify mutable attributes of a layer 7 policy.

Request Type PUT
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/l7policies/{l7policy_id}
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 404, 409, 500
Parameters Required
name no
description no
action no
redirect_pool_id only if action == REDIRECT_TO_POOL
redirect_url only if action == REDIRECT_TO_URL
position no
enabled no

Request Example:

{
    "action": "REDIRECT_TO_URL",
    "redirect_url": "http://www.example.com",
    "enabled": True
}

Response Example:

{
    "id": "58caa7ac-6cdc-4778-957a-17ed208355ed",
    "name": None,
    "description": None,
    "action": "REDIRECT_TO_URL",
    "redirect_pool_id": None,
    "redirect_url": "http://www.example.com",
    "position": 1,
    "enabled": True
}

Delete Layer 7 Policy

Delete a layer 7 policy.

Request Type DELETE
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/l7policies/{l7policy_id}
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 401, 404, 409, 500

Layer 7 Rules

Layer 7 rules are individual statements of logic which match parts of an HTTP request, session, or other protocol-specific data for any given client request. All the layer 7 rules associated with a given layer 7 policy are logically ANDed together to see whether the policy matches a given client request. If logical OR behavior is desired instead, the user should instead create multiple layer 7 policies with rules which match each of the components of the logical OR statement.

Fully Populated L7Rule Object
Parameters | Type | Description

+==================+=============+=======================================+ | id | UUID | L7 Rule ID | +------------------+-------------+---------------------------------------+ | type | String | type of L7 rule (see chart below) | +------------------+-------------+---------------------------------------+ | compare_type | String | comparison type to be used with the | | | | value in this L7 rule (see chart | | | | below) | +------------------+-------------+---------------------------------------+ | key | String | Header or cookie name to match if | | | | rule type is HEADER or COOKIE | +------------------+-------------+---------------------------------------+ | value | String | value to be compared with | +------------------+-------------+---------------------------------------+ | invert | Boolean | inverts the logic of the rule if | | | | True (ie. perform a logical NOT | | | | on the rule) | +------------------+-------------+---------------------------------------+

Layer 7 rule types

L7 rule type Description Valid comparisons
HOST_NAME Matches against the http Host: header in the request. REGEX, STARTS_WITH, ENDS_WITH, CONTAINS, EQUAL_TO
PATH Matches against the path portion of the URL requested REGEX, STARTS_WITH, ENDS_WITH, CONTAINS, EQUAL_TO
FILE_TYPE Matches against the file name extension in the URL requested REGEX, EQUAL_TO
HEADER Matches against a specified header in the request REGEX, STARTS_WITH, ENDS_WITH, CONTAINS, EQUAL_TO
COOKIE Matches against a specified cookie in the request REGEX, STARTS_WITH, ENDS_WITH, CONTAINS, EQUAL_TO

Layer 7 rule comparison types

L7 rule compare type Description
REGEX string will be evaluated against regular expression stored in value
STARTS_WITH start of string will be compared against value
ENDS_WITH end of string will be compared against value
CONTAINS string contains value
EQUAL_TO string is exactly equal to value

List L7 Rules

Retrieve a list of layer 7 rules.

Request Type GET
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/l7policies/{l7policy_id} /l7rules
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

[
    {
        "id": "9986e669-6da6-4979-96bd-b901858bf463",
        "type": "PATH",
        "compare_type": "STARTS_WITH",
        "key": None,
        "value": "/api",
        "invert": False
    },
    {
        "id": "560b97d4-4239-4e4c-b51c-fd0afe387f99",
        "type": "COOKIE",
        "compare_type": "REGEX",
        "key": "my-cookie",
        "value": "some-value",
        "invert": True
    }
]

List L7 Rule Details

Retrieve details of a layer 7 rule.

Request Type GET
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/l7policies/{l7policy_id} /l7rules/{l7rule_id}
Response Codes +

Success | 200

---------+-------------------------------------------------+

Error | 401, 404, 500

Response Example:

{
    "id": "f19ff3aa-0d24-4749-a9ed-b5b93fad0a22",
    "type": "PATH",
    "compare_type": "STARTS_WITH",
    "key": None,
    "value": "/api",
    "invert": False
}

Create Layer 7 Rule

Create a layer 7 rule.

Request Type POST
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/l7policies/{l7policy_id} /l7rules
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 404, 500
Parameters Required
type yes
compare_type yes
key only if type is HEADER or COOKIE
value yes
invert no (Defaults to False)

Request Example:

{
    "type": "HOST_NAME",
    "compare_type": "ENDS_WITH",
    "value": ".example.com"
}

Response Example:

{
    "id": "27445155-c28d-4361-8158-9ff91d0eaba3",
    "type": "HOST_NAME",
    "compare_type": "ENDS_WITH",
    "key": None,
    "value": ".example.com",
    "invert": False
}

Update Layer 7 Rule

Modify mutable attributes of a layer 7 rule.

Request Type PUT
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/l7policies/{l7policy_id} /l7rules/{l7rule_id}
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 404, 409, 500
Parameters Required
type no
compare_type no
key only if type is HEADER or COOKIE
value no
invert no

Request Example:

{
    "type": "HEADER",
    "compare_type": "CONTAINS",
    "key": "X-My-Header",
    "value": "sample_substring"
}

Response Example:

{
    "id": "6f209661-a9b0-47ca-a60a-27154f9fe274",
    "type": "HEADER",
    "compare_type": "CONTAINS",
    "key": "X-My-Header",
    "value": "sample_substring",
    "invert": False
}

Delete Layer 7 Rule

Delete a layer 7 rule.

Request Type DELETE
Endpoint URL/v1/loadbalancers/{lb_id}/listeners/{listener_id}/l7policies/{l7policy_id} /l7rules/{l7rule_id}
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 401, 404, 409, 500

Quotas

Fully Populated Quotas Object
Parameters | Type | Description

+=====================+============+=====================================+ | project_id | UUID | Project ID | +---------------------+------------+-------------------------------------+ | health_monitor | Integer | Health Monitor quota | +---------------------+------------+-------------------------------------+ | listener | Integer | Listener quota | +---------------------+------------+-------------------------------------+ | load_balancer | Integer | Load balancer quota | +---------------------+------------+-------------------------------------+ | member | Integer | Member quota | +---------------------+------------+-------------------------------------+ | pool | Integer | Pool quota | +---------------------+------------+-------------------------------------+

Quotas specified as null will use the configured default quota.

Unlimited quotas are represented as -1.

List Quotas

List all non-default quotas.

Note: 'tenant_id' is deprecated and will be removed in a future release.

Use 'project_id' instead.

Request Type GET
Endpoint URL/v1/quotas
Response Codes +

Success | 200

---------+----------------------------------+

Error | 401, 500

Response Example:

{
    "quotas": [
        {
            "load_balancer": 10,
            "listener": 10,
            "health_monitor": 10,
            "tenant_id": "0c23c1e5-2fd3-4914-9b94-ab12d131a4fa",
            "member": 10,
            "project_id": "0c23c1e5-2fd3-4914-9b94-ab12d131a4fa",
            "pool": 10
        }, {
            "load_balancer": null,
            "listener": null,
            "health_monitor": 10,
            "tenant_id": "5df074f1-d173-4a69-b78c-31aeb54f4578",
            "member": null,
            "project_id": "5df074f1-d173-4a69-b78c-31aeb54f4578",
            "pool": null
        }
    ]
}

List Quota Defaults

List the currently configured quota defaults.

Request Type GET
Endpoint URL/v1/quotas/default
Response Codes +

Success | 200

---------+----------------------------------+

Error | 401, 500

Response Example:

{
    "quota": {
        "load_balancer": 20,
        "listener": -1,
        "member": -1,
        "pool": 10,
        "health_monitor": -1
    }
}

List Quota Details

Retrieve details of a project quota. If the project specified does not have custom quotas, the default quotas are returned.

Request Type GET
Endpoint URL/v1/quotas/{project_id}
Response Codes +

Success | 200

---------+----------------------------------+

Error | 401, 500

Response Example:

{
    "quota": {
        "load_balancer": 10,
        "listener": 10,
        "member": 10,
        "pool": 10,
        "health_monitor": 10
    }
}

Update Quota

Modify a project's quotas.

Request Type PUT
Endpoint URL/v1/quotas/{project_id}
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 400, 401, 500, 503

Request Example:

{
    "quota": {
        "load_balancer": -1,
        "listener": 10,
        "member": 10,
        "pool": 10,
        "health_monitor": null
    }
}

Response Example:

{
    "quota": {
        "load_balancer": -1,
        "listener": 10,
        "member": 10,
        "pool": 10,
        "health_monitor": 20
    }
}

Delete Quota

Delete a project's quota, reseting it to the configured default quotas.

Request Type DELETE
Endpoint URL/v1/quotas/{project_id}
Response Codes +

Success | 202

---------+-------------------------------------------------+

Error | 401, 404, 500, 503