octavia/api-ref/source/v2/loadbalancer.inc

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

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

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

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

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.