openstack/openstack-ansible
Code Issues Proposed changes

[docs] Clean up the AIO user story

Browse Source 
Somehow the content has gotten all mixed up, resulting in a very
confusing story. This re-arranges the story to ensure that it follows
a basic sequence that matches the deploy guide and explains the right
things in the right context.

Change-Id: Ia395df90ed1c90aea7c3497d39f5acff9f954bcc
This commit is contained in:
Jesse Pretorius 2018-11-22 11:19:35 +00:00
parent 74bebf5d57
commit 56b3bd1e24
1 changed files with 67 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
doc/source/user/aio/quickstart.rst
View File

@ -30,9 +30,10 @@ Recommended server resources:
`Building an AIO`_ for more details. `Building an AIO`_ for more details.
* 16GB RAM * 16GB RAM
It's `possible` to perform AIO builds within a virtual machine for It is `possible` to perform AIO builds within a virtual machine for
demonstration and evaluation, but your virtual machines will perform poorly. demonstration and evaluation, but your virtual machines will perform poorly
For production workloads, multiple nodes for specific roles are recommended. 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 .. _hardware-assisted virtualization: https://en.wikipedia.org/wiki/Hardware-assisted_virtualization
@ -40,14 +41,20 @@ For production workloads, multiple nodes for specific roles are recommended.
Building an AIO Building an AIO
--------------- ---------------
Overview
~~~~~~~~
There are three steps to running an AIO build, with an optional first step There are three steps to running an AIO build, with an optional first step
should you need to customize your build: should you need to customize your build:
* Configuration *(this step is optional)* * Prepare the host
* Install and bootstrap Ansible * Bootstrap Ansible and the required roles
* Initial host bootstrap * Bootstrap the AIO configuration
* Run playbooks * Run playbooks
Prepare the host
~~~~~~~~~~~~~~~~
When building an AIO on a new server, it is recommended that all When building an AIO on a new server, it is recommended that all
system packages are upgraded and then reboot into the new kernel: system packages are upgraded and then reboot into the new kernel:
@ -79,6 +86,9 @@ system packages are upgraded and then reboot into the new kernel:
the *Installing with limited connectivity* appendix in the the *Installing with limited connectivity* appendix in the
:deploy_guide:`Deployment Guide <index.html>` before proceeding. :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 Start by cloning the OpenStack-Ansible repository and changing into the
repository root directory: repository root directory:
@ -108,73 +118,27 @@ version.
.. note:: .. note::
The |current_release_formal_name| release is only compatible with Ubuntu The |current_release_formal_name| release is only compatible with Ubuntu
16.04 (Xenial Xerus), Ubuntu 18.04 (Bionic Beaver) Centos 7 and 16.04 (Xenial Xerus), Ubuntu 18.04 (Bionic Beaver) CentOS 7 and
openSUSE Leap 42.X. openSUSE Leap 42.X.
By default the scripts deploy all OpenStack services with sensible defaults The next step is to bootstrap Ansible and the Ansible roles for the
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. development environment.
.. _bootstrap-host role defaults: https://git.openstack.org/cgit/openstack/openstack-ansible/tree/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"
By default the filesystem type will be set to ext4, if you want another type
of filesystem to be used, just use something similar to the following:
.. code-block:: shell-session
# export BOOTSTRAP_OPTS="bootstrap_host_data_disk_device=sdb bootstrap_host_data_disk_fs_type=xfs"
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_ubuntu_repo=http://mymirror.example.com/ubuntu"
You may wish to change the role fetch mode. Options are ``galaxy`` and You may wish to change the role fetch mode. Options are ``galaxy`` and
``git-clone``. The default for this option is ``galaxy``. ``git-clone``. The default for this option is ``git-clone``. The mode may
be changed by setting the ``ANSIBLE_ROLE_FETCH_MODE`` environment variable.
options: options:
:galaxy: Resolve all role dependencies using the ``ansible-galaxy`` resolver :galaxy: Resolve all role dependencies using the ``ansible-galaxy`` resolver
:git-clone: Clone all of the role dependencies using native git :git-clone: Clone all of the role dependencies using native git
Notes: Run the following to bootstrap Ansible and the required roles:
When doing role development it may be useful to set
``ANSIBLE_ROLE_FETCH_MODE`` to ``git-clone``. This will provide you the
ability to develop roles within the environment by modifying, patching, or
committing changes using an intact git tree while the ``galaxy`` option
scrubs the ``.git`` directory when it resolves a dependency.
.. code-block:: bash
$ export ANSIBLE_ROLE_FETCH_MODE=git-clone
The next step is to bootstrap Ansible and the Ansible roles for the
development environment. Deployers can customize roles by adding variables to
override the defaults in each role (see :ref:`user-overrides`). Run the
following to bootstrap Ansible:
.. code-block:: shell-session .. code-block:: shell-session
# scripts/bootstrap-ansible.sh # scripts/bootstrap-ansible.sh
Notes: .. note::
You might encounter an error while running the Ansible bootstrap script You might encounter an error while running the Ansible bootstrap script
when building some of the Python extensions (like pycrypto) which says: when building some of the Python extensions (like pycrypto) which says:
@ -197,12 +161,44 @@ Notes:
# TMPDIR=/var/tmp scripts/bootstrap-ansible.sh # 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 In order for all the services to run, the host must be prepared with the
appropriate disks partitioning, packages, network configuration and appropriate disks partitioning, packages, network configuration and
configurations for the OpenStack Deployment. configurations for the OpenStack Deployment.
For the default AIO scenario, this preparation By default the AIO bootstrap scripts deploy a base set of OpenStack services
is completed by executing: 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://git.openstack.org/cgit/openstack/openstack-ansible/tree/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 .. code-block:: shell-session
@ -216,9 +212,7 @@ execute the following:
# export SCENARIO='ceph' # export SCENARIO='ceph'
# scripts/bootstrap-aio.sh # scripts/bootstrap-aio.sh
**Tested Scenarios** To add OpenStack Services over and above the bootstrap-aio default services
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 for the applicable scenario, copy the ``conf.d`` files with the ``.aio`` file
extension into ``/etc/openstack_deploy`` and rename then to ``.yml`` files. extension into ``/etc/openstack_deploy`` and rename then to ``.yml`` files.
For example, in order to enable the OpenStack Telemetry services, execute the For example, in order to enable the OpenStack Telemetry services, execute the
@ -231,8 +225,16 @@ following:
# for f in $(ls -1 /etc/openstack_deploy/conf.d/*.aio); do mv -v ${f} ${f%.*}; done # for f in $(ls -1 /etc/openstack_deploy/conf.d/*.aio); do mv -v ${f} ${f%.*}; done
To add any global overrides, over and above the defaults for the applicable To add any global overrides, over and above the defaults for the applicable
scenario, edit ``/etc/openstack_deploy/user_variables.yml``. See the scenario, edit ``/etc/openstack_deploy/user_variables.yml``. In order to
:deploy_guide:`Deployment Guide <index.html>` for more details. 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
~~~~~~~~~~~~~
Finally, run the playbooks by executing: Finally, run the playbooks by executing:
@ -260,8 +262,6 @@ Keystone service, execute:
# cd /opt/openstack-ansible/playbooks # cd /opt/openstack-ansible/playbooks
# openstack-ansible os-keystone-install.yml # openstack-ansible os-keystone-install.yml
.. _bootstrap-aio default services: https://git.openstack.org/cgit/openstack/openstack-ansible/tree/tests/bootstrap-aio.yml
Rebooting an AIO Rebooting an AIO
---------------- ----------------