58ee9c4b84
I merged "quickstart" doc with "ansible-deployment" and "deploy-all-in-one-node". All three of them was covering same topic and added a lot of confusion for new users. I added some clarification lines from myself, with main goal to recive one straightforward document for new users. Change-Id: I793244c47ffbe0ba304e79bacf708494e59d99c4
366 lines
12 KiB
ReStructuredText
366 lines
12 KiB
ReStructuredText
Bare Metal Deployment of Kolla
|
|
==============================
|
|
|
|
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 machine recommended requirements:
|
|
|
|
- Two network interfaces.
|
|
- More than 8gb main memory.
|
|
- At least 40gb disk space.
|
|
|
|
Installing Dependencies
|
|
-----------------------
|
|
|
|
Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu. It should work with
|
|
other OS distributions, but some need further testing.
|
|
|
|
Fedora: Kolla will not run on Fedora 22 or later currently. Fedora 22
|
|
compresses 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, do not use AUFS when
|
|
starting Docker daemon, unless running Ubuntu uses 3.19 kernel or above.
|
|
AUFS requires CONFIG\_AUFS\_XATTR=y set when building the kernel. On
|
|
Ubuntu, versions prior to 3.19 did not set this flag to be compatible with
|
|
Docker. In order to update kernel in Ubuntu 14.04 LTS to 3.19, run:
|
|
|
|
::
|
|
|
|
sudo apt-get install linux-image-generic-lts-vivid
|
|
|
|
If unable to upgrade the kernel, the Kolla community recommends using a
|
|
different storage backend such as btrfs when running Docker daemon.
|
|
|
|
.. 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 none On deployment host
|
|
Docker 1.8.2 1.8.2 On target nodes
|
|
Docker Python 1.2.0 none On target nodes
|
|
Python Jinja2 2.6.0 none On deployment host
|
|
===================== =========== =========== =========================
|
|
|
|
To install Python dependencies use:
|
|
|
|
::
|
|
|
|
git clone https://git.openstack.org/openstack/kolla
|
|
cd kolla
|
|
sudo pip install -r requirements.txt
|
|
|
|
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 what Kolla releases are not in sync with docker in any way, so some things
|
|
could stop working with new version. Kolla release 1.0.0-liberty tested to
|
|
work with docker 1.8.2, to check you docker version run this command:
|
|
|
|
::
|
|
|
|
docker --version
|
|
|
|
If this version is higher than recomended, consider downgrade it using this
|
|
commands:
|
|
|
|
::
|
|
|
|
# Centos 7
|
|
yum downgrade docker-engine-1.8.2-1
|
|
service docker-engine restart
|
|
|
|
# Ubuntu 14.04 LTS
|
|
sudo apt-get install docker-engine=1.8.2-0~trusty
|
|
|
|
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
|
|
sudo apt-get install -y python-dev python-pip libffi-dev libssl-dev
|
|
|
|
# Centos 7
|
|
easy_install pip
|
|
yum install -y python-devel libffi-devel openssl-devel
|
|
|
|
To install these clients use:
|
|
|
|
::
|
|
|
|
pip install -U python-openstackclient
|
|
|
|
OpenStack uses healthcheck timers which run off wall-clock time rather then
|
|
starting a timer and expring the timer, encoding the expiration in the message
|
|
contents. In some cases, this timer interval can be on the order of 60
|
|
seconds. For OpenStack to operate correctly with these tight health-check
|
|
timer intervals, the Kolla community highly recommends running the ntpd
|
|
service on all deployment targets. To install, start, and enable ntp
|
|
execute the following:
|
|
|
|
::
|
|
|
|
# Centos 7
|
|
yum -y install ntp
|
|
systemctl enable ntpd
|
|
systemctl start ntpd
|
|
|
|
# Ubuntu
|
|
sudo 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.
|
|
|
|
::
|
|
|
|
service libvirtd disable
|
|
service libvirtd stop
|
|
|
|
Kolla deploys OpenStack using
|
|
`Ansible <http://www.ansible.com>`__. Install Ansible from distribution
|
|
packaging if the distro packaging has recommended version available.
|
|
|
|
Currently all implemented distro versons of Ansible are too old to use distro packaging.
|
|
Once distro packaging is updated install from packaging using:
|
|
|
|
::
|
|
|
|
yum -y install ansible
|
|
|
|
On DEB based systems this can be done using:
|
|
|
|
::
|
|
|
|
apt-get install ansible
|
|
|
|
If the distro packaged version of Ansible is too old, install Ansible using
|
|
pip:
|
|
|
|
::
|
|
|
|
pip install -U ansible
|
|
|
|
Building Container Images
|
|
--------------------------
|
|
|
|
The Kolla community does not currently generate new images for each commit
|
|
to the repository. The push time for a full image build to the docker registry
|
|
is about 5 hours on 100mbit Internet, so there are technical limitations to
|
|
using the Docker Hub registry with the current OpenStack CI/CD systems.
|
|
|
|
The Kolla community builds and pushes tested images for each tagged release of
|
|
Kolla, but if running from master, it is recommended to build images locally.
|
|
|
|
Before running the below instructions, ensure the docker daemon is running
|
|
or the build process will fail. To build images using default parameters run:
|
|
|
|
::
|
|
|
|
tools/build.py
|
|
|
|
By default docker will build all containers using Centos as base image and
|
|
binary installation as base installation method. To change this behavior,
|
|
please use the following parameters with build.py:
|
|
|
|
::
|
|
|
|
--base [ubuntu|centos|fedora|oraclelinux]
|
|
--type [binary|source]
|
|
|
|
A docker build of all containers on Xeon hardware with SSDs and 100mbit network
|
|
takes roughly 30 minutes. The CentOS mirrors are flakey and the RDO delorean
|
|
repository is not mirrored at all. As a result occasionally some containers
|
|
fail to build. To rectify this, the build tool will automatically attempt three
|
|
retries of a build operation if the first one fails.
|
|
|
|
It is also possible to build individual containers. As an example, if the
|
|
glance containers failed to build, all glance related containers can be
|
|
rebuilt as follows:
|
|
|
|
::
|
|
|
|
tools/build.py glance
|
|
|
|
In order to see all available parameters, run:
|
|
|
|
::
|
|
|
|
tools/build.py -h
|
|
|
|
Deploying Kolla
|
|
---------------
|
|
|
|
The Kolla community provide two example methods of Kolla deploy: *all-in-one* and
|
|
*multinode*. The "all-in-one" deploy is similar to `devstack
|
|
<http://docs.openstack.org/developer/devstack/>`__ deploy which installs all
|
|
OpenStack services on a single host. In the "multinode" deploy, OpenStack
|
|
services can be run on specific hosts. This documentation only describes
|
|
deploying *all-in-one* method as most simple one.
|
|
|
|
Each method is represented as an Ansible inventory file. More information on the
|
|
Ansible inventory file can be found in the Ansible `inventory introduction
|
|
<https://docs.ansible.com/intro_inventory.html>`__.
|
|
|
|
Copy the etc/kolla directory from the git to /etc/kolla on the deployment
|
|
host. All variables for the environment can be specified in the files:
|
|
"/etc/kolla/globals.yml" and "/etc/kolla/passwords.yml"
|
|
|
|
Start by editing /etc/kolla/globals.yml. Check and edit, if needed, these
|
|
parameters: kolla_base_distro, kolla_install_type.
|
|
|
|
The kolla\_\*\_address variables can both be the same. Please specify
|
|
an unused IP address in the network to act as a VIP for
|
|
kolla\_internal\_address. The VIP will be used with keepalived and
|
|
added to the "api\_interface" as specified in the globals.yml
|
|
|
|
::
|
|
|
|
kolla_external_address: "openstack.example.com"
|
|
kolla_internal_address: "10.10.10.254"
|
|
|
|
If the environment doesn't have a free IP address available for VIP
|
|
configuration, the host's IP address may be used here by disabling HAProxy by
|
|
adding:
|
|
|
|
::
|
|
|
|
enable_haproxy: "no"
|
|
|
|
Note this method is not recommended and generally not tested by the
|
|
development community, but included since sometimes a free IP is not available
|
|
in a testing environment.
|
|
|
|
The "network\_interface" variable is the interface to which Kolla binds API
|
|
services. For example, when starting up Mariadb it will bind to the
|
|
IP on the interface list in the "network\_interface" variable.
|
|
|
|
::
|
|
|
|
network_interface: "eth0"
|
|
|
|
The "neutron\_external\_interface" variable is the interface that will
|
|
be used for the external bridge in Neutron. Without this bridge the deployment
|
|
instance traffic will be unable to access the rest of the Internet. In
|
|
the case of a single interface on a machine, a veth pair may be used where
|
|
one end of the veth pair is listed here and the other end is in a bridge on
|
|
the system.
|
|
|
|
::
|
|
|
|
neutron_external_interface: "eth1"
|
|
|
|
The docker\_pull\_policy specifies whether Docker should always pull
|
|
images from the repository it is configured for, or only in the case
|
|
where the image isn't present locally. If building local images without
|
|
pushing them to the Docker registry, please set this value to "missing"
|
|
or when running deployment Docker will attempt to fetch the latest image
|
|
upstream.
|
|
|
|
::
|
|
|
|
docker_pull_policy: "missing"
|
|
|
|
For "all-in-one" deploys, the following commands can be run. These will
|
|
setup all of the containers on the localhost. These commands will be
|
|
wrapped in the kolla-script in the future.
|
|
|
|
::
|
|
|
|
tools/kolla-ansible deploy
|
|
|
|
In order to see all available parameters, run:
|
|
|
|
::
|
|
|
|
tools/kolla-ansible -h
|
|
|
|
A bare metal system with Ceph takes 18 minutes to deploy. A virtual machine
|
|
deployment takes 25 minutes. These are estimates; different hardware may be
|
|
faster or slower but should be near these results.
|
|
|
|
After successful deployment of OpenStack, the Horizon dashboard will be
|
|
avalible by entering IP addr or hostname from "kolla_external_address",
|
|
or kolla_internal_address in case then kolla_external_address uses
|
|
kolla_internal_address.
|
|
|
|
Useful tools
|
|
-------------
|
|
View tools/openrc-example for an example of an openrc that may be used with
|
|
the environment. The following command will initialize an environment with a
|
|
glance image and neutron networks:
|
|
|
|
::
|
|
|
|
tools/init-runonce
|
|
|
|
Debugging Kolla
|
|
---------------
|
|
|
|
The container's status can be determined on the deployment targets by
|
|
executing:
|
|
|
|
::
|
|
|
|
docker ps -a
|
|
|
|
If any of the containers exited, this indicates a bug in the container. Please
|
|
seek help by filing a bug or contacting the developers via IRC.
|
|
|
|
The logs can be examined by executing:
|
|
|
|
::
|
|
|
|
docker exec -it rsyslog bash
|
|
|
|
The logs from all services in all containers may be read from
|
|
/var/log/SERVICE_NAME
|
|
|
|
If the stdout logs are need, please run:
|
|
|
|
::
|
|
|
|
docker logs <container-name>
|
|
|
|
Note that some of the containers don't log to stdout at present so the above
|
|
command will provide no information.
|
|
|
|
To learn more about Docker command line operation please refer to `Docker
|
|
documentation <https://docs.docker.com/reference/commandline/cli/>`__.
|