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 ` guide. + +Recommended reading +~~~~~~~~~~~~~~~~~~~ + +It's beneficial to learn basics of both `Ansible `__ +and `Docker `__ 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 ` 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 `. + +#. 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 `__. 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 `__-provided, + pre-built images are going to be used. To learn more about building + mechanism, please refer :kolla-doc:`Building Container Images + `. + + 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 + `. + + 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 + `_. + For more information about service configuration, Please refer to the + :kolla-ansible-doc:`Services Reference Guide + `. + +* 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 `. + +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 `. + +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