<commit_before>.. _quickstart-aio:

===============
Quickstart: AIO
===============

All-in-one (AIO) builds are a great way to perform an OpenStack-Ansible build
for:

* a development environment
* an overview of how all of the OpenStack services fit together
* a simple lab deployment

Although AIO builds aren't recommended for large production deployments,
they're great for smaller proof-of-concept deployments.

Absolute minimum server resources (currently used for gate checks):

* 8 vCPU's
* 50GB free disk space on the root partition
* 8GB RAM

Recommended server resources:

* CPU/motherboard that supports `hardware-assisted virtualization`_
* 8 CPU Cores
* 80GB free disk space on the root partition, or 60GB+ on a blank
  secondary disk. Using a secondary disk requires the use of the
  ``bootstrap_host_data_disk_device`` parameter. Please see
  `Building an AIO`_ for more details.
* 16GB RAM

It is `possible` to perform AIO builds within a virtual machine for
demonstration and evaluation, but your virtual machines will perform poorly
unless nested virtualization is available. For production workloads, multiple
nodes for specific roles are recommended.

.. _hardware-assisted virtualization: https://en.wikipedia.org/wiki/Hardware-assisted_virtualization


Building an AIO
---------------

Overview
~~~~~~~~

There are three steps to running an AIO build, with an optional first step
should you need to customize your build:

* Prepare the host
* Bootstrap Ansible and the required roles
* Bootstrap the AIO configuration
* Run playbooks

Prepare the host
~~~~~~~~~~~~~~~~

When building an AIO on a new server, it is recommended that all
system packages are upgraded and then reboot into the new kernel:

.. note:: Execute the following commands and scripts as the root user.

.. code-block:: shell-session

   ## Ubuntu
   # apt-get update
   # apt-get dist-upgrade
   # reboot

.. code-block:: shell-session

   ## CentOS
   # yum upgrade
   # yum install git
   # reboot

.. note::

   Before rebooting, in ``/etc/sysconfig/selinux``, make sure that
   ``SELINUX=enforcing``is changed to ``SELINUX=disabled``.
   SELinux enabled is not currently supported in OpenStack-Ansible
   for CentOS/RHEL due to a lack of maintainers for the feature.

.. code-block:: shell-session

   ## openSUSE
   # zypper up
   # zypper in git-core
   # reboot

.. note::

   If you are installing with limited connectivity, please review
   the *Installing with limited connectivity* appendix in the
   :deploy_guide:`Deployment Guide <index.html>` before proceeding.

Bootstrap Ansible and the required roles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Start by cloning the OpenStack-Ansible repository and changing into the
repository root directory:

.. code-block:: shell-session

   # git clone https://opendev.org/openstack/openstack-ansible \
       /opt/openstack-ansible
   # cd /opt/openstack-ansible

Next switch the applicable branch/tag to be deployed from. Note that
deploying from the head of a branch may result in an unstable build due to
changes in flight and upstream OpenStack changes. For a test (for example,
not a development) build it is usually best to checkout the latest tagged
version.

.. parsed-literal::

   # # List all existing tags.
   # git tag -l

   # # Checkout the stable branch and find just the latest tag
   # git checkout |current_release_git_branch_name|
   # git describe --abbrev=0 --tags

   # # Checkout the latest tag from either method of retrieving the tag.
   # git checkout |latest_tag|

.. note::
   The |current_release_formal_name| release is only compatible with
   Debian 9 (stretch), Ubuntu 18.04 (Bionic Beaver), CentOS 7
   and openSUSE Leap 15.X.

The next step is to bootstrap Ansible and the Ansible roles for the
development environment.

Run the following to bootstrap Ansible and the required roles:

.. code-block:: shell-session

   # scripts/bootstrap-ansible.sh

.. note::
  You might encounter an error while running the Ansible bootstrap script
  when building some of the Python extensions (like pycrypto) which says:

  .. code-block:: shell-session

     configure: error: cannot run C compiled programs.

  The reason of this failure might be resulting from a noexec mount flag
  used for the filesystem associated with /tmp which you can check by
  running the following command:

  .. code-block:: shell-session

     # mount | grep $(df /tmp | tail -n +2 | awk '{print $1}') | grep noexec

  If this is the case you can specify an alternate path which does not
  have this mount option set:

  .. code-block:: shell-session

     # TMPDIR=/var/tmp scripts/bootstrap-ansible.sh

Bootstrap the AIO configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In order for all the services to run, the host must be prepared with the
appropriate disks partitioning, packages, network configuration and
configurations for the OpenStack Deployment.

By default the AIO bootstrap scripts deploy a base set of OpenStack services
with sensible defaults for the purpose of a gate check, development or testing
system.

Review the `bootstrap-host role defaults`_ file to see various configuration
options. Deployers have the option to change how the host is bootstrapped.
This is useful when you wish the AIO to make use of a secondary data disk,
or when using this role to bootstrap a multi-node development environment.

.. _bootstrap-host role defaults: https://opendev.org/openstack/openstack-ansible/src/tests/roles/bootstrap-host/defaults/main.yml

The bootstrap script is pre-set to pass the environment variable
``BOOTSTRAP_OPTS`` as an additional option to the bootstrap process. For
example, if you wish to set the bootstrap to re-partition a specific
secondary storage device (``/dev/sdb``), which will erase all of the data
on the device, then execute:

.. code-block:: shell-session

   # export BOOTSTRAP_OPTS="bootstrap_host_data_disk_device=sdb"

Additional options may be implemented by simply concatenating them with
a space between each set of options, for example:

.. code-block:: shell-session

   # export BOOTSTRAP_OPTS="bootstrap_host_data_disk_device=sdb"
   # export BOOTSTRAP_OPTS="${BOOTSTRAP_OPTS} bootstrap_host_data_disk_fs_type=xfs"

For the default AIO scenario, the AIO configuration preparation is completed by
executing:

.. code-block:: shell-session

   # scripts/bootstrap-aio.sh

To add OpenStack Services over and above the bootstrap-aio default services
for the applicable scenario, copy the ``conf.d`` files with the ``.aio`` file
extension into ``/etc/openstack_deploy`` and rename then to ``.yml`` files.
For example, in order to enable the OpenStack Telemetry services, execute the
following:

.. code-block:: shell-session

   # cd /opt/openstack-ansible/
   # cp etc/openstack_deploy/conf.d/{aodh,gnocchi,ceilometer}.yml.aio /etc/openstack_deploy/conf.d/
   # for f in $(ls -1 /etc/openstack_deploy/conf.d/*.aio); do mv -v ${f} ${f%.*}; done

It is possible to also do this (and change other defaults) during the bootstrap
script initial execution by changing the SCENARIO environment variable before
running the script. The key word 'aio' will ensure that a basic set of
OpenStack services (cinder, glance, horizon, neutron, nova) will be deployed.
The key words 'lxc' and 'nspawn' can be used to set the container back-end,
while the key word 'metal' will deploy all services without containers. In
order to implement any other services, add the name of the conf.d file name
without the `.yml.aio` extension into the SCENARIO environment variable. Each
key word should be delimited by an underscore. For example, the following will
implement an AIO with barbican, cinder, glance, horizon, neutron, and nova. It
will set the cinder storage back-end to ceph and will make use of LXC as the
container back-end.

.. code-block:: shell-session

   # export SCENARIO='aio_lxc_barbican'
   # scripts/bootstrap-aio.sh

.. note::
   If the 'metal' and 'aio' key words are used together, horizon will not be
   deployed because haproxy and horizon will conflict on the same listening
   ports.

To add any global overrides, over and above the defaults for the applicable
scenario, edit ``/etc/openstack_deploy/user_variables.yml``. In order to
understand the various ways that you can override the default behaviour
set out in the roles, playbook and group variables, see :ref:`user-overrides`.

See the :deploy_guide:`Deployment Guide <index.html>` for a more detailed break
down of how to implement your own configuration rather than to use the AIO
bootstrap.

Run playbooks<commit_msg>Fixes: AIO Quickstart docs ceph reference<commit_after>.. _quickstart-aio:

===============
Quickstart: AIO
===============

All-in-one (AIO) builds are a great way to perform an OpenStack-Ansible build
for:

* a development environment
* an overview of how all of the OpenStack services fit together
* a simple lab deployment

Although AIO builds aren't recommended for large production deployments,
they're great for smaller proof-of-concept deployments.

Absolute minimum server resources (currently used for gate checks):

* 8 vCPU's
* 50GB free disk space on the root partition
* 8GB RAM

Recommended server resources:

* CPU/motherboard that supports `hardware-assisted virtualization`_
* 8 CPU Cores
* 80GB free disk space on the root partition, or 60GB+ on a blank
  secondary disk. Using a secondary disk requires the use of the
  ``bootstrap_host_data_disk_device`` parameter. Please see
  `Building an AIO`_ for more details.
* 16GB RAM

It is `possible` to perform AIO builds within a virtual machine for
demonstration and evaluation, but your virtual machines will perform poorly
unless nested virtualization is available. For production workloads, multiple
nodes for specific roles are recommended.

.. _hardware-assisted virtualization: https://en.wikipedia.org/wiki/Hardware-assisted_virtualization


Building an AIO
---------------

Overview
~~~~~~~~

There are three steps to running an AIO build, with an optional first step
should you need to customize your build:

* Prepare the host
* Bootstrap Ansible and the required roles
* Bootstrap the AIO configuration
* Run playbooks

Prepare the host
~~~~~~~~~~~~~~~~

When building an AIO on a new server, it is recommended that all
system packages are upgraded and then reboot into the new kernel:

.. note:: Execute the following commands and scripts as the root user.

.. code-block:: shell-session

   ## Ubuntu
   # apt-get update
   # apt-get dist-upgrade
   # reboot

.. code-block:: shell-session

   ## CentOS
   # yum upgrade
   # yum install git
   # reboot

.. note::

   Before rebooting, in ``/etc/sysconfig/selinux``, make sure that
   ``SELINUX=enforcing``is changed to ``SELINUX=disabled``.
   SELinux enabled is not currently supported in OpenStack-Ansible
   for CentOS/RHEL due to a lack of maintainers for the feature.

.. code-block:: shell-session

   ## openSUSE
   # zypper up
   # zypper in git-core
   # reboot

.. note::

   If you are installing with limited connectivity, please review
   the *Installing with limited connectivity* appendix in the
   :deploy_guide:`Deployment Guide <index.html>` before proceeding.

Bootstrap Ansible and the required roles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Start by cloning the OpenStack-Ansible repository and changing into the
repository root directory:

.. code-block:: shell-session

   # git clone https://opendev.org/openstack/openstack-ansible \
       /opt/openstack-ansible
   # cd /opt/openstack-ansible

Next switch the applicable branch/tag to be deployed from. Note that
deploying from the head of a branch may result in an unstable build due to
changes in flight and upstream OpenStack changes. For a test (for example,
not a development) build it is usually best to checkout the latest tagged
version.

.. parsed-literal::

   # # List all existing tags.
   # git tag -l

   # # Checkout the stable branch and find just the latest tag
   # git checkout |current_release_git_branch_name|
   # git describe --abbrev=0 --tags

   # # Checkout the latest tag from either method of retrieving the tag.
   # git checkout |latest_tag|

.. note::
   The |current_release_formal_name| release is only compatible with
   Debian 9 (stretch), Ubuntu 18.04 (Bionic Beaver), CentOS 7
   and openSUSE Leap 15.X.

The next step is to bootstrap Ansible and the Ansible roles for the
development environment.

Run the following to bootstrap Ansible and the required roles:

.. code-block:: shell-session

   # scripts/bootstrap-ansible.sh

.. note::
  You might encounter an error while running the Ansible bootstrap script
  when building some of the Python extensions (like pycrypto) which says:

  .. code-block:: shell-session

     configure: error: cannot run C compiled programs.

  The reason of this failure might be resulting from a noexec mount flag
  used for the filesystem associated with /tmp which you can check by
  running the following command:

  .. code-block:: shell-session

     # mount | grep $(df /tmp | tail -n +2 | awk '{print $1}') | grep noexec

  If this is the case you can specify an alternate path which does not
  have this mount option set:

  .. code-block:: shell-session

     # TMPDIR=/var/tmp scripts/bootstrap-ansible.sh

Bootstrap the AIO configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In order for all the services to run, the host must be prepared with the
appropriate disks partitioning, packages, network configuration and
configurations for the OpenStack Deployment.

By default the AIO bootstrap scripts deploy a base set of OpenStack services
with sensible defaults for the purpose of a gate check, development or testing
system.

Review the `bootstrap-host role defaults`_ file to see various configuration
options. Deployers have the option to change how the host is bootstrapped.
This is useful when you wish the AIO to make use of a secondary data disk,
or when using this role to bootstrap a multi-node development environment.

.. _bootstrap-host role defaults: https://opendev.org/openstack/openstack-ansible/src/tests/roles/bootstrap-host/defaults/main.yml

The bootstrap script is pre-set to pass the environment variable
``BOOTSTRAP_OPTS`` as an additional option to the bootstrap process. For
example, if you wish to set the bootstrap to re-partition a specific
secondary storage device (``/dev/sdb``), which will erase all of the data
on the device, then execute:

.. code-block:: shell-session

   # export BOOTSTRAP_OPTS="bootstrap_host_data_disk_device=sdb"

Additional options may be implemented by simply concatenating them with
a space between each set of options, for example:

.. code-block:: shell-session

   # export BOOTSTRAP_OPTS="bootstrap_host_data_disk_device=sdb"
   # export BOOTSTRAP_OPTS="${BOOTSTRAP_OPTS} bootstrap_host_data_disk_fs_type=xfs"

For the default AIO scenario, the AIO configuration preparation is completed by
executing:

.. code-block:: shell-session

   # scripts/bootstrap-aio.sh

To add OpenStack Services over and above the bootstrap-aio default services
for the applicable scenario, copy the ``conf.d`` files with the ``.aio`` file
extension into ``/etc/openstack_deploy`` and rename then to ``.yml`` files.
For example, in order to enable the OpenStack Telemetry services, execute the
following:

.. code-block:: shell-session

   # cd /opt/openstack-ansible/
   # cp etc/openstack_deploy/conf.d/{aodh,gnocchi,ceilometer}.yml.aio /etc/openstack_deploy/conf.d/
   # for f in $(ls -1 /etc/openstack_deploy/conf.d/*.aio); do mv -v ${f} ${f%.*}; done

It is possible to also do this (and change other defaults) during the bootstrap
script initial execution by changing the SCENARIO environment variable before
running the script. The key word 'aio' will ensure that a basic set of
OpenStack services (cinder, glance, horizon, neutron, nova) will be deployed.
The key words 'lxc' and 'nspawn' can be used to set the container back-end,
while the key word 'metal' will deploy all services without containers. In
order to implement any other services, add the name of the conf.d file name
without the `.yml.aio` extension into the SCENARIO environment variable. Each
key word should be delimited by an underscore. For example, the following will
implement an AIO with barbican, cinder, glance, horizon, neutron, and nova. It
will set the cinder storage back-end to ceph and will make use of LXC as the
container back-end.

.. code-block:: shell-session

   # export SCENARIO='aio_lxc_barbican_ceph'
   # scripts/bootstrap-aio.sh

.. note::
   If the 'metal' and 'aio' key words are used together, horizon will not be
   deployed because haproxy and horizon will conflict on the same listening
   ports.

To add any global overrides, over and above the defaults for the applicable
scenario, edit ``/etc/openstack_deploy/user_variables.yml``. In order to
understand the various ways that you can override the default behaviour
set out in the roles, playbook and group variables, see :ref:`user-overrides`.

See the :deploy_guide:`Deployment Guide <index.html>` for a more detailed break
down of how to implement your own configuration rather than to use the AIO
bootstrap.

Run playbooks
{'fraction_non_alphanumeric': 0.08177855274629468, 'fraction_numerical': 0.0026736413833188025, 'mean_word_length': 4.108669833729216, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1766012', 'n_tokens_mistral': 4919, 'n_tokens_neox': 4603, 'n_words': 2188}