.. quickstart:
===========
Quick Start
===========
This guide provides step by step instructions to deploy OpenStack using Kolla
Ansible on bare metal servers or virtual machines.
Recommended reading
~~~~~~~~~~~~~~~~~~~
It's beneficial to learn basics of both `Ansible <https://docs.ansible.com>`__
and `Docker <https://docs.docker.com>`__ before running Kolla-Ansible.
Host machine requirements
~~~~~~~~~~~~~~~~~~~~~~~~~
The host machine must satisfy the following minimum requirements:
- 2 network interfaces
- 8GB main memory
- 40GB disk space
Install dependencies
~~~~~~~~~~~~~~~~~~~~
Typically commands that use the system package manager in this section must be
run with root privileges.
It is generally recommended to use a virtual environment to install Kolla
Ansible and its dependencies, to avoid conflicts with the system site packages.
Note that this is independent from the use of a virtual environment for remote
execution, which is described :ref:`here <virtual-environments-target-hosts>`.
#. For CentOS, install EPEL.
.. code-block:: console
sudo yum install epel-release
#. For Ubuntu, update the package index.
.. code-block:: console
sudo apt-get update
#. Install Python build dependencies:
For CentOS, run:
.. code-block:: console
sudo yum install python-devel libffi-devel gcc openssl-devel libselinux-python
For Ubuntu, run:
.. code-block:: console
sudo apt-get install python-dev libffi-dev gcc libssl-dev python-selinux python-setuptools
Install dependencies using a virtual environment
------------------------------------------------
If not installing Kolla Ansible in a virtual environment, skip this section.
#. Install the virtualenv package.
For CentOS or RHEL, run:
.. code-block:: console
sudo yum install python-virtualenv
For Ubuntu, run:
.. code-block:: console
sudo apt-get install python-virtualenv
#. Create a virtual environment and activate it:
.. code-block:: console
virtualenv /path/to/virtualenv
source /path/to/virtualenv/bin/activate
The virtual environment should be activated before running any commands that
depend on packages installed in it.
#. Ensure the latest version of pip is installed:
.. code-block:: console
pip install -U pip
#. Install `Ansible <http://www.ansible.com>`__. Currently, Kolla Ansible
requires Ansible 2.4+.
.. code-block:: console
pip install ansible
Install dependencies not using a virtual environment
----------------------------------------------------
If installing Kolla Ansible in a virtual environment, skip this section.
#. Install ``pip``.
For CentOS or RHEL, run:
.. code-block:: console
sudo yum install python-pip
For Ubuntu, run:
.. code-block:: console
sudo apt-get install python-pip
#. Ensure the latest version of pip is installed:
.. code-block:: console
sudo pip install -U pip
#. Install `Ansible <http://www.ansible.com>`__. Currently, Kolla Ansible
requires Ansible 2.4+.
For CentOS or RHEL, run:
.. code-block:: console
sudo yum install ansible
For Ubuntu, run:
.. code-block:: console
sudo apt-get install ansible
Install Kolla-ansible
~~~~~~~~~~~~~~~~~~~~~
Install Kolla-ansible for deployment or evaluation
--------------------------------------------------
#. Install kolla-ansible and its dependencies using ``pip``.
If using a virtual environment:
.. code-block:: console
pip install kolla-ansible
If not using a virtual environment:
.. code-block:: console
sudo pip install kolla-ansible
#. Create the ``/etc/kolla`` directory.
.. code-block:: console
sudo mkdir -p /etc/kolla
sudo chown $USER:$USER /etc/kolla
#. Copy ``globals.yml`` and ``passwords.yml`` to ``/etc/kolla`` directory.
If using a virtual environment:
.. code-block:: console
cp -r /path/to/virtualenv/share/kolla-ansible/etc_examples/kolla/* /etc/kolla
If not using a virtual environment on CentOS, run:
.. code-block:: console
cp -r /usr/share/kolla-ansible/etc_examples/kolla/* /etc/kolla
If not using a virtual environment on Ubuntu, run:
.. code-block:: console
cp -r /usr/local/share/kolla-ansible/etc_examples/kolla/* /etc/kolla
#. Copy ``all-in-one`` and ``multinode`` inventory files to
the current directory.
If using a virtual environment:
.. code-block:: console
cp /path/to/virtualenv/share/kolla-ansible/ansible/inventory/* .
If not using a virtual environment on CentOS, run:
.. code-block:: console
cp /usr/share/kolla-ansible/ansible/inventory/* .
If not using a virtual environment on Ubuntu, run:
.. code-block:: console
cp /usr/local/share/kolla-ansible/ansible/inventory/* .
Install Kolla for development
-----------------------------
#. Clone ``kolla`` and ``kolla-ansible`` repositories from git.
.. code-block:: console
git clone https://github.com/openstack/kolla
git clone https://github.com/openstack/kolla-ansible
#. Install requirements of ``kolla`` and ``kolla-ansible``:
If using a virtual environment:
.. code-block:: console
pip install -r kolla/requirements.txt
pip install -r kolla-ansible/requirements.txt
If not using a virtual environment:
.. code-block:: console
sudo pip install -r kolla/requirements.txt
sudo pip install -r kolla-ansible/requirements.txt
#. Create the ``/etc/kolla`` directory.
.. code-block:: console
sudo mkdir -p /etc/kolla
sudo chown $USER:$USER /etc/kolla
#. Copy the configuration files to ``/etc/kolla`` directory.
``kolla-ansible`` holds the configuration files ( ``globals.yml`` and
``passwords.yml``) in ``etc/kolla``.
.. code-block:: console
cp -r kolla-ansible/etc/kolla/* /etc/kolla
#. Copy the inventory files to the current directory. ``kolla-ansible`` holds
inventory files ( ``all-in-one`` and ``multinode``) in the
``ansible/inventory`` directory.
.. code-block:: console
cp kolla-ansible/ansible/inventory/* .
Configure Ansible
~~~~~~~~~~~~~~~~~
For best results, Ansible configuration should be tuned for your environment.
For example, add the following options to the Ansible configuration file
``/etc/ansible/ansible.cfg``:
.. path /etc/ansible/ansible.cfg
.. code-block:: ini
[defaults]
host_key_checking=False
pipelining=True
forks=100
Further information on tuning Ansible is available `here
<https://www.ansible.com/blog/ansible-performance-tuning>`__.
Prepare initial configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Inventory
---------
The next step is to prepare our inventory file. An inventory is an Ansible file
where we specify hosts and the groups that they belong to. We can use this to
define node roles and access credentials.
Kolla-Ansible comes with ``all-in-one`` and ``multinode`` example inventory
files. The difference between them is that the former is ready for deploying
single node OpenStack on localhost. If you need to use separate host or more
than one node, edit ``multinode`` inventory:
#. Edit the first section of ``multinode`` with connection details of your
environment, for example:
.. code-block:: ini
[control]
10.0.0.[10:12] ansible_user=ubuntu ansible_password=foobar ansible_become=true
# Ansible supports syntax like [10:12] - that means 10, 11 and 12.
# Become clause means "use sudo".
[network:children]
control
# when you specify group_name:children, it will use contents of group specified.
[compute]
10.0.0.[13:14] ansible_user=ubuntu ansible_password=foobar ansible_become=true
[monitoring]
10.0.0.10
# This group is for monitoring node.
# Fill it with one of the controllers' IP address or some others.
[storage:children]
compute
[deployment]
localhost ansible_connection=local become=true
# use localhost and sudo
To learn more about inventory files, check
`Ansible documentation <http://docs.ansible.com/ansible/latest/intro_inventory.html>`_.
#. Check whether the configuration of inventory is correct or not, run:
.. code-block:: console
ansible -i multinode all -m ping
.. note::
Ubuntu might not come with python pre-installed. That will cause
errors in ping module. To quickly install python with ansible you
can run ``ansible -i multinode all -m raw -a "apt-get -y install python-dev"``
Kolla passwords
---------------
Passwords used in our deployment are stored in ``/etc/kolla/passwords.yml``
file. All passwords are blank in this file and have to be filled either
manually or by running random password generator:
For deployment or evaluation, run:
.. code-block:: console
kolla-genpwd
For development, run:
.. code-block:: console
cd kolla-ansible/tools
./generate_passwords.py
Kolla globals.yml
-----------------
``globals.yml`` is the main configuration file for Kolla-Ansible.
There are a few options that are required to deploy Kolla-Ansible:
* Image options
User has to specify images that are going to be used for our deployment.
In this guide `DockerHub <https://hub.docker.com/u/kolla/>`__ provided
pre-built images are going to be used. To learn more about building
mechanism, please refer `image building documentation
<https://docs.openstack.org/kolla/latest/admin/image-building.html>`_.
Kolla provides choice of several Linux distributions in containers:
- Centos
- Ubuntu
- Oraclelinux
- Debian
- RHEL
For newcomers, we recommend to use CentOS 7 or Ubuntu 16.04.
.. code-block:: console
kolla_base_distro: "centos"
Next "type" of installation needs to be configured.
Choices are:
binary
using repositories like apt or yum
source
using raw source archives, git repositories or local source directory
.. note::
This only affects OpenStack services. Infrastructure services like Ceph are
always "binary".
.. note::
Source builds are proven to be slightly more reliable than binary.
.. code-block:: console
kolla_install_type: "source"
To use DockerHub images, the default image tag has to be overridden. Images are
tagged with release names. For example to use stable Rocky images set
.. code-block:: console
openstack_release: "rocky"
It's important to use same version of images as kolla-ansible. That
means if pip was used to install kolla-ansible, that means it's latest stable
version so ``openstack_release`` should be set to rocky. If git was used with
master branch, DockerHub also provides daily builds of master branch (which is
tagged as ``master``):
.. code-block:: console
openstack_release: "master"
* Networking
Kolla-Ansible requires a few networking options to be set.
We need to set network interfaces used by OpenStack.
First interface to set is "network_interface". This is the default interface
for multiple management-type networks.
.. code-block:: console
network_interface: "eth0"
Second interface required is dedicated for Neutron external (or public)
networks, can be vlan or flat, depends on how the networks are created.
This interface should be active without IP address. If not, instances
won't be able to access to the external networks.
.. code-block:: console
neutron_external_interface: "eth1"
To learn more about network configuration, refer `Network overview
<https://docs.openstack.org/kolla-ansible/latest/admin/production-architecture-guide.html#network-configuration>`_.
Next we need to provide floating IP for management traffic. This IP will be
managed by keepalived to provide high availability, and should be set to be
*not used* address in management network that is connected to our
``network_interface``.
.. code-block:: console
kolla_internal_vip_address: "10.1.0.250"
* Enable additional services
By default Kolla-Ansible provides a bare compute kit, however it does provide
support for a vast selection of additional services. To enable them, set
``enable_*`` to "yes". For example, to enable Block Storage service:
.. code-block:: console
enable_cinder: "yes"
Kolla now supports many OpenStack services, there is
`a list of available services
<https://github.com/openstack/kolla-ansible/blob/master/README.rst#openstack-services>`_.
For more information about service configuration, Please refer to the
`Services Reference Guide
<https://docs.openstack.org/kolla-ansible/latest/reference/index.html>`_.
* Virtual environment
It is recommended to use a virtual environment to execute tasks on the remote
hosts. This is covered :ref:`here <virtual-environments-target-hosts>`.
Deployment
~~~~~~~~~~
After configuration is set, we can proceed to the deployment phase. First we
need to setup basic host-level dependencies, like docker.
Kolla-Ansible provides a playbook that will install all required services in
the correct versions.
The following assumes the use of the ``multinode`` inventory. If using a
different inventory, such as ``all-in-one``, replace the ``-i`` argument
accordingly.
* For deployment or evaluation, run:
#. Bootstrap servers with kolla deploy dependencies:
.. code-block:: console
kolla-ansible -i ./multinode bootstrap-servers
#. Do pre-deployment checks for hosts:
.. code-block:: console
kolla-ansible -i ./multinode prechecks
#. Finally proceed to actual OpenStack deployment:
.. code-block:: console
kolla-ansible -i ./multinode deploy
* For development, run:
#. Bootstrap servers with kolla deploy dependencies:
.. code-block:: console
cd kolla-ansible/tools
./kolla-ansible -i ../../multinode bootstrap-servers
#. Do pre-deployment checks for hosts:
.. code-block:: console
./kolla-ansible -i ../../multinode prechecks
#. Finally proceed to actual OpenStack deployment:
.. code-block:: console
./kolla-ansible -i ../../multinode deploy
When this playbook finishes, OpenStack should be up, running and functional!
If error occurs during execution, refer to
`troubleshooting guide <https://docs.openstack.org/kolla-ansible/latest/user/troubleshooting.html>`_.
Using OpenStack
~~~~~~~~~~~~~~~
#. Install basic OpenStack CLI clients:
.. code-block:: console
pip install python-openstackclient python-glanceclient python-neutronclient
#. OpenStack requires an openrc file where credentials for admin user
are set. To generate this file:
* For deployment or evaluation, run:
.. code-block:: console
kolla-ansible post-deploy
. /etc/kolla/admin-openrc.sh
* For development, run:
.. code-block:: console
cd kolla-ansible/tools
./kolla-ansible post-deploy
. /etc/kolla/admin-openrc.sh
#. Depending on how you installed Kolla-Ansible, there is a script that will
create example networks, images, and so on.
* For deployment or evaluation,
run ``init-runonce`` script on CentOS:
.. code-block:: console
. /usr/share/kolla-ansible/init-runonce
Run ``init-runonce`` script on Ubuntu:
.. code-block:: console
. /usr/local/share/kolla-ansible/init-runonce
* For development, run:
.. code-block:: console
. kolla-ansible/tools/init-runonce