From 543eb4bdfd8336c690bc10dbb3b986fd0e0a1c95 Mon Sep 17 00:00:00 2001 From: Mark Goddard 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 +` 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= + 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 + +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 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: + +Set the IDs of the resources registered previously: + +.. code-block:: yaml + + octavia_amp_boot_network_list: + octavia_amp_secgroup_list: + octavia_amp_flavor_id: + +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: + +Certificates +============ + +Follow the :octavia-doc:`octavia documentation +` 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