quickstart.rst

Quick Start

This guide provides step by step instructions to deploy OpenStack using Kolla and Kolla-Ansible on bare metal servers or virtual machines.

Host machine requirements

The host machine must satisfy the following minimum requirements:

• 2 network interfaces
• 8GB main memory
• 40GB disk space

Note

Root access to the deployment host machine is required.

Recommended environment

This guide recommends using a bare metal server 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.

If developing Kolla on a system that provides VirtualBox or Libvirt in addition to Vagrant, use the Vagrant virtual environment documented in :doc:`vagrant-dev-env`.

Prerequisites

Verify the state of network interfaces. If using a VM spawned on OpenStack as the host machine, the state of the second interface will be DOWN on booting the VM.

ip addr show

Bring up the second network interface if it is down.

ip link set ens4 up

Verify if the second interface has an IP address.

ip addr show

Install dependencies

Kolla builds images which are used by Kolla-Ansible to deploy OpenStack. The deployment is tested on CentOS, Oracle Linux and Ubuntu as both container OS platforms and bare metal deployment targets.

Ubuntu: For Ubuntu based systems where Docker is used it is recommended to use the latest available LTS kernel. While all kernels should work for Docker, some older kernels may have issues with some of the different Docker back ends 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

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/mitaka 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 stable/newton branch and later (including 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 the latest before proceeding:

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

#Ubuntu
apt-get update
apt-get install python-pip
pip install -U pip

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

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

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

Kolla deploys OpenStack using Ansible. Install Ansible from distribution packaging if the distro packaging has recommended version available.

Some implemented distro versions of Ansible are too old to use distro packaging. Currently, CentOS and RHEL package Ansible >2.0 which is suitable for use with Kolla. Note that you will need to enable access to the EPEL repository to install via yum -- to do so, take a look at Fedora's EPEL docs and FAQ.

On CentOS or RHEL systems, this can be done using:

yum install ansible

Many DEB based systems do not meet Kolla's Ansible version requirements. It is recommended to use pip to install Ansible >2.0. Finally Ansible >2.0 may be installed using:

pip install -U ansible

Note

It is recommended to use virtualenv to install non-system packages.

If DEB based systems include a version of Ansible that meets Kolla's version requirements it can be installed by:

apt-get install ansible

Warning

Kolla uses PBR in its implementation. PBR provides version information to Kolla about the package in use. This information is later used when building images to specify the Docker tag used in the image built. When installing the Kolla package via pip, PBR will always use the PBR version information. When obtaining a copy of the software via git, PBR will use the git version information, but ONLY if Kolla has not been pip installed via the pip package manager. This is why there is an operator workflow and a developer workflow.

The following dependencies can be installed by bootstraping the host machine as described in the Automatic host bootstrap section. For manual installation, follow the instructions below:

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,!=1.13.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