From f81484cca55015747bb136595ecbd9c2526de663 Mon Sep 17 00:00:00 2001
From: Ramona Beermann <ramona.beermann@osism.tech>
Date: Tue, 8 Nov 2022 10:48:54 +0100
Subject: [PATCH] Add Quickstart Developer Guide
Follow up patch from https://review.opendev.org/c/openstack/kolla-ansible/+/861953
Signed-off-by: Ramona Beermann <ramona.beermann@osism.tech>
Change-Id: Ia21bb4ccadf0104c8e049bb7b8091d4742f6c1c1
---
doc/source/user/index.rst | 1 +
doc/source/user/quickstart-development.rst | 340 +++++++++++++++++++++
2 files changed, 341 insertions(+)
create mode 100644 doc/source/user/quickstart-development.rst
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index fcd9f96b72..4c4e698a66 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -6,6 +6,7 @@ User Guides
:maxdepth: 2
quickstart
+ quickstart-development
support-matrix
virtual-environments
multinode
diff --git a/doc/source/user/quickstart-development.rst b/doc/source/user/quickstart-development.rst
new file mode 100644
index 0000000000..729a864315
--- /dev/null
+++ b/doc/source/user/quickstart-development.rst
@@ -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
--
GitLab