openstack/openstack-ansible
Code Issues Proposed changes

[Docs] Simplify advanced config

Browse Source 
This merges advanced configuration and inventory, from the
operations guide into the reference guide. This avoids
duplications of the documentation accross the guides.

Change-Id: I6fd758b89a84698b0ac8e227d97cb24914bc2066
This commit is contained in:
Jean-Philippe Evrard 2018-02-19 10:51:21 +00:00
parent 4db3962281
commit 6435ec7521
10 changed files with 204 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/admin/index.rst
View File

@ -25,4 +25,3 @@ the major upgrades procedures.
troubleshooting.rst
upgrades/minor-updates.rst
upgrades/major-upgrades.rst
advanced-config.rst

35
doc/source/admin/maintenance-tasks/ansible-modules.rst
View File

@ -133,3 +133,38 @@ specific tasks within a playbook. For more information on tags, see
`Tags <http://ansible-docs.readthedocs.io/zh/stable-2.0/rst/playbooks_tags.html>`_
and `Understanding ansible tags
<http://www.caphrim.net/ansible/2015/05/24/understanding-ansible-tags.html>`_.
Ansible forks
~~~~~~~~~~~~~
The default ``MaxSessions`` setting for the OpenSSH Daemon is 10. Each Ansible
fork makes use of a session. By default, Ansible sets the number of forks to
5. However, you can increase the number of forks used in order to improve
deployment performance in large environments.
Note that more than 10 forks will cause issues for any playbooks
which use ``delegate_to`` or ``local_action`` in the tasks. It is
recommended that the number of forks are not raised when executing against the
control plane, as this is where delegation is most often used.
The number of forks used may be changed on a permanent basis by including
the appropriate change to the ``ANSIBLE_FORKS`` in your ``.bashrc`` file.
Alternatively it can be changed for a particular playbook execution by using
the ``--forks`` CLI parameter. For example, the following executes the nova
playbook against the control plane with 10 forks, then against the compute
nodes with 50 forks.
.. code-block:: shell-session
# openstack-ansible --forks 10 os-nova-install.yml --limit compute_containers
# openstack-ansible --forks 50 os-nova-install.yml --limit compute_hosts
For more information about forks, please see the following references:
* OpenStack-Ansible `Bug 1479812`_
* Ansible `forks`_ entry for ansible.cfg
* `Ansible Performance Tuning`_
.. _Bug 1479812: https://bugs.launchpad.net/openstack-ansible/+bug/1479812
.. _forks: http://docs.ansible.com/ansible/intro_configuration.html#forks
.. _Ansible Performance Tuning: https://www.ansible.com/blog/ansible-performance-tuning

17
doc/source/reference/configuration/advanced-config.rst Normal file
View File

@ -0,0 +1,17 @@
======================
Advanced configuration
======================
The OpenStack-Ansible project provides a basic OpenStack environment, but
many deployers will wish to extend the environment based on their needs. This
could include installing extra services, changing package versions, or
overriding existing variables.
Using these extension points, deployers can provide a more 'opinionated'
installation of OpenStack that may include their own software.
.. toctree::
:maxdepth: 1
using-overrides
extending-osa

60
doc/source/reference/configuration/extending-osa.rst Normal file
View File

@ -0,0 +1,60 @@
Extending OpenStack-Ansible
===========================
Including OpenStack-Ansible in your project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Including the openstack-ansible repository within another project can be
done in several ways:
- A git submodule pointed to a released tag.
- A script to automatically perform a git checkout of OpenStack-Ansible.
When including OpenStack-Ansible in a project, consider using a parallel
directory structure as shown in the ``ansible.cfg`` files section.
Also note that copying files into directories such as ``env.d`` or
``conf.d`` should be handled via some sort of script within the extension
project.
Including OpenStack-Ansible with your Ansible structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can create your own playbook, variable, and role structure while still
including the OpenStack-Ansible roles and libraries by setting environment
variables or by adjusting ``/usr/local/bin/openstack-ansible.rc``.
The relevant environment variables for Ansible 1.9 (included in
OpenStack-Ansible) are as follows:
``ANSIBLE_LIBRARY``
This variable should point to
``openstack-ansible/playbooks/library``. Doing so allows roles and
playbooks to access OpenStack-Ansible's included Ansible modules.
``ANSIBLE_ROLES_PATH``
This variable should point to
``openstack-ansible/playbooks/roles``. This allows Ansible to
properly look up any OpenStack-Ansible roles that extension roles
may reference.
``ANSIBLE_INVENTORY``
This variable should point to
``openstack-ansible/inventory/dynamic_inventory.py``. With this setting,
extensions have access to the same dynamic inventory that
OpenStack-Ansible uses.
The paths to the ``openstack-ansible`` top level directory can be
relative in this file.
Consider this directory structure::
my_project
|
|- custom_stuff
| |
| |- playbooks
|- openstack-ansible
| |
| |- playbooks
The environment variables set would use
``../openstack-ansible/playbooks/<directory>``.

189
doc/source/admin/advanced-config.rst → doc/source/reference/configuration/using-overrides.rst
View File

@ -1,133 +1,5 @@
======================
Advanced configuration
======================
The OpenStack-Ansible project provides a basic OpenStack environment, but
many deployers will wish to extend the environment based on their needs. This
could include installing extra services, changing package versions, or
overriding existing variables.
Using these extension points, deployers can provide a more 'opinionated'
installation of OpenStack that may include their own software.
Including OpenStack-Ansible in your project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Including the openstack-ansible repository within another project can be
done in several ways:
- A git submodule pointed to a released tag.
- A script to automatically perform a git checkout of OpenStack-Ansible.
When including OpenStack-Ansible in a project, consider using a parallel
directory structure as shown in the ``ansible.cfg`` files section.
Also note that copying files into directories such as ``env.d`` or
``conf.d`` should be handled via some sort of script within the extension
project.
Ansible forks
~~~~~~~~~~~~~
The default MaxSessions setting for the OpenSSH Daemon is 10. Each Ansible
fork makes use of a Session. By default, Ansible sets the number of forks to
5. However, you can increase the number of forks used in order to improve
deployment performance in large environments.
Note that more than 10 forks will cause issues for any playbooks
which use ``delegate_to`` or ``local_action`` in the tasks. It is
recommended that the number of forks are not raised when executing against the
Control Plane, as this is where delegation is most often used.
The number of forks used may be changed on a permanent basis by including
the appropriate change to the ``ANSIBLE_FORKS`` in your ``.bashrc`` file.
Alternatively it can be changed for a particular playbook execution by using
the ``--forks`` CLI parameter. For example, the following executes the nova
playbook against the control plane with 10 forks, then against the compute
nodes with 50 forks.
.. code-block:: shell-session
# openstack-ansible --forks 10 os-nova-install.yml --limit compute_containers
# openstack-ansible --forks 50 os-nova-install.yml --limit compute_hosts
For more information about forks, please see the following references:
* OpenStack-Ansible `Bug 1479812`_
* Ansible `forks`_ entry for ansible.cfg
* `Ansible Performance Tuning`_
.. _Bug 1479812: https://bugs.launchpad.net/openstack-ansible/+bug/1479812
.. _forks: http://docs.ansible.com/ansible/intro_configuration.html#forks
.. _Ansible Performance Tuning: https://www.ansible.com/blog/ansible-performance-tuning
Including OpenStack-Ansible with your Ansible structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can create your own playbook, variable, and role structure while still
including the OpenStack-Ansible roles and libraries by setting environment
variables or by adjusting ``/usr/local/bin/openstack-ansible.rc``.
The relevant environment variables for Ansible 1.9 (included in
OpenStack-Ansible) are as follows:
``ANSIBLE_LIBRARY``
This variable should point to
``openstack-ansible/playbooks/library``. Doing so allows roles and
playbooks to access OpenStack-Ansible's included Ansible modules.
``ANSIBLE_ROLES_PATH``
This variable should point to
``openstack-ansible/playbooks/roles``. This allows Ansible to
properly look up any OpenStack-Ansible roles that extension roles
may reference.
``ANSIBLE_INVENTORY``
This variable should point to
``openstack-ansible/inventory/dynamic_inventory.py``. With this setting,
extensions have access to the same dynamic inventory that
OpenStack-Ansible uses.
The paths to the ``openstack-ansible`` top level directory can be
relative in this file.
Consider this directory structure::
my_project
|
|- custom_stuff
| |
| |- playbooks
|- openstack-ansible
| |
| |- playbooks
The environment variables set would use
``../openstack-ansible/playbooks/<directory>``.
env.d
~~~~~
The ``/etc/openstack_deploy/env.d`` directory sources all YAML files into the
deployed environment, allowing a deployer to define additional group mappings.
This directory is used to extend the environment skeleton, or modify the
defaults defined in the ``inventory/env.d`` directory.
See also
:deploy_guide:`Understanding Container Groups <app-custom-layouts.html>`
in Appendix C of the Deployment Guide.
conf.d
~~~~~~
Common OpenStack services and their configuration are defined by
OpenStack-Ansible in the
``/etc/openstack_deploy/openstack_user_config.yml`` settings file.
Additional services should be defined with a YAML file in
``/etc/openstack_deploy/conf.d``, in order to manage file size.
See also :deploy_guide:`Understanding Host Groups <app-custom-layouts.html>`
in Appendix C of the Deployment Guide.
Using overrides
===============
user_*.yml files
~~~~~~~~~~~~~~~~
@ -146,7 +18,7 @@ variables in files named following the ``user_*.yml`` pattern so they will be
sourced alongside those used exclusively by OpenStack-Ansible.
Ordering and precedence
-----------------------
~~~~~~~~~~~~~~~~~~~~~~~
``user_*.yml`` files contain YAML variables which are applied as extra-vars
when executing ``openstack-ansible`` to run playbooks. They will be sourced
@ -154,37 +26,8 @@ in alphanumeric order by ``openstack-ansible``. If duplicate variables occur
in the ``user_*.yml`` files, the variable in the last file read will take
precedence.
.. _adding-galaxy-roles:
Adding Galaxy roles
~~~~~~~~~~~~~~~~~~~
Any roles defined in ``openstack-ansible/ansible-role-requirements.yml``
will be installed by the
``openstack-ansible/scripts/bootstrap-ansible.sh`` script.
Setting overrides in configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All of the services that use YAML, JSON, or INI for configuration can receive
overrides through the use of a Ansible action plugin named ``config_template``.
The configuration template engine allows a deployer to use a simple dictionary
to modify or add items into configuration files at run time that may not have a
preset template option. All OpenStack-Ansible roles allow for this
functionality where applicable. Files available to receive overrides can be
seen in the ``defaults/main.yml`` file as standard empty dictionaries (hashes).
Practical guidance for using this feature is available in the
:deploy_guide:`Deployment Guide <app-advanced-config-override.html>`.
This module has been `submitted for consideration`_ into Ansible Core.
.. _submitted for consideration: https://github.com/ansible/ansible/pull/12555
Build the environment with additional python packages
-----------------------------------------------------
Adding extra python packages into the environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The system will allow you to install and build any package that is a python
installable. The repository infrastructure will look for and create any
@ -221,9 +64,27 @@ Once the variables are set call the play ``repo-build.yml`` to build all of the
wheels within the repository infrastructure. When ready run the target plays to
deploy your overridden source code.
Setting overrides in configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Module documentation
--------------------
All of the services that use YAML, JSON, or INI for configuration can receive
overrides through the use of a Ansible action plugin named ``config_template``.
The configuration template engine allows a deployer to use a simple dictionary
to modify or add items into configuration files at run time that may not have a
preset template option. All OpenStack-Ansible roles allow for this
functionality where applicable. Files available to receive overrides can be
seen in the ``defaults/main.yml`` file as standard empty dictionaries (hashes).
Practical guidance for using this feature is available in the
:deploy_guide:`Deployment Guide <app-advanced-config-override.html>`.
This module has been `rejected for inclusion`_ into Ansible Core.
.. _rejected for inclusion: https://github.com/ansible/ansible/pull/12555
config_template documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These are the options available as found within the virtual module
documentation section.

8
doc/source/reference/conventions.rst
View File

@ -40,6 +40,14 @@ There is no ``ansible.cfg`` provided with OpenStack-Ansible.
Environment variables are used to alter the default
Ansible behavior if necessary.
Ansible roles fetching
~~~~~~~~~~~~~~~~~~~~~~
Any roles defined in ``openstack-ansible/ansible-role-requirements.yml``
will be installed by the
``openstack-ansible/scripts/bootstrap-ansible.sh`` script, and fetched
into the ansible roles folder.
Inventory conventions
~~~~~~~~~~~~~~~~~~~~~

1
doc/source/reference/index.rst
View File

@ -10,5 +10,6 @@ to deploy, configure, or upgrade an OpenStack-Ansible cloud.
conventions.rst
inventory/inventory.rst
configuration/advanced-config.rst
commands/reference.rst
upgrades/reference.rst

18
doc/source/reference/inventory/advanced-topics.rst Normal file
View File

@ -0,0 +1,18 @@
Advanced inventory topics
=========================
Changing the base environment directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``--environment/-e`` argument will take the path to a directory containing
an ``env.d`` directory. This defaults to ``inventory/`` in the
OpenStack-Ansible codebase.
Contents of this directory are populated into the environment *before* the
``env.d`` found in the directory specified by ``--config``.
Dynamic Inventory API documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. automodule:: dynamic_inventory
:members:

76
doc/source/reference/inventory/configure-inventory.rst
View File

@ -1,17 +1,49 @@
Configuring the inventory
=========================
Changing the base environment directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
conf.d
~~~~~~
The ``--environment/-e`` argument will take the path to a directory containing
an ``env.d`` directory. This defaults to ``inventory/`` in the
OpenStack-Ansible codebase.
Common OpenStack services and their configuration are defined by
OpenStack-Ansible in the
``/etc/openstack_deploy/openstack_user_config.yml`` settings file.
Contents of this directory are populated into the environment *before* the
``env.d`` found in the directory specified by ``--config``.
Additional services should be defined with a YAML file in
``/etc/openstack_deploy/conf.d``, in order to manage file size.
env.d
~~~~~
The ``/etc/openstack_deploy/env.d`` directory sources all YAML files into the
deployed environment, allowing a deployer to define additional group mappings.
This directory is used to extend the environment skeleton, or modify the
defaults defined in the ``inventory/env.d`` directory.
Configuration constraints
~~~~~~~~~~~~~~~~~~~~~~~~~
Group memberships
-----------------
When adding groups, keep the following in mind:
* A group can contain hosts
* A group can contain child groups
However, groups cannot contain child groups and hosts.
The lxc_hosts Group
-------------------
When the dynamic inventory script creates a container name, the host on
which the container resides is added to the ``lxc_hosts`` inventory group.
Using this name for a group in the configuration will result in a runtime
error.
Checking inventory configuration for errors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -35,33 +67,3 @@ debugging the inventory script's behavior. The output is written to
The ``inventory.log`` file is appended to, not overwritten.
Like ``--check``, this flag is not invoked when running from ansible.
Configuration constraints
~~~~~~~~~~~~~~~~~~~~~~~~~
Group memberships
-----------------
When adding groups, keep the following in mind:
* A group can contain hosts
* A group can contain child groups
However, groups cannot contain child groups and hosts.
The lxc_hosts Group
-------------------
When the dynamic inventory script creates a container name, the host on
which the container resides is added to the ``lxc_hosts`` inventory group.
Using this name for a group in the configuration will result in a runtime
error.
Dynamic Inventory API documentation
-----------------------------------
.. automodule:: dynamic_inventory
:members:

1
doc/source/reference/inventory/inventory.rst
View File

@ -15,3 +15,4 @@ for OpenStack-Ansible.
generate-inventory
configure-inventory
manage-inventory
advanced-topics