.. -*- rst -*-
List Load Balancers
===================
.. rest_method:: GET /v2/lbaas/loadbalancers
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 :ref:`filtering`.
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.
.. rest_status_code:: success ../http-status.yaml
- 200
.. rest_status_code:: error ../http-status.yaml
- 400
- 401
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- fields: fields
- project_id: project_id_query
Curl Example
------------
.. literalinclude:: examples/loadbalancers-list-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- additional_vips: additional_vips
- admin_state_up: admin_state_up
- availability_zone: availability-zone-name
- created_at: created_at
- description: description
- flavor_id: flavor-id
- id: loadbalancer-id
- listeners: listeners
- loadbalancers: loadbalancers
- name: name
- operating_status: operating_status
- pools: pools_ids
- project_id: project_id
- provider: provider
- provisioning_status: provisioning_status
- tags: tags
- updated_at: updated_at
- vip_address: vip_address
- vip_network_id: vip_network_id
- vip_port_id: vip_port_id
- vip_qos_policy_id: vip_qos_policy_id
- vip_subnet_id: vip_subnet_id
- vip_vnic_type: vip_vnic_type
Response Example
----------------
.. literalinclude:: examples/loadbalancers-list-response.json
:language: javascript
Create a Load Balancer
======================
.. rest_method:: POST /v2/lbaas/loadbalancers
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 :ref:`provisioning status<prov_status>` is
``ACTIVE``, ``PENDING_CREATE``, or ``ERROR``.
If the status is ``PENDING_CREATE``, issue GET
``/v2/lbaas/loadbalancers/{loadbalancer_id}`` to view the progress of
the provisioning operation. When the load balancer status changes
to ``ACTIVE``, the load balancer is successfully provisioned and
is ready for further configuration.
If the API cannot fulfill the request due to insufficient data or
data that is not valid, the service returns the HTTP ``Bad Request
(400)`` response code with information about the failure in the
response body. Validation errors require that you correct the error
and submit the request again.
Administrative users can specify a project ID that is different than
their own to create load balancers for other projects.
An optional ``flavor_id`` attribute can be used to create the load balancer
using a pre-configured octavia flavor. Flavors are created by the operator
to allow custom load balancer configurations, such as allocating more
memory for the load balancer.
An optional ``vip_qos_policy_id`` attribute from Neutron can be used to
apply QoS policies on a loadbalancer VIP, also could pass a 'null' value to
remove QoS policies.
You can also specify the ``provider`` attribute when you create a
load balancer. The ``provider`` attribute specifies which backend should
be used to create the load balancer. This could be the default provider
(``octavia``) or a vendor supplied ``provider`` if one has been installed.
Setting both a flavor_id and a provider will result in a conflict error if
the provider does not match the provider of the configured flavor profiles.
Specifying a Virtual IP (VIP) is mandatory. There are three ways to specify
a VIP network for the load balancer:
1. Provide a ``vip_port_id``.
Providing a neutron port ID for the ``vip_port_id`` tells
octavia to use this port for the VIP. Some port settings may be changed or
removed as required by octavia, but the IP address will be retained. If the
port has more than one subnet you must specify either the ``vip_subnet_id``
or ``vip_address`` to clarify which address should be used for the VIP.
2. Provide a ``vip_network_id``.
When a ``vip_network_ip`` is specified, unless neither ``vip_subnet_id``
nor ``vip_address`` is specified, octavia will select a subnet from
the network, preferring IPv4 over IPv6 subnets.
3. Provide a ``vip_subnet_id``.
Specifying a neutron subnet ID will tell octavia to create a neutron port
on this subnet and allocate an IP address from the subnet if the
``vip_address`` was not specified. If ``vip_address`` was specified,
octavia will attempt to allocate the ``vip_address`` from the subnet for
the VIP address.
Additional VIPs may also be specified in the ``additional_vips`` field, by
providing a list of JSON objects containing a ``subnet_id`` and optionally
an ``ip_address``. All additional subnets must be part of the same network
as the primary VIP.
.. rest_status_code:: success ../http-status.yaml
- 201
.. rest_status_code:: error ../http-status.yaml
- 400
- 401
- 403
- 404
- 500
- 503
Request
-------
.. rest_parameters:: ../parameters.yaml
- additional_vips: additional_vips
- admin_state_up: admin_state_up-default-optional
- availability_zone: availability-zone-name-optional
- description: description-optional
- flavor_id: flavor-id-optional
- listeners: listeners-optional
- loadbalancer: loadbalancer
- name: name-optional
- project_id: project_id-optional
- provider: provider-optional
- tags: tags-optional
- vip_address: vip_address-optional
- vip_network_id: vip_network_id-optional
- vip_port_id: vip_port_id-optional
- vip_qos_policy_id: vip_qos_policy_id-optional
- vip_subnet_id: vip_subnet_id-optional
Request Example
----------------
.. literalinclude:: examples/loadbalancer-create-request.json
:language: javascript
Curl Example
------------
.. literalinclude:: examples/loadbalancer-create-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- additional_vips: additional_vips
- admin_state_up: admin_state_up
- availability_zone: availability-zone-name
- created_at: created_at
- description: description
- flavor_id: flavor-id
- id: loadbalancer-id
- listeners: listeners
- loadbalancer: loadbalancer
- name: name
- operating_status: operating_status
- pools: pools_ids
- project_id: project_id
- provider: provider
- provisioning_status: provisioning_status
- tags: tags
- updated_at: updated_at
- vip_address: vip_address
- vip_network_id: vip_network_id
- vip_port_id: vip_port_id
- vip_qos_policy_id: vip_qos_policy_id
- vip_subnet_id: vip_subnet_id
- vip_vnic_type: vip_vnic_type
Response Example
----------------
.. literalinclude:: examples/loadbalancer-create-response.json
:language: javascript
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
---------------
.. literalinclude:: examples/loadbalancer-full-create-request.json
:language: javascript
Response Example
----------------
.. literalinclude:: examples/loadbalancer-full-create-response.json
:language: javascript
Show Load Balancer details
==========================
.. rest_method:: GET /v2/lbaas/loadbalancers/{loadbalancer_id}
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.
.. rest_status_code:: success ../http-status.yaml
- 200
.. rest_status_code:: error ../http-status.yaml
- 401
- 403
- 404
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- fields: fields
- loadbalancer_id: path-loadbalancer-id
Curl Example
------------
.. literalinclude:: examples/loadbalancer-show-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- additional_vips: additional_vips
- admin_state_up: admin_state_up
- availability_zone: availability-zone-name
- created_at: created_at
- description: description
- flavor_id: flavor-id
- id: loadbalancer-id
- loadbalancer: loadbalancer
- listeners: listeners
- name: name
- operating_status: operating_status
- pools: pools_ids
- project_id: project_id
- provider: provider
- provisioning_status: provisioning_status
- tags: tags
- updated_at: updated_at
- vip_address: vip_address
- vip_network_id: vip_network_id
- vip_port_id: vip_port_id
- vip_qos_policy_id: vip_qos_policy_id
- vip_subnet_id: vip_subnet_id
- vip_vnic_type: vip_vnic_type
Response Example
----------------
.. literalinclude:: examples/loadbalancer-show-response.json
:language: javascript
Update a Load Balancer
======================
.. rest_method:: PUT /v2/lbaas/loadbalancers/{loadbalancer_id}
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.
.. rest_status_code:: success ../http-status.yaml
- 202
.. rest_status_code:: error ../http-status.yaml
- 400
- 401
- 403
- 404
- 409
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- admin_state_up: admin_state_up-optional
- description: description-optional
- loadbalancer: loadbalancer
- loadbalancer_id: path-loadbalancer-id
- name: name-optional
- tags: tags-optional
- vip_qos_policy_id: vip_qos_policy_id-optional
Request Example
---------------
.. literalinclude:: examples/loadbalancer-update-request.json
:language: javascript
Curl Example
------------
.. literalinclude:: examples/loadbalancer-update-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- additional_vips: additional_vips
- admin_state_up: admin_state_up
- created_at: created_at
- description: description
- flavor_id: flavor-id
- id: loadbalancer-id
- listeners: listeners
- loadbalancer: loadbalancer
- name: name
- operating_status: operating_status
- pools: pools_ids
- project_id: project_id
- provider: provider
- provisioning_status: provisioning_status
- tags: tags
- updated_at: updated_at
- vip_address: vip_address
- vip_network_id: vip_network_id
- vip_port_id: vip_port_id
- vip_qos_policy_id: vip_qos_policy_id
- vip_subnet_id: vip_subnet_id
- vip_vnic_type: vip_vnic_type
Response Example
----------------
.. literalinclude:: examples/loadbalancer-update-response.json
:language: javascript
Remove a Load Balancer
======================
.. rest_method:: DELETE /v2/lbaas/loadbalancers/{loadbalancer_id}
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.
.. rest_status_code:: success ../http-status.yaml
- 204
.. rest_status_code:: error ../http-status.yaml
- 400
- 401
- 403
- 404
- 409
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- cascade: cascade-delete
- loadbalancer_id: path-loadbalancer-id
Curl Example
------------
.. literalinclude:: examples/loadbalancer-delete-curl
:language: bash
Response
--------
There is no body content for the response of a successful DELETE request.
Get Load Balancer statistics
============================
.. rest_method:: GET /v2/lbaas/loadbalancers/{loadbalancer_id}/stats
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.
.. rest_status_code:: success ../http-status.yaml
- 200
.. rest_status_code:: error ../http-status.yaml
- 401
- 403
- 404
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- loadbalancer_id: path-loadbalancer-id
Curl Example
------------
.. literalinclude:: examples/loadbalancer-stats-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- stats: stats
- active_connections: active_connections
- bytes_in: bytes_in
- bytes_out: bytes_out
- request_errors: request_errors
- total_connections: total_connections
Response Example
----------------
.. literalinclude:: examples/loadbalancer-stats-response.json
:language: javascript
Get the Load Balancer status tree
=================================
.. rest_method:: GET /v2/lbaas/loadbalancers/{loadbalancer_id}/status
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 :ref:`prov_status` for descriptions of the status codes.
``operating_status`` is the observed status of the resource.
See :ref:`op_status` 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.
.. rest_status_code:: success ../http-status.yaml
- 200
.. rest_status_code:: error ../http-status.yaml
- 401
- 403
- 404
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- loadbalancer_id: path-loadbalancer-id
Curl Example
------------
.. literalinclude:: examples/loadbalancer-status-curl
:language: bash
Response Parameters
-------------------
.. rest_parameters:: ../parameters.yaml
- action: action
- address: address
- healthmonitor: healthmonitor-status
- id: id
- l7policies: l7policies-status-object-list
- l7rules: l7rules-status-object-list
- listeners: listeners-status-object-list
- loadbalancer: loadbalancer-status
- members: members-status-object-list
- name: name
- operating_status: operating_status
- pools: pools-status-list
- protocol_port: protocol_port
- provisioning_status: provisioning_status
- statuses: statuses
- type: type
Response Example
----------------
.. literalinclude:: examples/loadbalancer-status-response.json
:language: javascript
Failover a load balancer
========================
.. rest_method:: PUT /v2/lbaas/loadbalancers/{loadbalancer_id}/failover
Performs a failover of a load balancer.
This operation is only available to users with load balancer administrative
rights.
.. rest_status_code:: success ../http-status.yaml
- 202
.. rest_status_code:: error ../http-status.yaml
- 401
- 403
- 404
- 409
- 500
Request
-------
.. rest_parameters:: ../parameters.yaml
- loadbalancer_id: path-loadbalancer-id
Curl Example
------------
.. literalinclude:: examples/loadbalancer-failover-curl
:language: bash
Response
--------
There is no body content for the response of a successful failover request.