Merge "[DOCS] Applies edits to the OSA install guide appendix C"

doc/source/install-guide/app-custom-layouts.rst

@@ -2,87 +2,86 @@
 Appendix C: Customizing host and service layouts
 ==================================================
 
-Understanding the default layout
+The default layout of containers and services in OpenStack-Ansible (OSA) is
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+determined by the ``/etc/openstack_deploy/openstack_user_config.yml`` file and
+the contents of both the ``/etc/openstack_deploy/conf.d/`` and
+``/etc/openstack_deploy/env.d/`` directories. You use these sources to define
+the *group* mappings that the playbooks use to target hosts and containers for
+roles used in the deploy.
 
-The default layout of containers and services in OpenStack-Ansible is driven
+* You define host groups, which gather the target hosts into *inventory
-by the ``/etc/openstack_deploy/openstack_user_config.yml`` file and the
+  groups*, through the ``/etc/openstack_deploy/openstack_user_config.yml``
-contents of both the ``/etc/openstack_deploy/conf.d/`` and
+  file and the contents of the ``/etc/openstack_deploy/conf.d/`` directory.
-``/etc/openstack_deploy/env.d/`` directories. Use these sources to define the
-group mappings used by the playbooks to target hosts and containers for roles
-used in the deploy.
 
-Conceptually, these can be thought of as mapping from two directions. You
+* You define *container groups*, which can map from the service components
-define host groups, which gather the target hosts into inventory groups,
+  to be deployed up to host groups, through files in the
-through the ``/etc/openstack_deploy/openstack_user_config.yml`` file and the
+  ``/etc/openstack_deploy/env.d/`` directory.
-contents of the ``/etc/openstack_deploy/conf.d/`` directory. You define
-container groups, which can map from the service components to be deployed up
-to host groups, through files in the ``/etc/openstack_deploy/env.d/``
-directory.
 
-To customize the layout of components for your deployment, modify the
+To customize the layout of the components for your deployment, modify the
-host groups and container groups appropriately to represent the layout you
+host groups and container groups appropriately before running the installation
-desire before running the installation playbooks.
+playbooks.
 
 Understanding host groups
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-As part of initial configuration, each target host appears in either the
+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
-the ``/etc/openstack_deploy/conf.d/`` directory. We use a format for files in
+the ``/etc/openstack_deploy/conf.d/`` directory. The format used for files in
-``conf.d/`` which is identical to the syntax used in the
+the ``conf.d/`` directory is identical to the syntax used in the
-``openstack_user_config.yml`` file. These hosts are listed under one or more
+``openstack_user_config.yml`` file.
+
+In these files, the target hosts are listed under one or more
 headings, such as ``shared-infra_hosts`` or ``storage_hosts``, which serve as
-Ansible group mappings. We treat these groupings as mappings to the physical
+Ansible group mappings. These groups map to the physical
 hosts.
 
-The example file ``haproxy.yml.example`` in the ``conf.d/`` directory provides
+The ``haproxy.yml.example`` file in the ``conf.d/`` directory provides
 a simple example of defining a host group (``haproxy_hosts``) with two hosts
 (``infra1`` and ``infra2``).
 
-A more complex example file is ``swift.yml.example``. Here, we
+The ``swift.yml.example`` file provides a more complex example. Here, host
-specify host variables for a target host using the ``container_vars`` key.
+variables for a target host are specified by using the ``container_vars`` key.
 OpenStack-Ansible applies all entries under this key as host-specific
 variables to any component containers on the specific host.
 
 .. note::
 
-   We recommend new inventory groups, particularly for new
+   To manage file size, we recommend that you define new inventory groups,
-   services, to be defined using a new file in the ``conf.d/`` directory in
+   particularly for new services, by using a new file in the
-   order to manage file size.
+   ``conf.d/`` directory.
 
 Understanding container groups
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Additional group mappings can be found within files in the
+Additional group mappings are located within files in the
-``/etc/openstack_deploy/env.d/`` directory. These groupings are treated as
+``/etc/openstack_deploy/env.d/`` directory. These groups are treated as
 virtual mappings from the host groups (described above) onto the container
-groups which define where each service deploys. By reviewing files within the
+groups, that define where each service deploys. By reviewing files within the
 ``env.d/`` directory, you can begin to see the nesting of groups represented
 in the default layout.
 
-We begin our review with ``shared-infra.yml``. In this file we define a
+For example, the ``shared-infra.yml`` file defines a container group,
-new container group (``shared-infra_containers``) as a subset of the
+``shared- infra_containers``, as a subset of the all_containers inventory
-``all_containers`` group. This new container group is mapped to a new
+group. The ``shared- infra_containers`` container group is mapped to the
-(``shared-infra_hosts``) host group. This means you deploy all service
+``shared-infra_hosts`` host group. All of the service components in the
-components under the new (``shared-infra_containers``) container group to each
+``shared-infra_containers`` container group are deployed to each target host
-target host in the host group (``shared-infra_hosts``).
+in the ``shared-infra_hosts host`` group.
 
-Within a ``physical_skel`` segment, the OpenStack-Ansible dynamic inventory
+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
-``container_skel`` and the second key maps to the target host groups
+``container_skel`` section, and the second key maps to the target host groups
-(described above) which are responsible for hosting the service component.
+(described above) that are responsible for hosting the service component.
 
-Next, we review ``memcache.yml``. Here, we define the new group
+To continue the example, the ``memcache.yml``file defines the
-``memcache_container``. In this case we identify the new group as a
+``memcache_container`` container group. This group is a subset of the
-subset of the ``shared-infra_containers`` group, which is itself a subset of
+``shared-infra_containers`` group, which is itself a subset of
 the ``all_containers`` inventory group.
 
 .. note::
 
    The ``all_containers`` group is automatically defined by OpenStack-Ansible.
    Any service component managed by OpenStack-Ansible maps to a subset of the
-   ``all_containers`` inventory group, whether directly or indirectly through
+   ``all_containers`` inventory group, directly or indirectly through
    another intermediate container group.
 
 The default layout does not rely exclusively on groups being subsets of other
@@ -90,7 +89,7 @@ groups. The ``memcache`` component group is part of the ``memcache_container``
 group, as well as the ``memcache_all`` group and also contains a ``memcached``
 component group. If you review the ``playbooks/memcached-install.yml``
 playbook, you see that the playbook applies to hosts in the ``memcached``
-group. Other services may have more complex deployment needs. They define and
+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.
 
@@ -101,92 +100,94 @@ 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 under the
+the ``is_metal`` property to ``true`` for the container group in the
-``container_skel`` in the appropriate file.
+``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 also deployed directly on the host by
+   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, several options exist:
+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. The simplest way to do this is to delete the related
+  the host group by deleting the related file located in the ``env.d/``
-  file located in the ``env.d/`` directory.
+  directory.
-- Do not run the playbook which installs the component.
+- Do not run the playbook that installs the component.
-  Unless you specify the component to run directly on a host using
+  Unless you specify the component to run directly on a host by using the
-  ``is_metal``, a container creates for this component.
+  ``is_metal`` property, a container is created for this component.
-- Adjust the `affinity`_ to 0 for the host group. Unless you
+- Adjust the
-  specify the component to run directly on a host using ``is_metal``,
+  `affinity <http://docs.openstack.org/developer/openstack-ansible/install-guide/app-advanced-config-affinity.html>`_
-  a container creates for this component.
+  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.
 
-.. _affinity: app-advanced-config-affinity.rst
+Deploy existing components on dedicated hosts
+---------------------------------------------
 
-Deploying 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.
 
-To deploy a shared-infra component onto dedicated hosts, modify both the
+For example, to run Galera directly on dedicated hosts, you would perform the
-files specifying the host groups and container groups for the component.
+following steps:
 
-For example, to run Galera directly on dedicated hosts the ``container_skel``
+#. Modify the ``container_skel`` section of the ``env.d/galera.yml`` file.
-segment of the ``env.d/galera.yml`` file might look like:
+   For example:
 
-.. code-block:: yaml
+   .. code-block:: yaml
 
-    container_skel:
+     container_skel:
-      galera_container:
+       galera_container:
-        belongs_to:
+         belongs_to:
-          - db_containers
+           - db_containers
-        contains:
+         contains:
-          - galera
+           - galera
-        properties:
+         properties:
-          log_directory: mysql_logs
+           log_directory: mysql_logs
-          service_name: galera
+           service_name: galera
-          is_metal: true
+           is_metal: true
 
-.. note::
+   .. note::
 
-   If you want to deploy within containers on these dedicated hosts, omit the
+      To deploy within containers on these dedicated hosts, omit the
-   ``is_metal: true`` property. We include it here as a recipe for the more
+      ``is_metal: true`` property.
-   commonly requested layout.
 
-Since we define the new container group (``db_containers`` above), we must
+#. Assign the ``db_containers`` container group (from the preceding step) to a
-assign that container group to a host group. To assign the new container
+   host group by providing a ``physical_skel`` section for the host group
-group to a new host group, provide a ``physical_skel`` for the new host group
+   in a new or existing file, such as ``env.d/galera.yml``.
-(in a new or existing file, such as ``env.d/galera.yml``). For example:
+   For example:
 
-.. code-block:: yaml
+   .. code-block:: yaml
 
-    physical_skel:
+     physical_skel:
-      db_containers:
+       db_containers:
-        belongs_to:
+         belongs_to:
-          - all_containers
+           - all_containers
-      db_hosts:
+       db_hosts:
-        belongs_to:
+         belongs_to:
-          - hosts
+           - hosts
 
-Lastly, define the host group (db_hosts above) in a ``conf.d/`` file (such as
+#. Define the host group (``db_hosts``) in a ``conf.d/`` file (such as
-``galera.yml``):
+   ``galera.yml``). For example:
 
-.. code-block:: yaml
+   .. code-block:: yaml
 
-    db_hosts:
+     db_hosts:
-      db-host1:
+       db-host1:
-        ip: 172.39.123.11
+         ip: 172.39.123.11
-      db-host2:
+       db-host2:
-        ip: 172.39.123.12
+         ip: 172.39.123.12
-      db-host3:
+       db-host3:
-        ip: 172.39.123.13
+         ip: 172.39.123.13
 
-.. note::
+   .. note::
 
-   Each of the custom group names in this example (``db_containers``
+      Each of the custom group names in this example (``db_containers``
-   and ``db_hosts``) were arbitrary. You can choose your own group names
+      and ``db_hosts``) are arbitrary. Choose your own group names,
-   but be sure the references are consistent between all relevant files.
+      but ensure the references are consistent among all relevant files.