Merge "Add Quickstart Developer Guide"
This commit is contained in:
Zuul
Gerrit Code Review
commit
01faefc4c4
@ -6,6 +6,7 @@ User Guides
|
||||
:maxdepth: 2
|
||||
|
||||
quickstart
|
||||
quickstart-development
|
||||
support-matrix
|
||||
virtual-environments
|
||||
multinode
|
||||
|
||||
340
doc/source/user/quickstart-development.rst
Normal file
340
doc/source/user/quickstart-development.rst
Normal file
@ -0,0 +1,340 @@
|
||||
.. quickstart-development:
|
||||
|
||||
===========================
|
||||
Quick Start for development
|
||||
===========================
|
||||
|
||||
This guide provides step by step instructions to deploy OpenStack using Kolla
|
||||
Ansible on bare metal servers or virtual machines. For deployment/evaluation we
|
||||
have the :kolla-ansible-doc:`quickstart <user/quickstart>` guide.
|
||||
|
||||
Recommended reading
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
It's beneficial to learn basics of both `Ansible <https://docs.ansible.com>`__
|
||||
and `Docker <https://docs.docker.com>`__ before running Kolla Ansible.
|
||||
|
||||
Host machine requirements
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The host machine must satisfy the following minimum requirements:
|
||||
|
||||
- 2 network interfaces
|
||||
- 8GB main memory
|
||||
- 40GB disk space
|
||||
|
||||
See the :kolla-ansible-doc:`support matrix <user/support-matrix>` for details
|
||||
of supported host Operating Systems. Kolla Ansible supports the default Python
|
||||
3.x versions provided by the supported Operating Systems. For more information
|
||||
see `tested runtimes <|TESTED_RUNTIMES_GOVERNANCE_URL|>`_.
|
||||
|
||||
Install dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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 in
|
||||
:kolla-ansible-doc:`Virtual Environments <user/virtual-environments.html>`.
|
||||
|
||||
#. For Debian or Ubuntu, update the package index.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo apt update
|
||||
|
||||
#. Install Python build dependencies:
|
||||
|
||||
For CentOS, RHEL or openEuler, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo dnf install python3-devel libffi-devel gcc openssl-devel python3-libselinux
|
||||
|
||||
For Debian or Ubuntu, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo apt install python3-dev libffi-dev gcc libssl-dev
|
||||
|
||||
Install dependencies for the virtual environment
|
||||
------------------------------------------------
|
||||
|
||||
#. Install the virtual environment dependencies.
|
||||
|
||||
For CentOS, RHEL or openEuler, you don't need to do anything.
|
||||
|
||||
For Debian or Ubuntu, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo apt install python3-venv
|
||||
|
||||
#. Create a virtual environment and activate it:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
python3 -m venv /path/to/venv
|
||||
source /path/to/venv/bin/activate
|
||||
|
||||
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
|
||||
|
||||
pip install -U pip
|
||||
|
||||
#. Install `Ansible <http://www.ansible.com>`__. Kolla Ansible requires at least
|
||||
Ansible ``4`` and supports up to ``5``.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pip install 'ansible>=4,<6'
|
||||
|
||||
Install Kolla-ansible
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
#. Clone ``kolla-ansible`` repository from git.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
git clone --branch |KOLLA_BRANCH_NAME| https://opendev.org/openstack/kolla-ansible
|
||||
|
||||
#. Install requirements of ``kolla`` and ``kolla-ansible``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pip install ./kolla-ansible
|
||||
|
||||
#. 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
|
||||
|
||||
cp -r kolla-ansible/etc/kolla/* /etc/kolla
|
||||
|
||||
#. Copy the inventory files to the current directory. ``kolla-ansible`` holds
|
||||
inventory files (``all-in-one`` and ``multinode``) in the
|
||||
``ansible/inventory`` directory.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cp kolla-ansible/ansible/inventory/* .
|
||||
|
||||
Install Ansible Galaxy requirements
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Install Ansible Galaxy dependencies:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
kolla-ansible install-deps
|
||||
|
||||
Prepare initial configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Inventory
|
||||
---------
|
||||
|
||||
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. The difference between them is that the former is ready for deploying
|
||||
single node OpenStack on localhost. In this Guide we will show the
|
||||
``all-in-one`` Installation.
|
||||
|
||||
Kolla passwords
|
||||
---------------
|
||||
|
||||
Passwords used in our deployment are stored in ``/etc/kolla/passwords.yml``
|
||||
file. All passwords are blank in this file and have to be filled either
|
||||
manually or by running random password generator:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd kolla-ansible/tools
|
||||
./generate_passwords.py
|
||||
|
||||
Kolla globals.yml
|
||||
-----------------
|
||||
|
||||
``globals.yml`` is the main configuration file for Kolla Ansible and per
|
||||
default stored in /etc/kolla/globals.yml.
|
||||
There are a few options that are required to deploy Kolla Ansible:
|
||||
|
||||
* Image options
|
||||
|
||||
User has to specify images that are going to be used for our deployment.
|
||||
In this guide
|
||||
`Quay.io <https://quay.io/organization/openstack.kolla>`__-provided,
|
||||
pre-built images are going to be used. To learn more about building
|
||||
mechanism, please refer :kolla-doc:`Building Container Images
|
||||
<admin/image-building.html>`.
|
||||
|
||||
Kolla provides choice of several Linux distributions in containers:
|
||||
|
||||
- CentOS Stream (``centos``)
|
||||
- Debian (``debian``)
|
||||
- Rocky (``rocky``)
|
||||
- Ubuntu (``ubuntu``)
|
||||
|
||||
For newcomers, we recommend to use Rocky Linux 9 or Ubuntu 22.04.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
kolla_base_distro: "rocky"
|
||||
|
||||
* Networking
|
||||
|
||||
Kolla Ansible requires a few networking options to be set.
|
||||
We need to set network interfaces used by OpenStack.
|
||||
|
||||
First interface to set is "network_interface". This is the default interface
|
||||
for multiple management-type networks.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
network_interface: "eth0"
|
||||
|
||||
Second interface required is dedicated for Neutron external (or public)
|
||||
networks, can be vlan or flat, depends on how the networks are created.
|
||||
This interface should be active without IP address. If not, instances
|
||||
won't be able to access to the external networks.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
neutron_external_interface: "eth1"
|
||||
|
||||
To learn more about network configuration, refer
|
||||
:kolla-ansible-doc:`Network overview
|
||||
<admin/production-architecture-guide.html#network-configuration>`.
|
||||
|
||||
Next we need to provide floating IP for management traffic. This IP will be
|
||||
managed by keepalived to provide high availability, and should be set to be
|
||||
*not used* address in management network that is connected to our
|
||||
``network_interface``. If you use an existing OpenStack installation for your
|
||||
deployment, make sure the IP is allowed in the configuration of your VM.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
kolla_internal_vip_address: "10.1.0.250"
|
||||
|
||||
* Enable additional services
|
||||
|
||||
By default Kolla Ansible provides a bare compute kit, however it does provide
|
||||
support for a vast selection of additional services. To enable them, set
|
||||
``enable_*`` to "yes".
|
||||
|
||||
Kolla now supports many OpenStack services, there is
|
||||
`a list of available services
|
||||
<https://opendev.org/openstack/kolla-ansible/src/branch/master/README.rst#openstack-services>`_.
|
||||
For more information about service configuration, Please refer to the
|
||||
:kolla-ansible-doc:`Services Reference Guide
|
||||
<reference/index.html>`.
|
||||
|
||||
* Multiple globals files
|
||||
|
||||
For a more granular control, enabling any option from the main
|
||||
``globals.yml`` file can now be done using multiple yml files. Simply,
|
||||
create a directory called ``globals.d`` under ``/etc/kolla/`` and place
|
||||
all the relevant ``*.yml`` files in there. The ``kolla-ansible`` script
|
||||
will, automatically, add all of them as arguments to the ``ansible-playbook``
|
||||
command.
|
||||
|
||||
An example use case for this would be if an operator wants to enable cinder
|
||||
and all its options, at a later stage than the initial deployment, without
|
||||
tampering with the existing ``globals.yml`` file. That can be achieved, using
|
||||
a separate ``cinder.yml`` file, placed under the ``/etc/kolla/globals.d/``
|
||||
directory and adding all the relevant options in there.
|
||||
|
||||
* Virtual environment
|
||||
|
||||
It is recommended to use a virtual environment to execute tasks on the remote
|
||||
hosts. This is covered in
|
||||
:kolla-ansible-doc:`Virtual Environments <user/virtual-environments.html>`.
|
||||
|
||||
Deployment
|
||||
~~~~~~~~~~
|
||||
|
||||
After configuration is set, we can proceed to the deployment phase. First we
|
||||
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 ``all-in-one`` inventory. If using a
|
||||
different inventory, such as ``multinode``, replace the ``-i`` argument
|
||||
accordingly.
|
||||
|
||||
#. Bootstrap servers with kolla deploy dependencies:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd kolla-ansible/tools
|
||||
./kolla-ansible -i ../../all-in-one bootstrap-servers
|
||||
|
||||
#. Do pre-deployment checks for hosts:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
kolla-ansible -i ../../all-in-one prechecks
|
||||
|
||||
#. Finally proceed to actual OpenStack deployment:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
kolla-ansible -i ../../all-in-one deploy
|
||||
|
||||
When this playbook finishes, OpenStack should be up, running and functional!
|
||||
If error occurs during execution, refer to
|
||||
:kolla-ansible-doc:`troubleshooting guide <user/troubleshooting.html>`.
|
||||
|
||||
Using OpenStack
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
#. Install the OpenStack CLI client:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pip install python-openstackclient -c https://releases.openstack.org/constraints/upper/|KOLLA_OPENSTACK_RELEASE|
|
||||
|
||||
#. OpenStack requires a ``clouds.yaml`` file where credentials for the
|
||||
admin user are set. To generate this file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd kolla-ansible/tools
|
||||
./kolla-ansible post-deploy
|
||||
|
||||
* The file will be generated in /etc/kolla/clouds.yaml, you can use it by
|
||||
copying it to /etc/openstack or ~/.config/openstack or setting
|
||||
OS_CLIENT_CONFIG_FILE environment variable.
|
||||
|
||||
#. Depending on how you installed Kolla Ansible, there is a script that will
|
||||
create example networks, images, and so on.
|
||||
|
||||
.. warning::
|
||||
|
||||
You are free to use the following ``init-runonce`` script for demo
|
||||
purposes but note it does **not** have to be run in order to use your
|
||||
cloud. Depending on your customisations, it may not work, or it may
|
||||
conflict with the resources you want to create. You have been warned.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
kolla-ansible/tools/init-runonce
|
||||
Loading…
Reference in New Issue
Block a user