=================================
End-user / Cloud / Load Balancers
=================================

From this page you can manage load balancers.

.. warning::

    In order to be able to manage load balancers from Fleio the admin user needs to have ``load-balancer_admin`` and
    ``creator`` roles on user projects.

    For new projects Fleio can add these roles automatically if they are selected in ``Default role names`` dropdown on
    :ref:`OpenStack settings - Defaults<openstack-settings-defaults>` tab.

    For existing projects you will have to set these roles manually - see :ref:`upgrade-to-antelope` for an example of
    how to accomplish this.

.. contents::
    :depth: 3
    :local:
    :backlinks: none


Create new load balancer
========================

Creating a load balancer may take some time so you will have to wait a while until the load balancer becomes active.

To create a new load balancer you will have to fill up the following forms with details:

Load balancer details
~~~~~~~~~~~~~~~~~~~~~

This form will allow you to configure load balancer details.

.. image:: /_static/images/enduser/cloud/load-balancers/create-load-balancer-details.png
  :scale: 50

The following properties can be set for a new load balancer:

* Name - load balancer name
* Description - load balancer description
* IP address - virtual IP address for load balancer
* Availability zone - the availability zone for load balancer
* Flavor - the load balancer flavor
* Subnet (required) - subnet used to allocate virtual IP for load balancer
* Admin state up - check this to enable load balancer after create

Listener details
~~~~~~~~~~~~~~~~

This form will allow you to configure the listener that will be created for a new load balancer.

.. image:: /_static/images/enduser/cloud/load-balancers/create-listener-details.png
  :scale: 50

The following properties can be set for the listener:

* Name - listener name
* Description - listener description
* Protocol (required) - listener protocol, see below for details
* Port (required) - the port to listen on
* Client data timeout, TCP timeout, Member connect timeout, Member data timeout - various timeout in milliseconds - use
  0 for infinite
* Connection limit - number of concurrent connections - use -1 for infinite


Listener protocols
++++++++++++++++++

.. image:: /_static/images/enduser/cloud/load-balancers/create-listener-details-protocol.png

Currently we support the following listener protocols in Fleio: **TCP**, **HTTP**, **HTTPS**, **TERMINATED_HTTPS** and
**UPD**.

TERMINATED_HTTPS
++++++++++++++++

**TERMINATED_HTTPS** protocol will require user to store at least one valid TLS certificate in ``barbican`` and allow
``admin`` user to access it.

Certificates should be stored in ``PKCS#12`` format in ``barbican``. In order to convert a certificate to ``PKCS#12``
format you can use the following command:

.. code-block:: bash

    openssl pkcs12 -export -inkey cert.key -in cert.crt  -passout pass: -out cert.p12

Once the certificate is exported to ``PKCS#12`` format it can be added to ``barbican`` secret store using the following
command:

.. code-block:: bash

    openstack secret store --name='tls_secret' -t 'application/octet-stream' -e 'base64' --payload="$(base64 < cert.p12)"

and then add ACL for ``admin`` user:

.. code-block:: bash

    openstack secret list
    # copy ``Secret href`` of the secret you want to allow ``admin`` user to access
    openstack acl user add --user admin <secret href>  # use ``Secret href`` from above

.. note::

    If user cannot store secrets in barbican he will need to be granted ``creator`` role. Use the following command to
    grant a user creator role:

    .. code-block:: bash

        openstack role add --user <api user name> --project <user project id> creator


Pool details
~~~~~~~~~~~~

This form will allow you to configure the pool that will be created for a new load balancer.

.. image:: /_static/images/enduser/cloud/load-balancers/create-pool-details.png
  :scale: 50

The following properties can be set for the pool:

* Name - poll name
* Description - pool description
* Algorithm (required) - algorithm used by the pool to balance connection between pool members

Pool members
~~~~~~~~~~~~

This form will allow you to define pool members. The load balancer will balance connection between member defined here.

.. image:: /_static/images/enduser/cloud/load-balancers/create-pool-members.png
  :scale: 50

There are two types of pool members:

* external - specified by IP Address & port
* instance - an instance from user project can be selected and used as a pool member

Monitor details
~~~~~~~~~~~~~~~

This form will allow you to configure the health monitor that will be created for a new load balancer.

.. image:: /_static/images/enduser/cloud/load-balancers/create-monitor-details.png
  :scale: 50

The following properties can be set for the health monitor:

* Name - poll name
* Type - type of check to be used to determine if a pool member is down
* Max retries down - the number of retries until a pool member if considered down if the check fails
* Delay - number of seconds to wait between checks
* Max retries - the number of successful checks before a pool member is considered online
* Timeout - number of seconds after which a health check times out