diff --git a/deploy-guide/source/app.rst b/deploy-guide/source/app.rst index a5bbef4ccf..3facb1a825 100644 --- a/deploy-guide/source/app.rst +++ b/deploy-guide/source/app.rst @@ -5,7 +5,6 @@ Appendices .. toctree:: :maxdepth: 2 - app-custom-layouts.rst app-limited-connectivity.rst app-advanced-config-sslcertificates.rst app-resources.rst diff --git a/doc/source/reference/inventory/configure-inventory.rst b/doc/source/reference/inventory/configure-inventory.rst index 64cd74426b..cf1823e39a 100644 --- a/doc/source/reference/inventory/configure-inventory.rst +++ b/doc/source/reference/inventory/configure-inventory.rst @@ -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/reference/inventory/generate-inventory.rst b/doc/source/reference/inventory/generate-inventory.rst index b9df5b1230..4162407429 100644 --- a/doc/source/reference/inventory/generate-inventory.rst +++ b/doc/source/reference/inventory/generate-inventory.rst @@ -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 diff --git a/doc/source/reference/inventory/inventory.rst b/doc/source/reference/inventory/inventory.rst index 5a54e6905a..561a688b50 100644 --- a/doc/source/reference/inventory/inventory.rst +++ b/doc/source/reference/inventory/inventory.rst @@ -14,5 +14,6 @@ for OpenStack-Ansible. generate-inventory configure-inventory + understanding-inventory manage-inventory advanced-topics diff --git a/deploy-guide/source/app-custom-layouts.rst b/doc/source/reference/inventory/understanding-inventory.rst similarity index 52% rename from deploy-guide/source/app-custom-layouts.rst rename to doc/source/reference/inventory/understanding-inventory.rst index d1c0a9cf14..cdfe7ad1b2 100644 --- a/deploy-guide/source/app-custom-layouts.rst +++ b/doc/source/reference/inventory/understanding-inventory.rst @@ -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 ` - 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.