quickstart.rst

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 and Docker 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

See the :kolla-ansible-doc:`support matrix <user/support-matrix>` for details of supported host Operating Systems. Kolla Ansible supports the default Python 3.x versions provided by the supported Operating Systems. For more information see tested runtimes.

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 in :kolla-ansible-doc:`Virtual Environments <user/virtual-environments.html>`.

1. For Debian or Ubuntu, update the package index.

   sudo apt update

2. Install Python build dependencies:

   For CentOS or RHEL 8, run:

   sudo dnf install python3-devel libffi-devel gcc openssl-devel python3-libselinux

   For Debian or Ubuntu, run:

   sudo apt install python3-dev libffi-dev gcc libssl-dev

Install dependencies using a virtual environment

If not installing Kolla Ansible in a virtual environment, skip this section.

1. Install the virtual environment dependencies.

   For CentOS or RHEL 8, you don't need to do anything.

   For Debian or Ubuntu, run:

   sudo apt install python3-venv

2. Create a virtual environment and activate it:

   python3 -m venv /path/to/venv
   source /path/to/venv/bin/activate

   The virtual environment should be activated before running any commands that depend on packages installed in it.

3. Ensure the latest version of pip is installed:

   pip install -U pip

4. Install Ansible. Kolla Ansible requires at least Ansible 2.10 and supports up to 4.

   pip install 'ansible<5.0'

Install dependencies not using a virtual environment

If installing Kolla Ansible in a virtual environment, skip this section.

1. Install pip.

   For CentOS or RHEL, run:

   sudo dnf install python3-pip

   For Debian or Ubuntu, run:

   sudo apt install python3-pip

2. Ensure the latest version of pip is installed:

   sudo pip3 install -U pip

3. Install Ansible. Kolla Ansible requires at least Ansible 2.10 and supports up to 4.

   For CentOS or RHEL, run:

   sudo dnf install ansible

   For Debian or Ubuntu, run:

   sudo apt install ansible

   Note

   If the installed Ansible version does not meet the requirements, one can use pip: sudo pip install -U 'ansible<3.0'. Beware system package upgrades might interfere with that so it is recommended to uninstall the system package first. One might be better off with the virtual environment method to avoid this pitfall.

Install Kolla-ansible

Install Kolla-ansible for deployment or evaluation

1. Install kolla-ansible and its dependencies using pip.

   If using a virtual environment:

   pip install git+https://opendev.org/openstack/kolla-ansible@|KOLLA_BRANCH_NAME|

   If not using a virtual environment:

   sudo pip3 install git+https://opendev.org/openstack/kolla-ansible@|KOLLA_BRANCH_NAME|

2. Create the /etc/kolla directory.

   sudo mkdir -p /etc/kolla
   sudo chown $USER:$USER /etc/kolla

3. Copy globals.yml and passwords.yml to /etc/kolla directory.

   If using a virtual environment:

   cp -r /path/to/venv/share/kolla-ansible/etc_examples/kolla/* /etc/kolla

   If not using a virtual environment, run:

   cp -r /usr/local/share/kolla-ansible/etc_examples/kolla/* /etc/kolla

4. Copy all-in-one and multinode inventory files to the current directory.

   If using a virtual environment:

   cp /path/to/venv/share/kolla-ansible/ansible/inventory/* .

   If not using a virtual environment, run:

   cp /usr/local/share/kolla-ansible/ansible/inventory/* .

Install Kolla for development

1. Clone kolla-ansible repository from git.

   git clone --branch |KOLLA_BRANCH_NAME| https://opendev.org/openstack/kolla-ansible

2. Install requirements of kolla and kolla-ansible:

   If using a virtual environment:

   pip install ./kolla-ansible

   If not using a virtual environment:

   sudo pip3 install ./kolla-ansible

3. Create the /etc/kolla directory.

   sudo mkdir -p /etc/kolla
   sudo chown $USER:$USER /etc/kolla

4. Copy the configuration files to /etc/kolla directory. kolla-ansible holds the configuration files ( globals.yml and passwords.yml) in etc/kolla.

   cp -r kolla-ansible/etc/kolla/* /etc/kolla

5. Copy the inventory files to the current directory. kolla-ansible holds inventory files ( all-in-one and multinode) in the ansible/inventory directory.

   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:

[defaults]
host_key_checking=False
pipelining=True
forks=100

Further information on tuning Ansible is available here.

Prepare initial configuration

Inventory