openstack/octavia
Code Issues Proposed changes

Add install guide for Ubuntu

Browse Source 
This patch adds install guide for Ubuntu.

Co-Authored-By: Ajay Kumar <ajay.k@india.nec.com>
Change-Id: I30a16837fca8f1ddea2799dd7bd35ba4ebd7dbe8
This commit is contained in:
Hidekazu Nakamura 2019-07-26 01:07:40 +00:00
parent ba88441935
commit 26cbb93a9a
3 changed files with 526 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/install/index.rst
View File

@ -6,3 +6,4 @@ Octavia Installation
:maxdepth: 1
Installation overview guide <../contributor/guides/dev-quick-start>
install.rst

506
doc/source/install/install-ubuntu.rst Normal file
View File

@ -0,0 +1,506 @@
.. _install-ubuntu:
Install and configure for Ubuntu
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure the Load-balancer
service for Ubuntu 18.04 (LTS).
Prerequisites
-------------
Before you install and configure the service, you must create a database,
service credentials, and API endpoints.
1. Create the database, complete these steps:
* Use the database access client to connect to the database
server as the ``root`` user:
.. code-block:: console
# mysql
* Create the ``octavia`` database:
.. code-block:: console
CREATE DATABASE octavia;
* Grant proper access to the ``octavia`` database:
.. code-block:: console
GRANT ALL PRIVILEGES ON octavia.* TO 'octavia'@'localhost' \
IDENTIFIED BY 'OCTAVIA_DBPASS';
GRANT ALL PRIVILEGES ON octavia.* TO 'octavia'@'%' \
IDENTIFIED BY 'OCTAVIA_DBPASS';
Replace OCTAVIA_DBPASS with a suitable password.
* Exit the database access client.
.. code-block:: console
exit;
2. Source the ``admin`` credentials to gain access to admin-only CLI commands:
.. code-block:: console
$ . admin-openrc
3. To create the Octavia service credentials, complete these steps:
* Create the ``octavia`` user:
.. code-block:: console
$ openstack user create --domain default --password-prompt octavia
User Password:
Repeat User Password:
+---------------------+----------------------------------+
| Field | Value |
+---------------------+----------------------------------+
| domain_id | default |
| enabled | True |
| id | b18ee38e06034b748141beda8fc8bfad |
| name | octavia |
| options | {} |
| password_expires_at | None |
+---------------------+----------------------------------+
* Add the ``admin`` role to the ``octavia`` user:
.. code-block:: console
$ openstack role add --project service --user octavia admin
.. note::
This command produces no output.
.. note::
The Octavia service does not require the full admin role.
Details of how to run Octavia without the admin role will come in a future version of this document.
* Create the octavia service entities:
.. code-block:: console
$ openstack service create --name octavia --description "OpenStack Octavia" load-balancer
+-------------+----------------------------------+
| Field | Value |
+-------------+----------------------------------+
| description | OpenStack Octavia |
| enabled | True |
| id | d854f6fff0a64f77bda8003c8dedfada |
| name | octavia |
| type | load-balancer |
+-------------+----------------------------------+
4. Create the Load-balancer service API endpoints:
.. code-block:: console
$ openstack endpoint create --region RegionOne \
load-balancer public http://controller:9876
+--------------+----------------------------------+
| Field | Value |
+--------------+----------------------------------+
| enabled | True |
| id | 47cf883de46242c39f147c52f2958ebf |
| interface | public |
| region | RegionOne |
| region_id | RegionOne |
| service_id | d854f6fff0a64f77bda8003c8dedfada |
| service_name | octavia |
| service_type | load-balancer |
| url | http://controller:9876 |
+--------------+----------------------------------+
$ openstack endpoint create --region RegionOne \
load-balancer internal http://controller:9876
+--------------+----------------------------------+
| Field | Value |
+--------------+----------------------------------+
| enabled | True |
| id | 225aef8465ef4df48a341aaaf2b0a390 |
| interface | internal |
| region | RegionOne |
| region_id | RegionOne |
| service_id | d854f6fff0a64f77bda8003c8dedfada |
| service_name | octavia |
| service_type | load-balancer |
| url | http://controller:9876 |
+--------------+----------------------------------+
$ openstack endpoint create --region RegionOne \
load-balancer admin http://controller:9876
+--------------+----------------------------------+
| Field | Value |
+--------------+----------------------------------+
| enabled | True |
| id | 375eb5057fb546edbdf3ee4866179672 |
| interface | admin |
| region | RegionOne |
| region_id | RegionOne |
| service_id | d854f6fff0a64f77bda8003c8dedfada |
| service_name | octavia |
| service_type | load-balancer |
| url | http://controller:9876 |
+--------------+----------------------------------+
5. Create octavia-openrc file
.. code-block:: console
cat << EOF >> $HOME/octavia-openrc
export OS_PROJECT_DOMAIN_NAME=Default
export OS_USER_DOMAIN_NAME=Default
export OS_PROJECT_NAME=service
export OS_USERNAME=octavia
export OS_PASSWORD=OCTAVIA_PASS
export OS_AUTH_URL=http://controller:5000
export OS_IDENTITY_API_VERSION=3
export OS_IMAGE_API_VERSION=2
export OS_VOLUME_API_VERSION=3
EOF
Replace OCTAVIA_PASS with the password you chose for the octavia user in
the Identity service.
6. Source the ``octavia`` credentials to gain access to octavia CLI commands:
.. code-block:: console
$ . $HOME/octavia-openrc
7. Create the amphora image
For creating amphora image, please refer to the `Building Octavia Amphora Images <https://docs.openstack.org/octavia/latest/admin/amphora-image-build.html>`_.
8. Upload the amphora image
.. code-block:: console
$ openstack image create --disk-format qcow2 --container-format bare \
--private --tag amphora \
--file <path to the amphora image> amphora-x64-haproxy
9. Create a flavor for the amphora image
.. code-block:: console
$ openstack flavor create --id 200 --vcpus 1 --ram 1024 \
--disk 2 "amphora" --private
Install and configure components
--------------------------------
1. Install the packages:
.. code-block:: console
# apt install octavia-api octavia-health-manager octavia-housekeeping \
octavia-worker python3-octavia python3-octaviaclient
If octavia-common and octavia-api packages ask you to configure, choose No.
2. Create the certificates
.. code-block:: console
$ git clone https://opendev.org/openstack/octavia.git
$ cd octavia/bin/
$ source create_dual_intermediate_CA.sh
$ sudo mkdir -p /etc/octavia/certs/private
$ sudo chmod 755 /etc/octavia -R
$ sudo cp -p etc/octavia/certs/server_ca.cert.pem /etc/octavia/certs
$ sudo cp -p etc/octavia/certs/server_ca-chain.cert.pem /etc/octavia/certs
$ sudo cp -p etc/octavia/certs/server_ca.key.pem /etc/octavia/certs/private
$ sudo cp -p etc/octavia/certs/client_ca.cert.pem /etc/octavia/certs
$ sudo cp -p etc/octavia/certs/client.cert-and-key.pem /etc/octavia/certs/private
For the production environment, Please refer to the `Octavia Certificate Configuration Guide <https://docs.openstack.org/octavia/latest/admin/guides/certificates.html>`_.
3. Source the ``octavia`` credentials to gain access to octavia CLI commands:
.. code-block:: console
$ . octavia-openrc
4. Create security groups and their rules
.. 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
$ openstack security group create lb-health-mgr-sec-grp
$ openstack security group rule create --protocol udp --dst-port 5555 lb-health-mgr-sec-grp
5. Create a key pair for logining to the amphora instance
.. code-block:: console
$ openstack keypair create --public-key ~/.ssh/id_rsa.pub mykey
.. note::
Check whether " ~/.ssh/id_rsa.pub" file exists or not in advance.
If the file is not exist, run ssh-keygen command to create it.
6. Create dhclient.conf file for dhclient
.. code-block:: console
$ cd $HOME
$ sudo mkdir -m755 -p /etc/dhcp/octavia
$ sudo cp octavia/etc/dhcp/dhclient.conf /etc/dhcp/octavia
7. Create a network
.. note::
During the execution of the below command, please save the of
BRNAME and MGMT_PORT_MAC in a notepad for further reference.
.. code-block:: console
$ OCTAVIA_MGMT_SUBNET=172.16.0.0/12
$ OCTAVIA_MGMT_SUBNET_START=172.16.0.100
$ OCTAVIA_MGMT_SUBNET_END=172.16.31.254
$ OCTAVIA_MGMT_PORT_IP=172.16.0.2
$ openstack network create lb-mgmt-net
$ 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
$ SUBNET_ID=$(openstack subnet show lb-mgmt-subnet -f value -c id)
$ PORT_FIXED_IP="--fixed-ip subnet=$SUBNET_ID,ip-address=$OCTAVIA_MGMT_PORT_IP"
$ MGMT_PORT_ID=$(openstack port create --security-group \
lb-health-mgr-sec-grp --device-owner Octavia:health-mgr \
--host=$(hostname) -c id -f value --network lb-mgmt-net \
$PORT_FIXED_IP octavia-health-manager-listen-port)
$ MGMT_PORT_MAC=$(openstack port show -c mac_address -f value \
$MGMT_PORT_ID)
$ MGMT_PORT_IP=$(openstack port show -f yaml -c fixed_ips \
$MGMT_PORT_ID | awk '{FS=",|";gsub(",","");gsub("'\''",""); \
for(line = 1; line <= NF; ++line) {if ($line ~ /^- ip_address:/) \
{split($line, word, " ");if (ENVIRON["IPV6_ENABLED"] == "" && word[3] ~ /\./) \
print word[3];if (ENVIRON["IPV6_ENABLED"] != "" && word[3] ~ /:/) print word[3];} \
else {split($line, word, " ");for(ind in word) {if (word[ind] ~ /^ip_address=/) \
{split(word[ind], token, "=");if (ENVIRON["IPV6_ENABLED"] == "" && token[2] ~ /\./) \
print token[2];if (ENVIRON["IPV6_ENABLED"] != "" && token[2] ~ /:/) print token[2];}}}}}')
$ sudo ip link add o-hm0 type veth peer name o-bhm0
$ NETID=$(openstack network show lb-mgmt-net -c id -f value)
$ BRNAME=brq$(echo $NETID|cut -c 1-11)
$ sudo brctl addif $BRNAME o-bhm0
$ sudo ip link set o-bhm0 up
$ sudo ip link set dev o-hm0 address $MGMT_PORT_MAC
$ sudo iptables -I INPUT -i o-hm0 -p udp --dport 5555 -j ACCEPT
$ sudo dhclient -v o-hm0 -cf /etc/dhcp/octavia
8. Below settings are required to create veth pair after the host reboot
Edit the ``/etc/systemd/network/o-hm0.network`` file
.. code-block:: ini
[Match]
Name=o-hm0
[Network]
DHCP=yes
Edit the ``/etc/systemd/system/octavia-interface.service`` file
.. code-block:: ini
[Unit]
Description=Octavia Interface Creator
Requires=neutron-linuxbridge-agent.service
After=neutron-linuxbridge-agent.service
[Service]
Type=oneshot
RemainAfterExit=true
ExecStart=/opt/octavia-interface.sh start
ExecStop=/opt/octavia-interface.sh stop
[Install]
WantedBy=multi-user.target
Edit the ``/opt/octavia-interface.sh`` file
.. code-block:: console
#!/bin/bash
set -ex
MAC=$MGMT_PORT_MAC
BRNAME=$BRNAME
if [ "$1" == "start" ]; then
ip link add o-hm0 type veth peer name o-bhm0
brctl addif $BRNAME o-bhm0
ip link set o-bhm0 up
ip link set dev o-hm0 address $MAC
ip link set o-hm0 up
iptables -I INPUT -i o-hm0 -p udp --dport 5555 -j ACCEPT
elif [ "$1" == "stop" ]; then
ip link del o-hm0
else
brctl show $BRNAME
ip a s dev o-hm0
fi
You need to substitute $MGMT_PORT_MAC and $BRNAME for the values in your environment.
9. Edit the ``/etc/octavia/octavia.conf`` file
* In the ``[database]`` section, configure database access:
.. code-block:: ini
[database]
connection = mysql+pymysql://octavia:OCTAVIA_DBPASS@controller/octavia
Replace OCTAVIA_DBPASS with the password you chose for the Octavia databases.
* In the ``[DEFAULT]`` section, configure the transport url for RabbitMQ message broker.
.. code-block:: ini
[DEFAULT]
transport_url = rabbit://openstack:RABBIT_PASS@controller
Replace RABBIT_PASS with the password you chose for the openstack account in RabbitMQ.
* In the ``[oslo_messaging]`` section, configure the transport url for RabbitMQ message broker and topic name.
.. code-block:: ini
[oslo_messaging]
...
topic = octavia_prov
Replace RABBIT_PASS with the password you chose for the openstack account in RabbitMQ.
* In the ``[api_settings]`` section, configure the host IP and port to bind to.
.. code-block:: ini
[api_settings]
bind_host = 0.0.0.0
bind_port = 9876
* In the ``[keystone_authtoken]`` section, configure Identity service access.
.. code-block:: ini
[keystone_authtoken]
www_authenticate_uri = http://controller:5000
auth_url = http://controller:5000
memcached_servers = controller:11211
auth_type = password
project_domain_name = Default
user_domain_name = Default
project_name = service
username = octavia
password = OCTAVIA_PASS
Replace OCTAVIA_PASS with the password you chose for the octavia user in
the Identity service.
* In the ``[service_auth]`` section, configure credentials for using other openstack services
.. code-block:: ini
[service_auth]
auth_url = http://controller:5000
memcached_servers = controller:11211
auth_type = password
project_domain_name = Default
user_domain_name = Default
project_name = service
username = octavia
password = OCTAVIA_PASS
Replace OCTAVIA_PASS with the password you chose for the octavia user in
the Identity service.
* In the ``[certificates]`` section, configure the absolute path to the CA Certificate, the Private Key for signing, and passphrases.
.. code-block:: ini
[certificates]
...
server_certs_key_passphrase = insecure-key-do-not-use-this-key
ca_private_key_passphrase = not-secure-passphrase
ca_private_key = /etc/octavia/certs/private/server_ca.key.pem
ca_certificate = /etc/octavia/certs/server_ca.cert.pem
.. note::
The values of ca_private_key_passphrase and server_certs_key_passphrase are default and should not be used in production.
The server_certs_key_passphrase must be a base64 compatible and 32 characters long string.
* In the ``[haproxy_amphora]`` section, configure the client certificate and the CA.
.. code-block:: ini
[haproxy_amphora]
...
server_ca = /etc/octavia/certs/server_ca-chain.cert.pem
client_cert = /etc/octavia/certs/private/client.cert-and-key.pem
* In the ``[health_manager]`` section, configure the IP and port number for heartbeat.
.. code-block:: ini
[health_manager]
...
bind_port = 5555
bind_ip = 172.16.0.2
controller_ip_port_list = 172.16.0.2:5555
* In the ``[controller_worker]`` section, configure worker settings.
.. code-block:: ini
[controller_worker]
...
amp_image_owner_id = <id of service project>
amp_image_tag = amphora
amp_ssh_key_name = mykey
amp_secgroup_list = <lb-mgmt-sec-grp_id>
amp_boot_network_list = <lb-mgmt-net_id>
amp_flavor_id = 200
network_driver = allowed_address_pairs_driver
compute_driver = compute_nova_driver
amphora_driver = amphora_haproxy_rest_driver
client_ca = /etc/octavia/certs/client_ca.cert.pem
10. Populate the octavia database:
.. code-block:: console
# octavia-db-manage --config-file /etc/octavia/octavia.conf upgrade head
Finalize installation
---------------------
Restart the services:
.. code-block:: console
# systemctl restart octavia-api octavia-health-manager octavia-housekeeping octavia-worker

19
doc/source/install/install.rst Normal file
View File

@ -0,0 +1,19 @@
.. _install:
Install and configure
~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure the Load-balancer
service, code-named Octavia, on the controller node.
This section assumes that you already have a working OpenStack
environment with at least the following components installed:
Identity Service, Image Service, Placement Service, Compute Service,
and Networking Service.
Note that installation and configuration vary by distribution.
.. toctree::
:maxdepth: 2
install-ubuntu.rst