quickstart.rst

Quick Start

This guide provides a step by step of how to deploy Kolla on bare metal or a virtual machine.

Host machine requirements

The recommended deployment target requirements:

• 2 (or more) network interfaces.
• At least 8gb main memory
• At least 40gb disk space.

Note

Some commands below may require root permissions (e.g. pip, apt-get).

Recommended Environment

If developing or evaluating Kolla, the community strongly recommends using bare metal or a virtual machine. Follow the instructions in this document to get started with deploying OpenStack on bare metal or a virtual machine with Kolla. There are other deployment environments referenced below in Additional Environments.

Automatic host bootstrap

Note

New in Newton

To quickly prepare hosts for Kolla, playbook bootstrap-servers can be used. This is an Ansible playbook which works on Ubuntu 14.04, 16.04 and CentOS 7 hosts to install and prepare cluster for Kolla installation.

Note

Installation of dependencies for deployment node and configuration of Kolla interfaces is still required prior to running this command. More information about Kolla interface configuration in :ref:`interface-configuration`.

Command to run the playbook:

kolla-ansible -i <<inventory file>> bootstrap-servers

To learn more about the inventory file, follow :ref:`edit-inventory`.

Install Dependencies

Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu as both container OS platforms and bare metal deployment targets.

Fedora: Kolla will not run on Fedora 22 and later as a bare metal deployment target. These distributions compress kernel modules with the .xz compressed format. The guestfs system in the CentOS family of containers cannot read these images because a dependent package supermin in CentOS needs to be updated to add .xz compressed format support.

Ubuntu: For Ubuntu based systems where Docker is used it is recommended to use the latest available LTS kernel. The latest LTS kernel available is the wily kernel (version 4.2). While all kernels should work for Docker, some older kernels may have issues with some of the different Docker backends such as AUFS and OverlayFS. In order to update kernel in Ubuntu 14.04 LTS to 4.2, run:

apt-get install linux-image-generic-lts-wily

Warning

Operators performing an evaluation or deployment should use a stable branch. Operators performing development (or developers) should use master.

Note

Install is very sensitive about version of components. Please review carefully because default Operating System repos are likely out of date.

Dependencies for the stable branch are:

Component	Min Version	Max Version	Comment
Ansible	1.9.4	< 2.0.0	On deployment host
Docker	1.10.0	none	On target nodes
Docker Python	1.6.0	none	On target nodes
Python Jinja2	2.6.0	none	On deployment host

Dependencies for the master branch are:

Component	Min Version	Max Version	Comment
Ansible	2.0.0	none	On deployment host
Docker	1.10.0	none	On target nodes
Docker Python	1.6.0	none	On target nodes
Python Jinja2	2.8.0	none	On deployment host

Make sure the pip package manager is installed and upgraded to latest before proceeding:

# CentOS 7
yum install epel-release
yum install python-pip

# Ubuntu 14.04 LTS
apt-get install python-pip

# Upgrade pip and check version
pip install -U pip
pip -V

Install dependencies needed to build the code with pip package manager.

# Ubuntu
apt-get install python-dev libffi-dev gcc libssl-dev

# CentOS 7
yum install python-devel libffi-devel gcc openssl-devel

Since Docker is required to build images as well as be present on all deployed targets, the Kolla community recommends installing the official Docker, Inc. packaged version of Docker for maximum stability and compatibility with the following command:

curl -sSL https://get.docker.io | bash

This command will install the most recent stable version of Docker, but please note that Kolla releases are not in sync with Docker in any way, so some things could stop working with new version. The latest release of Kolla is tested to work with docker-engine >= 1.10.0. To check your Docker version run this command:

docker --version

When running with systemd, setup docker-engine with the appropriate information in the Docker daemon to launch with. This means setting up the following information in the docker.service file. If you do not set the MountFlags option correctly then kolla-ansible will fail to deploy the neutron-dhcp-agent container and throws APIError/HTTPError. After adding the drop-in unit file as follows, reload and restart the Docker service:

# Create the drop-in unit directory for docker.service
mkdir -p /etc/systemd/system/docker.service.d

# Create the drop-in unit file
tee /etc/systemd/system/docker.service.d/kolla.conf <<-'EOF'
[Service]
MountFlags=shared
EOF

Restart Docker by executing the following commands:

# Run these commands to reload the daemon
systemctl daemon-reload
systemctl restart docker

For Ubuntu 14.04 which uses upstart and other non-systemd distros, run the following:

mount --make-shared /run

For mounting /run as shared upon startup, add that command to /etc/rc.local

# Edit /etc/rc.local to add:
mount --make-shared /run

Note

If centos/oraclelinux container images are built on an Ubuntu host, the backend storage driver must not be AUFS (see the known issues in :doc:`image-building`).

Note

On ubuntu 16.04, please uninstall lxd and lxc packages. (issue with cgroup mounts, mounts exponentially increasing when restarting container).

On the target hosts you also need an updated version of the Docker python libraries:

Note

The old docker-python is obsoleted by python-docker-py.