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