Merge "Update quickstart instructions"

This commit is contained in:
Zuul 2019-04-10 09:17:42 +00:00 committed by Gerrit Code Review
commit ac98428c95
1 changed files with 146 additions and 48 deletions

View File

@ -5,7 +5,7 @@ Quick Start
===========
This guide provides step by step instructions to deploy OpenStack using Kolla
on bare metal servers or virtual machines.
Ansible on bare metal servers or virtual machines.
Recommended reading
~~~~~~~~~~~~~~~~~~~
@ -25,81 +25,121 @@ The host machine must satisfy the following minimum requirements:
Install dependencies
~~~~~~~~~~~~~~~~~~~~
#. Install and upgrad ``pip`` to the latest before proceeding.
Typically commands that use the system package manager in this section must be
run with root privileges.
It is generally recommended to use a virtual environment to install Kolla
Ansible and its dependencies, to avoid conflicts with the system site packages.
Note that this is independent from the use of a virtual environment for remote
execution, which is described :ref:`here <virtual-environments-target-hosts>`.
#. For CentOS, install EPEL.
.. code-block:: console
sudo yum install epel-release
#. For Ubuntu, update the package index.
.. code-block:: console
sudo apt-get update
#. Install Python build dependencies:
For CentOS, run:
.. code-block:: console
yum install epel-release
yum install python-pip
pip install -U pip
sudo yum install python-devel libffi-devel gcc openssl-devel libselinux-python
For Ubuntu, run:
.. code-block:: console
apt-get update
apt-get install python-pip
pip install -U pip
sudo apt-get install python-dev libffi-dev gcc libssl-dev python-selinux python-setuptools
#. Install the following dependencies:
Install dependencies using a virtual environment
------------------------------------------------
For CentOS, run:
If not installing Kolla Ansible in a virtual environment, skip this section.
#. Install the virtualenv package.
For CentOS or RHEL, run:
.. code-block:: console
yum install python-devel libffi-devel gcc openssl-devel libselinux-python
sudo yum install python-virtualenv
For Ubuntu, run:
.. code-block:: console
apt-get install python-dev libffi-dev gcc libssl-dev python-selinux python-setuptools
sudo apt-get install python-virtualenv
#. Install `Ansible <http://www.ansible.com>`__ from distribution packaging:
.. note::
Some implemented distro versions of Ansible are too old to use distro
packaging. Currently, CentOS and RHEL package Ansible >=2.4 which is suitable
for use with Kolla. Note that you will need to enable access to the EPEL
repository to install via :command:`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>`__.
For CentOS or RHEL, this can be done using:
#. Create a virtual environment and activate it:
.. code-block:: console
yum install ansible
virtualenv /path/to/virtualenv
source /path/to/virtualenv/bin/activate
For Ubuntu, it can be installed by:
The virtual environment should be activated before running any commands that
depend on packages installed in it.
#. Ensure the latest version of pip is installed:
.. code-block:: console
apt-get install ansible
pip install -U pip
#. Use ``pip`` to install or upgrade Ansible to latest version:
#. Install `Ansible <http://www.ansible.com>`__. Currently, Kolla Ansible
requires Ansible 2.4+.
.. code-block:: console
pip install -U ansible
pip install ansible
.. note::
Install dependencies not using a virtual environment
----------------------------------------------------
It is recommended to use virtualenv to install non-system packages.
If installing Kolla Ansible in a virtual environment, skip this section.
#. (optional) Add the following options to ansible configuration file
``/etc/ansible/ansible.cfg``:
#. Install ``pip``.
.. path /etc/ansible/ansible.cfg
.. code-block:: ini
For CentOS or RHEL, run:
[defaults]
host_key_checking=False
pipelining=True
forks=100
.. code-block:: console
sudo yum install python-pip
For Ubuntu, run:
.. code-block:: console
sudo apt-get install python-pip
#. Ensure the latest version of pip is installed:
.. code-block:: console
sudo pip install -U pip
#. Install `Ansible <http://www.ansible.com>`__. Currently, Kolla Ansible
requires Ansible 2.4+.
For CentOS or RHEL, run:
.. code-block:: console
sudo yum install ansible
For Ubuntu, run:
.. code-block:: console
sudo apt-get install ansible
Install Kolla-ansible
~~~~~~~~~~~~~~~~~~~~~
@ -109,23 +149,38 @@ Install Kolla-ansible for deployment or evaluation
#. Install kolla-ansible and its dependencies using ``pip``.
If using a virtual environment:
.. code-block:: console
pip install kolla-ansible
If not using a virtual environment:
.. code-block:: console
sudo pip install kolla-ansible
#. Create the ``/etc/kolla`` directory.
.. code-block:: console
sudo mkdir -p /etc/kolla
sudo chown $USER:$USER /etc/kolla
#. Copy ``globals.yml`` and ``passwords.yml`` to ``/etc/kolla`` directory.
For CentOS, run:
.. code-block:: console
cp -r /usr/share/kolla-ansible/etc_examples/kolla /etc/
cp -r /usr/share/kolla-ansible/etc_examples/kolla/* /etc/kolla
For Ubuntu, run:
.. code-block:: console
cp -r /usr/local/share/kolla-ansible/etc_examples/kolla /etc/
cp -r /usr/local/share/kolla-ansible/etc_examples/kolla/* /etc/kolla
#. Copy ``all-in-one`` and ``multinode`` inventory files to
the current directory.
@ -154,18 +209,33 @@ Install Kolla for development
#. Install requirements of ``kolla`` and ``kolla-ansible``:
If using a virtual environment:
.. code-block:: console
pip install -r kolla/requirements.txt
pip install -r kolla-ansible/requirements.txt
If not using a virtual environment:
.. code-block:: console
sudo pip install -r kolla/requirements.txt
sudo pip install -r kolla-ansible/requirements.txt
#. Create the ``/etc/kolla`` directory.
.. code-block:: console
sudo mkdir -p /etc/kolla
sudo chown $USER:$USER /etc/kolla
#. Copy the configuration files to ``/etc/kolla`` directory.
``kolla-ansible`` holds the configuration files ( ``globals.yml`` and
``passwords.yml``) in ``etc/kolla``.
.. code-block:: console
mkdir -p /etc/kolla
cp -r kolla-ansible/etc/kolla/* /etc/kolla
#. Copy the inventory files to the current directory. ``kolla-ansible`` holds
@ -176,17 +246,36 @@ Install Kolla for development
cp kolla-ansible/ansible/inventory/* .
Configure Ansible
~~~~~~~~~~~~~~~~~
For best results, Ansible configuration should be tuned for your environment.
For example, add the following options to the Ansible configuration file
``/etc/ansible/ansible.cfg``:
.. path /etc/ansible/ansible.cfg
.. code-block:: ini
[defaults]
host_key_checking=False
pipelining=True
forks=100
Further information on tuning Ansible is available `here
<https://www.ansible.com/blog/ansible-performance-tuning>`__.
Prepare initial configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Inventory
---------
Next step is to prepare our inventory file. Inventory is an ansible file where
we specify node roles and access credentials.
The next step is to prepare our inventory file. An inventory is an Ansible file
where we specify hosts and the groups that they belong to. We can use this to
define node roles and access credentials.
Kolla-Ansible comes with ``all-in-one`` and ``multinode`` example inventory
files. Difference between them is that the former is ready for deploying
files. The difference between them is that the former is ready for deploying
single node OpenStack on localhost. If you need to use separate host or more
than one node, edit ``multinode`` inventory:
@ -371,6 +460,11 @@ There are a few options that are required to deploy Kolla-Ansible:
`Services Reference Guide
<https://docs.openstack.org/kolla-ansible/latest/reference/index.html>`_.
* Virtual environment
It is recommended to use a virtual environment to execute tasks on the remote
hosts. This is covered :ref:`here <virtual-environments-target-hosts>`.
Deployment
~~~~~~~~~~
@ -380,6 +474,10 @@ need to setup basic host-level dependencies, like docker.
Kolla-Ansible provides a playbook that will install all required services in
the correct versions.
The following assumes the use of the ``multinode`` inventory. If using a
different inventory, such as ``all-in-one``, replace the ``-i`` argument
accordingly.
* For deployment or evaluation, run:
#. Bootstrap servers with kolla deploy dependencies:
@ -407,19 +505,19 @@ the correct versions.
.. code-block:: console
cd kolla-ansible/tools
./kolla-ansible -i ../ansible/inventory/multinode bootstrap-servers
./kolla-ansible -i ../../multinode bootstrap-servers
#. Do pre-deployment checks for hosts:
.. code-block:: console
./kolla-ansible -i ../ansible/inventory/multinode prechecks
./kolla-ansible -i ../../multinode prechecks
#. Finally proceed to actual OpenStack deployment:
.. code-block:: console
./kolla-ansible -i ../ansible/inventory/multinode deploy
./kolla-ansible -i ../../multinode deploy
When this playbook finishes, OpenStack should be up, running and functional!
If error occurs during execution, refer to