openstack/openstack-ansible
Code Issues Proposed changes

[Docs] Centralize Inventory documentation

Browse Source 
There are details about inventory configuration in the deploy
guide that could go to the reference.

Change-Id: I712470742250f37a410eb88087b14403ac777493
This commit is contained in:
Jean-Philippe Evrard 2018-02-22 16:18:07 +00:00
parent 99ca16e85e
commit eb89fa513a
5 changed files with 159 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
deploy-guide/source/app.rst
View File

@ -5,7 +5,6 @@ Appendices
.. toctree::
:maxdepth: 2
app-custom-layouts.rst
app-limited-connectivity.rst
app-advanced-config-sslcertificates.rst
app-resources.rst

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

@ -1,9 +1,8 @@
.. _configuring-inventory:
Configuring the inventory
=========================
conf.d
~~~~~~
Common OpenStack services and their configuration are defined by
OpenStack-Ansible in the
``/etc/openstack_deploy/openstack_user_config.yml`` settings file.
@ -11,64 +10,15 @@ OpenStack-Ansible in the
Additional services should be defined with a YAML file in
``/etc/openstack_deploy/conf.d``, in order to manage file size.
Affinity
~~~~~~~~
When OpenStack-Ansible generates its dynamic inventory, the affinity
setting determines how many containers of a similar type are deployed on a
single physical host.
Using ``shared-infra_hosts`` as an example, consider this
``openstack_user_config.yml`` configuration:
.. code-block:: yaml
shared-infra_hosts:
infra1:
ip: 172.29.236.101
infra2:
ip: 172.29.236.102
infra3:
ip: 172.29.236.103
Three hosts are assigned to the `shared-infra_hosts` group,
OpenStack-Ansible ensures that each host runs a single database container,
a single Memcached container, and a single RabbitMQ container. Each host has
an affinity of 1 by default, which means that each host runs one of each
container type.
If you are deploying a stand-alone Object Storage (swift) environment,
you can skip the deployment of RabbitMQ. If you use this configuration,
your ``openstack_user_config.yml`` file would look as follows:
.. code-block:: yaml
shared-infra_hosts:
infra1:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.101
infra2:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.102
infra3:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.103
This configuration deploys a Memcached container and a database container
on each host, but no RabbitMQ containers.
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.
To understand how the dynamic inventory works, see
:ref:`inventory-in-depth`.
Configuration constraints
~~~~~~~~~~~~~~~~~~~~~~~~~
@ -91,6 +41,103 @@ 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.
Customizing existing components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Deploying directly on hosts
---------------------------
To deploy a component directly on the host instead of within a container, set
the ``is_metal`` property to ``true`` for the container group in the
``container_skel`` section in the appropriate file.
The use of ``container_vars`` and mapping from container groups to host groups
is the same for a service deployed directly onto the host.
.. note::
The ``cinder-volume`` component is deployed directly on the host by
default. See the ``env.d/cinder.yml`` file for this example.
Omit a service or component from the deployment
-----------------------------------------------
To omit a component from a deployment, you can use one of several options:
- Remove the ``physical_skel`` link between the container group and
the host group by deleting the related file located in the ``env.d/``
directory.
- Do not run the playbook that installs the component.
Unless you specify the component to run directly on a host by using the
``is_metal`` property, a container is created for this component.
- Adjust the :ref:`affinity`
to 0 for the host group. Similar to the second option listed here, Unless
you specify the component to run directly on a host by using the ``is_metal``
property, a container is created for this component.
Deploy existing components on dedicated hosts
---------------------------------------------
To deploy a ``shared-infra`` component to dedicated hosts, modify the
files that specify the host groups and container groups for the component.
For example, to run Galera directly on dedicated hosts, you would perform the
following steps:
#. Modify the ``container_skel`` section of the ``env.d/galera.yml`` file.
For example:
.. code-block:: yaml
container_skel:
galera_container:
belongs_to:
- db_containers
contains:
- galera
properties:
is_metal: true
.. note::
To deploy within containers on these dedicated hosts, omit the
``is_metal: true`` property.
#. Assign the ``db_containers`` container group (from the preceding step) to a
host group by providing a ``physical_skel`` section for the host group
in a new or existing file, such as ``env.d/galera.yml``.
For example:
.. code-block:: yaml
physical_skel:
db_containers:
belongs_to:
- all_containers
db_hosts:
belongs_to:
- hosts
#. Define the host group (``db_hosts``) in a ``conf.d/`` file (such as
``galera.yml``). For example:
.. code-block:: yaml
db_hosts:
db-host1:
ip: 172.39.123.11
db-host2:
ip: 172.39.123.12
db-host3:
ip: 172.39.123.13
.. note::
Each of the custom group names in this example (``db_containers``
and ``db_hosts``) are arbitrary. Choose your own group names,
but ensure the references are consistent among all relevant files.
Checking inventory configuration for errors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

4
doc/source/reference/inventory/generate-inventory.rst
View File

@ -78,8 +78,10 @@ physical host and not in a container. For an example of ``is_metal: true``
being used refer to ``inventory/env.d/cinder.yml`` in the
``container_skel`` section.
For more details, see :ref:`configuring-inventory`.
Outputs
^^^^^^^
~~~~~~~
Once executed, the script will output an ``openstack_inventory.json`` file into
the directory specified with the ``--config`` argument. This is used as the

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

@ -14,5 +14,6 @@ for OpenStack-Ansible.
generate-inventory
configure-inventory
understanding-inventory
manage-inventory
advanced-topics

150
deploy-guide/source/app-custom-layouts.rst → doc/source/reference/inventory/understanding-inventory.rst
View File

@ -1,6 +1,7 @@
================================================
Appendix E: Customizing host and service layouts
================================================
.. _inventory-in-depth:
Understanding the inventory
===========================
The default layout of containers and services in OpenStack-Ansible (OSA) is
determined by the ``/etc/openstack_deploy/openstack_user_config.yml`` file and
@ -21,8 +22,8 @@ To customize the layout of the components for your deployment, modify the
host groups and container groups appropriately before running the installation
playbooks.
Understanding host groups
~~~~~~~~~~~~~~~~~~~~~~~~~
Understanding host groups (conf.d structure)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As part of the initial configuration, each target host appears either in the
``/etc/openstack_deploy/openstack_user_config.yml`` file or in files within
@ -50,8 +51,8 @@ variables to any component containers on the specific host.
particularly for new services, by using a new file in the
``conf.d/`` directory.
Understanding container groups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Understanding container groups (env.d structure)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Additional group mappings are located within files in the
``/etc/openstack_deploy/env.d/`` directory. These groups are treated as
@ -61,11 +62,11 @@ groups, that define where each service deploys. By reviewing files within the
in the default layout.
For example, the ``shared-infra.yml`` file defines a container group,
``shared- infra_containers``, as a subset of the all_containers inventory
group. The ``shared- infra_containers`` container group is mapped to the
``shared-infra_hosts`` host group. All of the service components in the
``shared-infra_containers`` container group are deployed to each target host
in the ``shared-infra_hosts host`` group.
``shared-infra_containers``, as a subset of the ``all_containers``
inventory group. The ``shared- infra_containers`` container group is
mapped to the ``shared-infra_hosts`` host group. All of the service
components in the ``shared-infra_containers`` container group are
deployed to each target host in the ``shared-infra_hosts host`` group.
Within a ``physical_skel`` section, the OpenStack-Ansible dynamic inventory
expects to find a pair of keys. The first key maps to items in the
@ -93,98 +94,53 @@ group. Other services might have more complex deployment needs. They define and
consume inventory container groups differently. Mapping components to several
groups in this way allows flexible targeting of roles and tasks.
Customizing existing components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _affinity:
Deploying directly on hosts
---------------------------
Affinity
~~~~~~~~
To deploy a component directly on the host instead of within a container, set
the ``is_metal`` property to ``true`` for the container group in the
``container_skel`` section in the appropriate file.
When OpenStack-Ansible generates its dynamic inventory, the affinity
setting determines how many containers of a similar type are deployed on a
single physical host.
The use of ``container_vars`` and mapping from container groups to host groups
is the same for a service deployed directly onto the host.
Using ``shared-infra_hosts`` as an example, consider this
``openstack_user_config.yml`` configuration:
.. note::
.. code-block:: yaml
The ``cinder-volume`` component is deployed directly on the host by
default. See the ``env.d/cinder.yml`` file for this example.
shared-infra_hosts:
infra1:
ip: 172.29.236.101
infra2:
ip: 172.29.236.102
infra3:
ip: 172.29.236.103
Omit a service or component from the deployment
-----------------------------------------------
Three hosts are assigned to the `shared-infra_hosts` group,
OpenStack-Ansible ensures that each host runs a single database container,
a single Memcached container, and a single RabbitMQ container. Each host has
an affinity of 1 by default, which means that each host runs one of each
container type.
To omit a component from a deployment, you can use one of several options:
If you are deploying a stand-alone Object Storage (swift) environment,
you can skip the deployment of RabbitMQ. If you use this configuration,
your ``openstack_user_config.yml`` file would look as follows:
- Remove the ``physical_skel`` link between the container group and
the host group by deleting the related file located in the ``env.d/``
directory.
- Do not run the playbook that installs the component.
Unless you specify the component to run directly on a host by using the
``is_metal`` property, a container is created for this component.
- Adjust the :deploy_guide:`affinity <app-advanced-config-affinity.html>`
to 0 for the host group. Similar to the second option listed here, Unless
you specify the component to run directly on a host by using the``is_metal``
property, a container is created for this component.
.. code-block:: yaml
Deploy existing components on dedicated hosts
---------------------------------------------
shared-infra_hosts:
infra1:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.101
infra2:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.102
infra3:
affinity:
rabbit_mq_container: 0
ip: 172.29.236.103
To deploy a ``shared-infra`` component to dedicated hosts, modify the
files that specify the host groups and container groups for the component.
For example, to run Galera directly on dedicated hosts, you would perform the
following steps:
#. Modify the ``container_skel`` section of the ``env.d/galera.yml`` file.
For example:
.. code-block:: yaml
container_skel:
galera_container:
belongs_to:
- db_containers
contains:
- galera
properties:
is_metal: true
.. note::
To deploy within containers on these dedicated hosts, omit the
``is_metal: true`` property.
#. Assign the ``db_containers`` container group (from the preceding step) to a
host group by providing a ``physical_skel`` section for the host group
in a new or existing file, such as ``env.d/galera.yml``.
For example:
.. code-block:: yaml
physical_skel:
db_containers:
belongs_to:
- all_containers
db_hosts:
belongs_to:
- hosts
#. Define the host group (``db_hosts``) in a ``conf.d/`` file (such as
``galera.yml``). For example:
.. code-block:: yaml
db_hosts:
db-host1:
ip: 172.39.123.11
db-host2:
ip: 172.39.123.12
db-host3:
ip: 172.39.123.13
.. note::
Each of the custom group names in this example (``db_containers``
and ``db_hosts``) are arbitrary. Choose your own group names,
but ensure the references are consistent among all relevant files.
This configuration deploys a Memcached container and a database container
on each host, but no RabbitMQ containers.