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\|6)	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_container_id	String	Barbican `UUID` for TLS container
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 Persistence Object	JSON Session Persistence object (see below)
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

OpenStack

Octavia API¶

Authentication¶

Using the version 1 API¶

Available Statuses on Entities¶

Response Codes¶

Load Balancers¶

Virtual IP¶

List Load Balancers¶

List Load Balancer Details¶

List Load Balancer Statistics¶

Create Load Balancer¶

Create Fully Populated Load Balancer¶

Update Load Balancer¶

Delete Load Balancer¶

Delete Load Balancer Cascade¶

Listeners¶

List Listeners¶

List Listener Details¶

List Listener Statistics¶

Create Listener¶

Update Listener¶

Delete Listener¶

Pools¶

List Pools¶

List Pool Details¶

Create Pool¶

Update Pool¶

Delete Pool¶

Health Monitors¶

List Health Monitor Details¶

Create Health Monitor¶

Update Health Monitor¶

Delete Health Monitor¶

Pool Members¶

List Members¶

List Member Details¶

Create Member¶

Update Member¶

Delete Member¶

Layer 7 Policies¶

List L7 Policies¶

List L7 Policy Details¶

Create Layer 7 Policy¶

Update Layer 7 Policy¶

Delete Layer 7 Policy¶

Layer 7 Rules¶

List L7 Rules¶

List L7 Rule Details¶

Create Layer 7 Rule¶

Update Layer 7 Rule¶

Delete Layer 7 Rule¶

Quotas¶

List Quotas¶

List Quota Defaults¶

List Quota Details¶

Update Quota¶

Delete Quota¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search