From 543eb4bdfd8336c690bc10dbb3b986fd0e0a1c95 Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Thu, 18 Jun 2020 20:46:32 +0100
Subject: [PATCH] octavia: Add documentation
Covers manual registration of resources.
Change-Id: Idbee6ea1dba911cda38a0df307ed94e4ef98900d
Closes-Bug: #1877417
---
doc/source/conf.py | 1 +
doc/source/reference/networking/index.rst | 1 +
doc/source/reference/networking/octavia.rst | 198 ++++++++++++++++++++
3 files changed, 200 insertions(+)
create mode 100644 doc/source/reference/networking/octavia.rst
diff --git a/doc/source/conf.py b/doc/source/conf.py
index eef0b4c31b..f10c47e994 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -97,6 +97,7 @@ openstack_projects = [
'neutron-vpnaas',
'neutron',
'nova',
+ 'octavia',
'oslotest',
'swift',
]
diff --git a/doc/source/reference/networking/index.rst b/doc/source/reference/networking/index.rst
index f9a2b2f4d1..9ac34a0198 100644
--- a/doc/source/reference/networking/index.rst
+++ b/doc/source/reference/networking/index.rst
@@ -14,5 +14,6 @@ Networking-SFC, QoS, and so on.
dpdk
neutron
neutron-extensions
+ octavia
provider-networks
sriov
diff --git a/doc/source/reference/networking/octavia.rst b/doc/source/reference/networking/octavia.rst
new file mode 100644
index 0000000000..cb03a8a23d
--- /dev/null
+++ b/doc/source/reference/networking/octavia.rst
@@ -0,0 +1,198 @@
+=======
+Octavia
+=======
+
+Octavia provides load balancing as a service. This guide covers configuration
+of Octavia for the Amphora driver. See the :octavia-doc:`Octavia documentation
+<>` for full details. The :octavia-doc:`installation guide
+<install/install-ubuntu.html>` is a useful reference.
+
+Resources
+=========
+
+Currently in Kolla Ansible it is necessary to manually register the OpenStack
+resources required by Octavia. Kolla Ansible aims to automate this in the
+future.
+
+.. note::
+
+ In Train and earlier releases, resources should be registered in the
+ ``admin`` project. This is configured via ``octavia_service_auth_project``,
+ and may be set to ``service`` to avoid a breaking change when upgrading to
+ Ussuri. Changing the project on an existing system requires at a minimum
+ registering a new security group in the new project. Ideally the flavor and
+ network should be recreated in the new project, although this will impact
+ existing Amphorae.
+
+All resources should be registered in the ``service`` project. This can be done
+as follows:
+
+.. code-block:: console
+
+ source admin-openrc.sh
+ export OS_USERNAME=octavia
+ export OS_PASSWORD=<octavia keystone password>
+ export OS_PROJECT_NAME=service
+ export OS_TENANT_NAME=service
+
+You can find the Octavia password in ``passwords.yml``.
+
+Amphora image
+-------------
+
+It is necessary to build an Amphora image. On CentOS / RHEL 8:
+
+.. code-block:: console
+
+ sudo dnf -y install epel-release
+ sudo dnf install -y debootstrap
+
+On Ubuntu:
+
+.. code-block:: console
+
+ sudo apt -y install debootstrap
+
+Acquire the Octavia source code:
+
+.. code-block:: console
+
+ git clone https://opendev.org/openstack/octavia -b <branch>
+
+Install ``diskimage-builder``, ideally in a virtual environment:
+
+.. code-block:: console
+
+ python3 -m venv dib-venv
+ source dib-venv/bin/activate
+ pip install diskimage-builder
+
+Create the Amphora image:
+
+.. code-block:: console
+
+ cd octavia/diskimage-create
+ ./diskimage-create.sh
+
+Register the image in Glance:
+
+.. code-block:: console
+
+ openstack image create amphora-x64-haproxy.qcow2 --container-format bare --disk-format qcow2 --private --tag amphora --file amphora-x64-haproxy.qcow2
+
+Octavia uses the tag to determine which image to use.
+
+Amphora flavor
+--------------
+
+Register the flavor in Nova:
+
+.. code-block:: console
+
+ openstack flavor create --vcpus 1 --ram 1024 --disk 2 "amphora" --private
+
+Make a note of the ID of the flavor, or specify one via ``--id``.
+
+Keypair
+-------
+
+Register the keypair in Nova:
+
+.. code-block:: console
+
+ openstack keypair create --public-key <path to octavia public key> octavia_ssh_key
+
+Network and subnet
+------------------
+
+Register the management network and subnet in Neutron. This must be a network
+that is accessible from the controllers. Typically a VLAN provider network is
+used. In that case it will be necessary to enable Neutron provider networks.
+
+.. code-block:: console
+
+ OCTAVIA_MGMT_SUBNET=192.168.43.0/24
+ OCTAVIA_MGMT_SUBNET_START=192.168.43.10
+ OCTAVIA_MGMT_SUBNET_END=192.168.43.254
+
+ openstack network create lb-mgmt-net --provider-network-type vlan --provider-segment 107 --provider-physical-network physnet1
+ openstack subnet create --subnet-range $OCTAVIA_MGMT_SUBNET --allocation-pool \
+ start=$OCTAVIA_MGMT_SUBNET_START,end=$OCTAVIA_MGMT_SUBNET_END \
+ --network lb-mgmt-net lb-mgmt-subnet
+
+Make a note of the ID of the network.
+
+Security group
+--------------
+
+Register the security group in Neutron.
+
+.. code-block:: console
+
+ openstack security group create lb-mgmt-sec-grp
+ openstack security group rule create --protocol icmp lb-mgmt-sec-grp
+ openstack security group rule create --protocol tcp --dst-port 22 lb-mgmt-sec-grp
+ openstack security group rule create --protocol tcp --dst-port 9443 lb-mgmt-sec-grp
+
+Make a note of the ID of the security group.
+
+Kolla Ansible configuration
+===========================
+
+Globals
+-------
+
+The following options should be added to ``globals.yml``.
+
+Enable the Octavia service:
+
+.. code-block:: yaml
+
+ enable_octavia: yes
+
+If using a VLAN for the Octavia management network, enable Neutron provider
+networks:
+
+.. code-block:: yaml
+
+ enable_neutron_provider_networks: yes
+
+Configure the name of the network interface on the controllers used to access
+the Octavia management network. If using a VLAN provider network, ensure that
+the traffic is also bridged to Open vSwitch on the controllers.
+
+.. code-block:: yaml
+
+ octavia_network_interface: <network interface on controllers>
+
+Set the IDs of the resources registered previously:
+
+.. code-block:: yaml
+
+ octavia_amp_boot_network_list: <ID of lb-mgmt-net>
+ octavia_amp_secgroup_list: <ID of lb-mgmt-sec-grp>
+ octavia_amp_flavor_id: <ID of amphora flavor>
+
+Passwords
+---------
+
+The following option should be set in ``passwords.yml``, matching the password
+used to encrypt the CA key:
+
+.. code-block:: yaml
+
+ octavia_ca_password: <CA key password>
+
+Certificates
+============
+
+Follow the :octavia-doc:`octavia documentation
+<admin/guides/certificates.html>` to generate certificates for Amphorae. These
+should be copied to the Kolla Ansible configuration as follows:
+
+.. code-block:: ini
+
+ cp client_ca/certs/ca.cert.pem /etc/kolla/config/octavia/client_ca.cert.pem
+ cp server_ca/certs/ca.cert.pem /etc/kolla/config/octavia/server_ca.cert.pem
+ cp server_ca/private/ca.key.pem /etc/kolla/config/octavia/server_ca.key.pem
+ cp client_ca/private/client.cert-and-key.pem /etc/kolla/config/octavia/client.cert-and-key.pem