openstack/kolla-ansible
Code Issues Proposed changes

Updated quickstart doc

Browse Source 
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
This commit is contained in:
Proskurin Kirill 2015-11-02 20:38:54 +03:00
parent 45d4191ddf
commit 58ee9c4b84
4 changed files with 222 additions and 287 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
doc/ansible-deployment.rst
View File

@ -1,141 +0,0 @@
Kolla with Ansible!
===================
Kolla supports deploying Openstack using
`Ansible <https://docs.ansible.com>`__.
Getting Started
---------------
To run the Ansible playbooks, an inventory file which tracks all of the
available nodes in the environment must be specified. With this
inventory file Ansible will log into each node via ssh (configurable)
and run tasks. Ansible does not require password-less logins via ssh,
however it is highly recommended to setup ssh-keys.
Two sample inventory files are provided, *all-in-one*, and *multinode*.
The "all-in-one" inventory defaults to use the Ansible "local"
connection type, which removes the need to setup ssh keys in order to
get started quickly.
More information on the Ansible inventory file can be found in the Ansible
`inventory introduction <https://docs.ansible.com/intro_inventory.html>`__.
Prerequisites
-------------
.. 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.3 none On deployment host
Docker 1.6.0 1.8.2 On target nodes
Docker Python 1.2.0 none On target nodes
===================== =========== =========== =========================
Docker Python Library (aka docker-py) is also needed to build images
locally.
Directory Structure
-------------------
When deploying, the following directories will be modified. Make sure
kolla-ansible have permission to access them.
- /etc/kolla/
When deploying, the following directories may be modified. But the path
could be changed in `/etc/kolla/globals.yml`.
- /usr/share/kolla
The sysctl(ansible module) may create temporary file in `/etc/` for
updating sysctl.
Deploying
---------
Add the etc/kolla directory to /etc/kolla on the deployment host. Inside
of this directory are two files and a minimum number of parameters which
are listed below.
All variables for the environment can be specified in the files:
"/etc/kolla/globals.yml" and "/etc/kolla/passwords.yml"
The kolla\_\*\_address variables can both be the same. Please specify
an unused IP address in your network to act as a VIP for
kolla\_internal\_address. The VIP will be used with keepalived and
added to your "api\_interface" as specified in the globals.yml
::
kolla_external_address: "openstack.example.com"
kolla_internal_address: "10.10.10.254"
The "network\_interface" variable is the interface that we bind all our
services to. 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 your external bridge in Neutron. Without this bridge your
instance traffic will be unable to access the rest of the Internet. In
the case of a single interface on a machine, you may use a veth pair
where one end of the veth pair is listed here and the other end is in a
bridge on your 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 you are building your own
images locally without pushing them to the Docker Registry, or a local
registry, you must set this value to "missing" or when you run the
playbooks docker will attempt to fetch the latest image upstream.
::
docker_pull_policy: "always"
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.
::
cd ./kolla/ansible
ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml
To run the playbooks for only a particular service, Ansible tags can be
used. Multiple tags may be specified, and order is still determined by
the playbooks.
::
cd ./kolla/ansible
ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq
ansible-playbook -i inventory/all-in-one -e @/etc/kolla/globals.yml -e @/etc/kolla/passwords.yml site.yml --tags rabbitmq,mariadb
Finally, you can view ./kolla/tools/openrc-example for an example of an
openrc you can use with your environment. If you wish you may also run
the following command to initiate your environment with an glance image
and neutron networks.
::
cd ./kolla/tools
./init-runonce
Further Reading
---------------
Ansible playbook documentation can be found in the Ansible
`playbook documentation <http://docs.ansible.com/playbooks.html>`__.

72
doc/deploy-all-in-one-node.rst
View File

@ -1,72 +0,0 @@
Deploy OpenStack all in one node using Ansible
==============================================
Deploy OpenStack to ubuntu host(ubuntu docker image)
----------------------------------------------------
The machine minimal requirements:
- two network interfaces.
The machine recommended requirements:
- two network interfaces.
- more than 8gb main memory.
- at least 40gb disk space.
It is generally a good idea to run a recent kernel. On Ubuntu LTS::
sudo apt-get install linux-image-generic-lts-vivid
sudo reboot
The guide assumes that you have build images using the following command.
::
tools/build.py --registry 172.22.2.81:4000 --base ubuntu --type source --push
The IP, "172.22.2.81", is the host running private docker registry.
To deploy a private docker registry,
please read the document DeployingRegistryServer_.
First, add ``--insecure-registry 172.22.2.81:4000``
to ``DOCKER_OPTS`` in ``/etc/default/docker``.
And restart the docker service.
This will permit Docker to pull from the deployment's private registry.
Clone the kolla repository and copy kolla config to ``"/etc"``:
::
git clone https://github.com/openstack/kolla
cd kolla
cp -rf etc/kolla/ /etc/
And modify the file, ``"/etc/kolla/globals.yml"``. Do the below tasks.
- Set ``"kolla_base_distro"`` to ``"ubuntu"``.
- Set ``"kolla_install_type"`` to ``"source"``.
- Set ``"docker_registry"`` to ``"172.22.2.81:4000"``.
- Change kolla_internal_address value.
Specify an unissued IP address in the deployment environment
Change the following values if needed:
- network_interface
- neutron_external_interface
After doing these tasks, run the following command in kolla directory:
::
tools/kolla-ansible -i ansible/inventory/all-in-one -p ansible/site.yml deploy
Deployment takes between 10 and 15 minutes from
a local private registry on gigabit networks.
.. _DeployingRegistryServer: https://docs.docker.com/registry/deploying/

2
doc/index.rst
View File

@ -34,8 +34,6 @@ Kolla Overview
deployment-philosophy deployment-philosophy
quickstart quickstart
ansible-deployment
deploy-all-in-one-node
heat-dev-env heat-dev-env
vagrant-dev-env vagrant-dev-env
image-building image-building

294
doc/quickstart.rst
View File

@ -5,25 +5,35 @@ Evaluation and Developer Environments
------------------------------------- -------------------------------------
Two virtualized evaluation and development environment options are Two virtualized evaluation and development environment options are
available. These options permit the evaluation of Kolla without available. These options permit the evaluation of Kolla without
disrupting the host operating system. disrupting the host operating system.
If developing or evaluating Kolla on an OpenStack cloud environment that If developing or evaluating Kolla on an OpenStack cloud environment that
supports Heat, follow the :doc:`Heat evaluation and developer environment guide <devenv-heat>`. 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, If developing or evaluating Kolla on a system that provides VirtualBox or
Vagrant may be used and is documented in the :doc:`Vagrant evaluation and developer environment guide <devenv-vagrant>`. 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 If evaluating or deploying OpenStack on bare-metal with Kolla, follow the
instructions in this document to get started. 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 Installing Dependencies
----------------------- -----------------------
Kolla is tested on Fedora/Ubuntu/CentOS. It should work with other OS Kolla is tested on CentOS, Oracle Linux, RHEL and Ubuntu. It should work with
distributions, but some need further testing. If other OS distributions can other OS distributions, but some need further testing.
be verified, update this doc accordingly. For Fedora/Ubuntu, follow below
recommendations:
Fedora: Kolla will not run on Fedora 22 or later currently. Fedora 22 Fedora: Kolla will not run on Fedora 22 or later currently. Fedora 22
compresses kernel modules with the .xz compressed format. The guestfs system compresses kernel modules with the .xz compressed format. The guestfs system
@ -32,21 +42,32 @@ package supermin in CentOS needs to be updated to add .xz compressed format
support. support.
Ubuntu: For Ubuntu based systems where Docker is used, do not use AUFS when Ubuntu: For Ubuntu based systems where Docker is used, do not use AUFS when
starting Docker daemon unless you are running the Ubuntu with 3.19 kernel or starting Docker daemon, unless running Ubuntu uses 3.19 kernel or above.
above. AUFS requires CONFIG\_AUFS\_XATTR=y set when building the kernel. On 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 Ubuntu, versions prior to 3.19 did not set this flag to be compatible with
Docker. If unable to upgrade the kernel, the Kolla community recommends using Docker. In order to update kernel in Ubuntu 14.04 LTS to 3.19, run:
a different storage backend such as btrfs when running Docker daemon.
On the deployment host Ansible>=1.8.4 must be installed and is the only ::
requirement for deploying OpenStack. To build the Docker container images
locally the dependencies docker>=1.7.0 and the Python libraries
docker-py>=1.2.0 and Jinja2>=2.6 must be installed.
The deployment target nodes require the installation of docker>=1.7.0 and sudo apt-get install linux-image-generic-lts-vivid
docker-py>=1.2.0.
To install Kolla Python dependencies use: 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:
:: ::
@ -63,21 +84,39 @@ command:
curl -sSL https://get.docker.io | bash 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 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. recommends installing the OpenStack python clients if they are not installed.
This could be a completely different machine then the deployment host or This could be a completely different machine then the deployment host or
deployment targets. Before installing the OpenStack python client, there are deployment targets. Before installing the OpenStack python client, the
the following requirements needed by your system: following requirements are needed to build the client code:
:: ::
# Ubuntu # Ubuntu
apt-get install -y python-dev python-pip libffi-dev libssl-dev sudo apt-get install -y python-dev python-pip libffi-dev libssl-dev
# Fedora # Centos 7
yum install -y python-devel python-pip libffi-devel openssl-devel
# Centos
easy_install pip easy_install pip
yum install -y python-devel libffi-devel openssl-devel yum install -y python-devel libffi-devel openssl-devel
@ -89,20 +128,24 @@ To install these clients use:
OpenStack uses healthcheck timers which run off wall-clock time rather then 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 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 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 seconds. For OpenStack to operate correctly with these tight health-check
timer intervals, the Kolla community highly recommends running the ntpd timer intervals, the Kolla community highly recommends running the ntpd
service on all deployment targets. To install, start, and enable ntp on service on all deployment targets. To install, start, and enable ntp
CentOS execute the following: execute the following:
:: ::
# Centos 7
yum -y install ntp yum -y install ntp
chkconfig ntpd enable systemctl enable ntpd
service ntpd start systemctl start ntpd
Libvirt is started by default on many operating systems. Please disable libvirt # Ubuntu
on any machines that will be deployment targets. Only one copy of libvirt may 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. be running at a time.
:: ::
@ -111,10 +154,11 @@ be running at a time.
service libvirtd stop service libvirtd stop
Kolla deploys OpenStack using Kolla deploys OpenStack using
`Ansible <http://www.ansible.com>`__. Install Ansible from distribution `Ansible <http://www.ansible.com>`__. Install Ansible from distribution
packaging if the distro packaging has 1.8.4 or greater available. Currently packaging if the distro packaging has recommended version available.
Ubuntu's version of Ansible is too old to use from packaging. On RPM
based systems install from packaging using: Currently all implemented distro versons of Ansible are too old to use distro packaging.
Once distro packaging is updated install from packaging using:
:: ::
@ -137,49 +181,154 @@ Building Container Images
-------------------------- --------------------------
The Kolla community does not currently generate new images for each commit 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 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 is about 5 hours on 100mbit Internet, so there are technical limitations to
using the Docker Hub registry with our current OpenStack CI/CD systems. 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 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, but if running from master, it is recommended to build images locally.
All Docker images can be built as follows.
Before running the below instructions, ensure the docker daemon is running Before running the below instructions, ensure the docker daemon is running
or the build process would fail: or the build process will fail. To build images using default parameters run:
:: ::
tools/build.py 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 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 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 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 fail to build. To rectify this, the build tool will automatically attempt three
retries of a build operation if the first one fails. retries of a build operation if the first one fails.
It is also possible to build individual containers. If for some reason the glance It is also possible to build individual containers. As an example, if the
containers failed to build, all glance related containers can be rebuilt as follows: glance containers failed to build, all glance related containers can be
rebuilt as follows:
:: ::
tools/build.py glance tools/build.py glance
Starting Kolla In order to see all available parameters, run:
--------------
Configure Ansible by reading the
:doc:`Kolla Ansible configuration Guide <ansible-deployment>` documentation.
Finally, run the deploy operation:
:: ::
./tools/kolla-ansible deploy tools/build.py -h
A bare metal system takes three minutes to deploy AIO. A virtual machine Deploying Kolla
deployment takes five minutes to deploy AIO. These are estimates; different ---------------
hardware may be faster or slower but should be near these results.
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 Debugging Kolla
--------------- ---------------
@ -191,25 +340,26 @@ executing:
docker ps -a docker ps -a
If any of the containers exited, this indicates a bug in the container. Please 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. seek help by filing a bug or contacting the developers via IRC.
the logs can be examined by executing: 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> docker logs <container-name>
Note some of the containers don't log to stdout at present so the above Note that some of the containers don't log to stdout at present so the above
command will provide no information. Instead they log to files command will provide no information.
in /var/log/<service_> inside the container. The Kolla community is
working to improve auditing and make things more consistent. The Kolla
community expects this work to complete by Liberty rc1. An example of
reading the logs for nova-api:
:: To learn more about Docker command line operation please refer to `Docker
documentation <https://docs.docker.com/reference/commandline/cli/>`__.
docker exec -t nova_api more /var/log/nova/nova-api.log
Note reading the logs via an exec operation can only be done if the
container is running.