quickstart.rst

Deployment of Kolla on Bare Metal or Virtual Machine

Evaluation and Developer Environments

Two virtualized evaluation and development environment options are available. These options permit the evaluation of Kolla without disrupting the host operating system.

If developing or evaluating Kolla on an OpenStack cloud environment that supports Heat, follow the :doc:`Heat evaluation and developer environment guide <heat-dev-env>`.

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

If evaluating or deploying OpenStack on bare-metal with Kolla, follow the instructions in this document to get started.

Host machine requirements

The recommended deployment target requirements:

• Two network interfaces.
• More than 8gb main memory.
• At least 40gb disk space.

Note

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

Installing 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

Note

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

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

Make sure "pip" package manager is installed before procceed:

# Centos 7
easy_install pip

# Ubuntu 14.04 LTS
apt-get install python-pip

To clone the Kolla repo, install git and use:

git clone https://git.openstack.org/openstack/kolla

To install Kolla tools and Python dependencies use:

pip install kolla/

Copy Kolla configuration to /etc:

cp -r kolla/etc/kolla /etc/

Since Docker is required to build images as well as be present on all deployed targets, the Kolla community recommends installing the 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 changing the service file, reload and restart the docker service:

# /lib/systemd/system/docker.service
[Service]
MountFlags=shared

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

For Ubuntu 14.04 which uses upstart instead of systemd, run the following:

mount --make-shared /run

On the system where the OpenStack CLI/Python code is run, the Kolla community recommends installing the OpenStack python clients if they are not installed. This could be a completely different machine then the deployment host or deployment targets. Before installing the OpenStack python client, the following requirements are needed to build the client code:

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

# Centos 7
yum install -y python-devel libffi-devel openssl-devel gcc

To install these clients use:

pip install -U python-openstackclient

OpenStack, RabbitMQ, and Ceph require all hosts to have matching times to ensure proper message delivery. In the case of Ceph, it will complain if the hosts differ by more than 0.05 seconds. Some OpenStack services have timers as low as 2 seconds by default. For these reasons it is highly recommended to setup an NTP service of some kind. While ntpd will achieve more accurate time for the deployment if the NTP servers are running in the local deployment environment, chrony is more accurate when syncing the time across a WAN connection. When running Ceph it is recommended to setup ntpd to sync time locally due to the tight time constraints.

To install, start, and enable ntp on CentOS execute the following:

# Centos 7
yum -y install ntp
systemctl enable ntpd.service
systemctl start ntpd.service

To install and start on Debian based systems execute the following:

apt-get install ntp

Libvirt is started by default on many operating systems. Please disable libvirt on any machines that will be deployment targets. Only one copy of libvirt may be running at a time.

# Centos 7
systemctl stop libvirtd.service
systemctl disable libvirtd.service

# Ubuntu
service libvirt-bin stop
update-rc.d libvirt-bin disable

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 1.9.4 which is suitable for use with Kolla.

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

yum -y install ansible

Many DEB based systems do not meet Kolla's Ansible version requirements. It is recommended to use pip to install Ansible 1.9.4.

Some ansible dependencies, like pycrypto, may need gcc installed on the build system. Install it using system packaging tools if it's not installed already:

# Centos 7
yum -y install gcc

# Ubuntu
apt-get install gcc

Finally Ansible 1.9.4 may be installed using:

pip install -U ansible==1.9.4

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

apt-get install ansible

Deploy a registry (required for multinode)

A Docker registry is a locally hosted registry that replaces the need to pull from the Docker Hub to get images. Kolla can function with or without a local registry, however for a multinode deployment a registry is required.

The Docker registry prior to version 2.3 has extremely bad performance because all container data is pushed for every image rather than taking advantage of Docker layering to optimize push operations. For more information reference pokey registry.

The Kolla community recommends using registry 2.3 or later. To deploy registry 2.3 do the following:

docker run -d -p 4000:5000 --restart=always --name registry registry:2

Note: Kolla looks for the Docker registry to use port 4000. (Docker default is port 5000)

After enabling the registry, it is necessary to instruct Docker that it will be communicating with an insecure registry. To enable insecure registry communication on CentOS, modify the "/etc/sysconfig/docker" file to contain the following where 192.168.1.100 is the IP address of the machine where the registry is currently running:

other_args="--insecure-registry 192.168.1.100:4000"

Docker Inc's packaged version of docker-engine for CentOS is defective and does not read the other_args configuration options from "/etc/sysconfig/docker". To rectify this problem, set the contents of "/usr/lib/systemd/system/docker.service" to:

[Unit]
Description=Docker Application Container Engine
Documentation=https://docs.docker.com
After=network.target docker.socket
Requires=docker.socket

[Service]
EnvironmentFile=/etc/sysconfig/docker
Type=notify
ExecStart=/usr/bin/docker daemon -H fd:// $other_args
MountFlags=slave
LimitNOFILE=1048576
LimitNPROC=1048576
LimitCORE=infinity

[Install]
WantedBy=multi-user.target

And restart docker by executing the following commands: