openstack/kolla
Code Issues Proposed changes

Improve Quick Start documentation

Browse Source 
Made improvents to the quickstart guide

Moved the troubleshooting section from quickstart guide to a new
document troubleshooting.rst

Change-Id: I0f08d8743682390b2fe8071ab2484e251f2ef803
This commit is contained in:
Sayantani Goswami
2016-11-30 22:13:10 +00:00
committed by sayantani
parent e6fee0d907
commit db75665e1d
3 changed files with 469 additions and 376 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/index.rst
View File

@@ -55,6 +55,7 @@ Kolla Overview
advanced-configuration
operating-kolla
security
troubleshooting
Kolla Services
==============

704
doc/quickstart.rst
View File

@@ -4,79 +4,73 @@
Quick Start
===========
This guide provides a step by step procedure to deploy Kolla on bare metal or a
virtual machine.
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 recommended deployment target requirements:
The host machine must satisfy the following minimum requirements:
- 2 (or more) network interfaces.
- At least 8GB main memory.
- At least 40GB disk space.
- 2 network interfaces
- 8GB main memory
- 40GB disk space
.. note:: Some commands below may require root permissions (e.g. pip, apt-get).
.. note::
Recommended Environment
Root access to the deployment host machine is required.
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`_.
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.
Automatic host bootstrap
========================
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`.
.. note:: New in Newton
Prerequisites
=============
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:
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.
::
kolla-ansible -i <<inventory file>> bootstrap-servers
ip addr show
To learn more about the inventory file, follow :ref:`edit-inventory`.
Bring up the second network interface if it is down.
::
Install Dependencies
ip link set ens4 up
Verify if the second interface has an IP address.
::
ip addr show
Install dependencies
====================
Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu as both container OS
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.
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 back ends such as
AUFS and OverlayFS. In order to update kernel in Ubuntu 14.04 LTS to 4.2, run:
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
.. 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.
@@ -86,14 +80,14 @@ Dependencies for the stable/mitaka branch are:
===================== =========== =========== =========================
Component Min Version Max Version Comment
===================== =========== =========== =========================
Ansible 1.9.4 < 2.0.0 On deployment host
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 stable/newton and later (including master branch) are:
Dependencies for the stable/newton branch and later (including master branch)
are:
===================== =========== =========== =========================
Component Min Version Max Version Comment
@@ -104,32 +98,78 @@ 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
Make sure the ``pip`` package manager is installed and upgraded to the latest
before proceeding:
::
# CentOS 7
#CentOS
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
#Ubuntu
apt-get update
apt-get install python-pip
pip install -U pip
Install dependencies needed to build the code with ``pip`` package manager.
::
# Ubuntu
#CentOS
yum install python-devel libffi-devel gcc openssl-devel
#Ubuntu
apt-get install python-dev libffi-dev gcc libssl-dev
# CentOS 7
yum install python-devel libffi-devel gcc openssl-devel
Kolla deploys OpenStack using `Ansible <http://www.ansible.com>`__. 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
<https://fedoraproject.org/wiki/EPEL>`__ and `FAQ
<https://fedoraproject.org/wiki/EPEL/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.
@@ -176,38 +216,6 @@ Restart Docker by executing the following commands:
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
mount --make-shared /var/lib/nova/mnt
If ``/var/lib/nova/mnt`` is not partitioned, can do below work around
::
mkdir -p /var/lib/nova/mnt /var/lib/nova/mnt1
mount --bind /var/lib/nova/mnt1 /var/lib/nova/mnt
mount --make-shared /var/lib/nova/mnt
For mounting ``/run`` and ``/var/lib/nova/mnt`` as shared upon startup,
add below commands to ``/etc/rc.local``
::
# Edit /etc/rc.local to add:
mount --make-shared /run
mount --make-shared /var/lib/nova/mnt
.. note:: If centos/fedora/oraclelinux container images are built on an Ubuntu
host, the back-end 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:
@@ -268,7 +276,8 @@ On Ubuntu, apparmor will sometimes prevent libvirt from working.
::
/usr/sbin/libvirtd: error while loading shared libraries: libvirt-admin.so.0: cannot open shared object file: Permission denied
/usr/sbin/libvirtd: error while loading shared libraries:
libvirt-admin.so.0: cannot open shared object file: Permission denied
If you are seeing the libvirt container fail with the error above, disable the
libvirt profile.
@@ -276,166 +285,217 @@ libvirt profile.
::
sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.libvirtd
sudo ln -s /etc/apparmor.d/usr.sbin.libvirtd /etc/apparmor.d/disable/
Kolla deploys OpenStack using `Ansible <http://www.ansible.com>`__. 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 <https://fedoraproject.org/wiki/EPEL>`__ and
`FAQ <https://fedoraproject.org/wiki/EPEL/FAQ>`__.
.. note::
On CentOS or RHEL systems, this can be done using:
On Ubuntu 16.04, please uninstall lxd and lxc packages. (An issue exists
with cgroup mounts, mounts exponentially increasing when restarting
container).
Additional steps for upstart and other non-systemd distros
==========================================================
For Ubuntu 14.04 which uses upstart and other non-systemd distros, run the
following.
::
yum install ansible
mount --make-shared /run
mount --make-shared /var/lib/nova/mnt
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:
If /var/lib/nova/mnt is not present, can do below work around.
::
pip install -U ansible
mkdir -p /var/lib/nova/mnt /var/lib/nova/mnt1
mount --bind /var/lib/nova/mnt1 /var/lib/nova/mnt
mount --make-shared /var/lib/nova/mnt
If DEB based systems include a version of Ansible that meets Kolla's version
requirements it can be installed by:
For mounting /run and /var/lib/nova/mnt as shared upon startup, edit
/etc/rc.local to add the following.
::
apt-get install ansible
mount --make-shared /run
mount --make-shared /var/lib/nova/mnt
.. 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.
.. note::
Installing Kolla for evaluation or deployment
---------------------------------------------
If CentOS/Fedora/OracleLinux container images are built on an Ubuntu host,
the back-end storage driver must not be AUFS (see the known issues in
:doc:`image-building`).
Install Kolla and its dependencies:
Install Kolla for deployment or evaluation
==========================================
Install Kolla and its dependencies using pip.
::
pip install kolla
Copy the Kolla configuration files to ``/etc``:
Copy the configuration files globals.yml and passwords.yml to /etc directory.
::
# CentOS 7
cp -r /usr/share/kolla/etc_examples/kolla /etc/
#CentOS
cp -r /usr/share/kolla/etc_examples/kolla /etc/kolla/
# Ubuntu
cp -r /usr/local/share/kolla/etc_examples/kolla /etc/
#Ubuntu
cp -r /usr/local/share/kolla/etc_examples/kolla /etc/kolla/
Installing Kolla and dependencies for development
-------------------------------------------------
To clone the Kolla repo:
The inventory files (all-in-one and multinode) are located in
/usr/local/share/kolla/ansible/inventory. Copy the configuration files to the
current directory.
::
git clone https://git.openstack.org/openstack/kolla
#CentOS
cp /usr/share/kolla/ansible/inventory/* .
To install Kolla's Python dependencies use:
#Ubuntu
cp /usr/local/share/kolla/ansible/inventory/* .
Install Kolla for development
=============================
Clone the Kolla and Kolla-Ansible repositories from git.
::
pip install -r kolla/requirements.txt -r kolla/test-requirements.txt
git clone https://github.com/openstack/kolla
git clone https://github.com/openstack/kolla-ansible
.. note:: This does not actually install Kolla. Many commands in this documentation are named
differently in the tools directory.
Kolla holds configurations files in ``etc/kolla``. Copy the configuration files
to ``/etc``:
Kolla-ansible holds configuration files (globals.yml and passwords.yml) in
etc/kolla. Copy the configuration files to /etc directory.
::
cd kolla
cp -r etc/kolla /etc/
cp -r kolla-ansible/etc/kolla /etc/kolla/
Install Python Clients
======================
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. Install dependencies needed to build the code with ``pip``
package manager as explained earlier.
To install the clients use:
Kolla-ansible holds the inventory files (all-in-one and multinode) in
ansible/inventory. Copy the configuration files to the current directory.
::
yum install python-openstackclient python-neutronclient
Or using ``pip`` to install:
::
pip install -U python-openstackclient python-neutronclient
cp kolla-ansible/ansible/inventory/* .
Local Registry
==============
A local registry is not required for an ``all-in-one`` installation. Check out
the :doc:`multinode` for more information on using a local registry. Otherwise,
the `Docker Hub Image Registry`_ contains all images from each of Kolla's major
releases. The latest release tag is 3.0.0 for Newton.
A local registry is recommended but not required for an ``all-in-one``
installation when developing for master. Since no master images are available
on docker hub, the docker cache may be used for all-in-one deployments. When
deploying multinode, a registry is strongly recommended to serve as a single
source of images. Reference the :doc:`multinode` for more information on using
a local Docker registry. Otherwise, the Docker Hub Image Registry contains all
images from each of Kolla’s major releases. The latest release tag is 3.0.2 for
Newton.
Additional Environments
=======================
Automatic host bootstrap
========================
Two virtualized development environment options are available for Kolla. These
options permit the development of Kolla without disrupting the host operating
system.
Edit the ``/etc/kolla/globals.yml`` file to configure interfaces.
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`.
::
Building Container Images
=========================
network_interface: “ens3”
neutron_external_interface: “ens4"
Generate passwords. This will populate all empty fields in the
``/etc/kolla/passwords.yml`` file using randomly generated values to secure the
deployment. Optionally, the passwords may be populated in the file by hand.
::
kolla-genpwd
To quickly prepare hosts, 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 the cluster for OpenStack installation.
::
kolla-ansible -i <<inventory file>> bootstrap-servers
Build container images
======================
When running with systemd, edit the file
``/etc/systemd/system/docker.service.d/kolla.conf``
to include the MTU size to be used for Docker containers.
::
[Service]
MountFlags=shared
ExecStart=
ExecStart=/usr/bin/docker daemon \
-H fd:// \
--mtu 1400
.. note::
The MTU size should be less than or equal to the MTU size allowed on the
network interfaces of the host machine. If the MTU size allowed on the
network interfaces of the host machine is 1500 then this step can be
skipped. This step is relevant for building containers. Actual openstack
services won't be affected.
.. note::
Verify that the MountFlags parameter is configured as shared. 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.
Restart Docker and ensure that Docker is running.
::
systemctl daemon-reload
systemctl restart docker
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.
Kolla. Pull required images with appropriate tags.
Checkout the :doc:`image-building` for more advanced build configuration.
::
Before running the below instructions, ensure the Docker daemon is running
or the build process will fail. To build images using default parameters run:
kolla-ansible pull
View the images.
::
docker images
Developers running from master are required to build container images as
the Docker Hub does not contain built images for the master branch.
Reference the :doc:`image-building` for more advanced build configuration.
To build images using default parameters run:
::
kolla-build
By default ``kolla-build`` will build all containers using CentOS as the base
image and binary installation as base installation method. To change this
behavior, please use the following parameters with ``kolla-build``:
By default kolla-build will build all containers using CentOS as the base image
and binary installation as base installation method. To change this behavior,
please use the following parameters with kolla-build:
::
--base [ubuntu|centos|oraclelinux]
--type [binary|source]
--base [ubuntu|centos|oraclelinux]
--type [binary|source]
Note ``--base`` and ``--type`` can be added to the above ``kolla-build``
command if different distributions or types are desired.
.. note::
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:
--base and --type can be added to the above kolla-build command if
different distributions or types are desired.
It is also possible to build individual container images. As an example, if the
glance images failed to build, all glance related images can be rebuilt as
follows:
::
@@ -447,26 +507,27 @@ In order to see all available parameters, run:
kolla-build -h
For more information about building Kolla container images, check the detailed
instruction in :doc:`image-building`.
View the images.
::
docker images
.. WARNING::
Mixing of OpenStack releases with Kolla releases (example, updating
kolla-build.conf to build Mitaka Keystone to be deployed with Newton Kolla) is
not recommended and will likely cause issues.
.. _deploying-kolla:
Deploy Kolla
============
Deploying Kolla
===============
The Kolla community provides 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. To setup
*multinode* see the :doc:`multinode`.
Kolla-Ansible is used to deploy containers by using images built by Kolla.
There are two methods of deployment: *all-in-one* and *multinode*. The
*all-in-one* deployment is similar to `devstack
<http://docs.openstack.org/developer/devstack/>`__ deploy which installs all
OpenStack services on a single host. In the *multinode* deployment, OpenStack
services can be run on specific hosts. This documentation describes deploying
an *all-in-one* setup. To setup *multinode* see the :doc:`multinode`.
Each method is represented as an Ansible inventory file. More information on
the Ansible inventory file can be found in the Ansible `inventory introduction
@@ -485,229 +546,128 @@ deployment. Optionally, the passwords may be populate in the file by hand.
kolla-genpwd
Start by editing ``/etc/kolla/globals.yml``. Check and edit, if needed, these
parameters: ``kolla_base_distro``, ``kolla_install_type``. These parameters
should match what you used in the ``kolla-build`` command line. The default for
parameters: ``kolla_base_distro``, ``kolla_install_type``. The default for
``kolla_base_distro`` is ``centos`` and for ``kolla_install_type`` is
``binary``. If you want to use ubuntu with source type, then you should make
sure ``globals.yml`` has the following entries:
sure globals.yml has the following entries:
::
kolla_base_distro: "ubuntu"
kolla_base_distro: “ubuntu"
kolla_install_type: "source"
Please specify an unused IP address in the network to act as a VIP for
``kolla_internal_vip_address``. The VIP will be used with keepalived and added
to the ``api_interface`` as specified in the ``globals.yml`` ::
to the ``api_interface`` as specified in the ``globals.yml``
kolla_internal_vip_address: "10.10.10.254"
::
kolla_internal_vip_address: “192.168.137.79”
.. note::
The kolla_internal_vip_address must be unique and should belong to the same
network to which the first network interface belongs to.
.. note::
The kolla_base_distro and kolla_install_type should be same as base and
install_type used in kolla-build command line.
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. ::
services. For example, when starting Mariadb, it will bind to the IP on the
interface list in the ``network_interface`` variable.
network_interface: "eth0"
::
network_interface: "ens3"
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. ::
traffic will be unable to access the rest of the Internet.
neutron_external_interface: "eth1"
::
For *all-in-one* deploys, the following commands can be run. These will
neutron_external_interface: "ens4"
In case of deployment using the **nested** environment (eg. Using Virtualbox
VM’s, KVM VM’s), verify if your compute node supports hardware acceleration for
virtual machines by executing the following command in the *compute node*.
::
egrep -c '(vmx|svm)' /proc/cpuinfo
If this command returns a value of **zero**, your compute node does not support
hardware acceleration and you **must** configure libvirt to use **QEMU**
instead of KVM. Create a file /etc/kolla/config/nova/nova-compute.conf and add
the content shown below.
::
mkdir /etc/kolla/config/nova
cat << EOF > /etc/kolla/config/nova/nova-compute.conf
[libvirt]
virt_type=qemu
EOF
For *all-in-one* deployments, 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.
.. note:: Even for all-in-one installs it is possible to use the Docker
registry for deployment, although not strictly required.
First, check that the deployment targets are in a state where Kolla may deploy
to them:
First, validate that the deployment targets are in a state where Kolla may
deploy to them. Provide the correct path to inventory file in the following
commands.
::
kolla-ansible prechecks
kolla-ansible prechecks -i /path/to/all-in-one
Verify that all required images with appropriate tags are available:
Deploy OpenStack.
::
kolla-ansible pull
kolla-ansible deploy -i /path/to/all-in-one
Run the deployment:
List the running containers.
::
kolla-ansible deploy
docker ps -a
If APIError/HTTPError is received from the neutron-dhcp-agent container,
remove the container and recreate it:
Generate the ``admin-openrc.sh`` file. The file will be created in
``/etc/kolla/`` directory.
::
docker rm -v -f neutron_dhcp_agent
kolla-ansible deploy
kolla-ansible post-deploy
In order to see all available parameters, run:
To test your deployment, run the following commands to initialize the network
with a glance image and neutron networks.
::
kolla-ansible -h
source /etc/kolla/admin-openrc.sh
.. note:: In case of deploying using the _nested_ environment (*eg*.
Using Virtualbox VM's, KVM VM's), if your compute node supports
hardware acceleration for virtual machines.
#centOS
cd /usr/share/kolla
./init-runonce
For this, run the follow command in **compute node**:
#ubuntu
cd /usr/local/share/kolla
./init-runonce
::
.. note::
egrep -c '(vmx|svm)' /proc/cpuinfo
If this command returns a value of **zero**, your compute node does not
support hardware acceleration and you **must** configure libvirt to use
**QEMU** instead of KVM.
For this, change the **virt_type** option in the `[libvirt]` section
of **nova-compute.conf** file inside the ``/etc/kolla/config/`` directory.
::
[libvirt]
virt_type=qemu
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.
Different hardware results in results in variance with deployment times.
After successful deployment of OpenStack, the Horizon dashboard will be
available by entering IP address or hostname from ``kolla_external_fqdn``, or
``kolla_internal_fqdn``. If these variables were not set during deploy they
default to ``kolla_internal_vip_address``.
Useful tools
------------
After successful deployment of OpenStack, run the following command can create
an openrc file ``/etc/kolla/admin-openrc.sh`` on the deploy node. Or view
``tools/openrc-example`` for an example of an openrc that may be used with the
environment.
::
kolla-ansible post-deploy
After the openrc file is created, use the following command to initialize an
environment with a glance image and neutron networks:
::
. /etc/kolla/admin-openrc.sh
kolla/tools/init-runonce
Failures
========
Nearly always when Kolla fails, it is caused by a CTRL-C during the deployment
process or a problem in the ``globals.yml`` configuration.
To correct the problem where Operators have a misconfigured environment, the
Kolla developers have added a precheck feature which ensures the deployment
targets are in a state where Kolla may deploy to them. To run the prechecks,
execute:
::
kolla-ansible prechecks
If a failure during deployment occurs it nearly always occurs during evaluation
of the software. Once the Operator learns the few configuration options
required, it is highly unlikely they will experience a failure in deployment.
Deployment may be run as many times as desired, but if a failure in a
bootstrap task occurs, a further deploy action will not correct the problem.
In this scenario, Kolla's behavior is undefined.
The fastest way during evaluation to recover from a deployment failure is to
remove the failed deployment:
On each node where OpenStack is deployed run:
::
tools/cleanup-containers
tools/cleanup-host
The Operator will have to copy via scp or some other means the cleanup scripts
to the various nodes where the failed containers are located.
Any time the tags of a release change, it is possible that the container
implementation from older versions won't match the Ansible playbooks in a new
version. If running multinode from a registry, each node's Docker image cache
must be refreshed with the latest images before a new deployment can occur. To
refresh the Docker cache from the local Docker registry:
::
kolla-ansible pull
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 `launchpad bug`_ or contacting the developers via IRC.
The logs can be examined by executing:
::
docker exec -it heka bash
The logs from all services in all containers may be read from
``/var/log/kolla/SERVICE_NAME``
If the stdout logs are needed, please run:
::
docker logs <container-name>
Note that most of the containers don't log to stdout 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/>`__.
When ``enable_central_logging`` is enabled, to view the logs in a web browser
using Kibana, go to:
::
http://<kolla_internal_vip_address>:<kibana_server_port>
or http://<kolla_external_vip_address>:<kibana_server_port>
and authenticate using ``<kibana_user>`` and ``<kibana_password>``.
The values ``<kolla_internal_vip_address>``, ``<kolla_external_vip_address>``
``<kibana_server_port>`` and ``<kibana_user>`` can be found in
``<kolla_install_path>/kolla/ansible/group_vars/all.yml`` or if the default
values are overridden, in ``/etc/kolla/globals.yml``. The value of
``<kibana_password>`` can be found in ``/etc/kolla/passwords.yml``.
.. note:: When you log in to Kibana web interface for the first time, you are
prompted to create an index. Please create an index using the name ``log-*``.
This step is necessary until the default Kibana dashboard is implemented in
Kolla.
.. _Docker Hub Image Registry: https://hub.docker.com/u/kolla/
.. _launchpad bug: https://bugs.launchpad.net/kolla/+filebug

132
doc/troubleshooting.rst Normal file
View File

@@ -0,0 +1,132 @@
.. troubleshooting:
=====================
Troubleshooting Guide
=====================
Failures
========
If Kolla fails, often it is caused by a CTRL-C during the deployment
process or a problem in the ``globals.yml`` configuration.
To correct the problem where Operators have a misconfigured environment, the
Kolla community has added a precheck feature which ensures the deployment
targets are in a state where Kolla may deploy to them. To run the prechecks,
execute:
Production
==========
::
kolla-ansible prechecks
Development
===========
::
./tools/kolla-ansible prechecks
If a failure during deployment occurs it nearly always occurs during evaluation
of the software. Once the Operator learns the few configuration options
required, it is highly unlikely they will experience a failure in deployment.
Deployment may be run as many times as desired, but if a failure in a
bootstrap task occurs, a further deploy action will not correct the problem.
In this scenario, Kolla's behavior is undefined.
The fastest way during to recover from a deployment failure is to
remove the failed deployment:
Production
==========
::
kolla-ansible destroy -i <<inventory-file>>
Development
===========
::
./tools/kolla-ansible destroy -i <<inventory-file>>
Any time the tags of a release change, it is possible that the container
implementation from older versions won't match the Ansible playbooks in a new
version. If running multinode from a registry, each node's Docker image cache
must be refreshed with the latest images before a new deployment can occur. To
refresh the docker cache from the local Docker registry:
Production
==========
::
kolla-ansible pull
Development
===========
::
./tools/kolla-ansible pull
Debugging Kolla
===============
The status of containers after deployment 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 `launchpad bug`_ or contacting the developers via IRC.
The logs can be examined by executing:
::
docker exec -it heka bash
The logs from all services in all containers may be read from
``/var/log/kolla/SERVICE_NAME``
If the stdout logs are needed, please run:
::
docker logs <container-name>
Note that most of the containers don't log to stdout 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/>`__.
When ``enable_central_logging`` is enabled, to view the logs in a web browser
using Kibana, go to:
::
http://<kolla_internal_vip_address>:<kibana_server_port>
or http://<kolla_external_vip_address>:<kibana_server_port>
and authenticate using ``<kibana_user>`` and ``<kibana_password>``.
The values ``<kolla_internal_vip_address>``, ``<kolla_external_vip_address>``
``<kibana_server_port>`` and ``<kibana_user>`` can be found in
``<kolla_install_path>/kolla/ansible/group_vars/all.yml`` or if the default
values are overridden, in ``/etc/kolla/globals.yml``. The value of
``<kibana_password>`` can be found in ``/etc/kolla/passwords.yml``.
.. note:: When you log in to Kibana web interface for the first time, you are
prompted to create an index. Please create an index using the name ``log-*``.
This step is necessary until the default Kibana dashboard is implemented in
Kolla.
.. _launchpad bug: https://bugs.launchpad.net/kolla/+filebug