config-download User's Guide

Adds a full User's Guide for config-download, documenting most
everything I could think of that would be useful.

Previously the page was under the "Feature Configuration" section, and
it's now moved to it's own top level section witin the ToC.

There are a few other minor fixes and improvements included.

Change-Id: I9bc2df4f44ac4ccea565d632d0072c2c4d7b3a43

doc/source/install/advanced_deployment/ansible_config_download.rst

@@ -1,14 +1,20 @@
 .. _config_download:
 
-Deploying with Ansible
+TripleO config-download User's Guide: Deploying with Ansible
-======================
+=============================================================
+
+Introduction
+------------
+This documentation details using ``config-download``.
+
+``config-download`` is the feature that enables deploying the Overcloud software
+configuration with Ansible in TripleO.
 
 Summary
 -------
-
+Starting with the Queens release, it is possible to use Ansible to apply the
-Starting in the Queens release, it is possible to use Ansible to apply the
+overcloud configuration. In the Rocky release, this method is the new default
-overcloud configuration. In the Rocky release, this method using Ansible is the
+behavior.
-new default behavior.
 
 Ansible is used to replace the communication and transport of the software
 configuration deployment data between Heat and the Heat agent
@@ -20,28 +26,29 @@ by running ``ansible-playbook`` with an Ansible inventory file and a set of
 playbooks and tasks.
 
 The Ansible control node (the node running ``ansible-playbook``) is the
-undercloud. The terms "control node" and undercloud refer to the same node
+undercloud by default.
-where the undercloud installation has been performed.
 
 ``config-download`` is the feature name that enables using Ansible in this
 manner, and will often be used to refer to the method detailed in this
 documentation.
 
-Heat is still used in the typical fashion to create the stack and all of the
+Heat is still used to create the stack and all of the OpenStack resources. The
-OpenStack resources. The same parameter values and environment files are
+same parameter values and environment files are passed to Heat as they were
-passed to Heat as usual. Heat then creates any OpenStack service resources as
+previously. During the stack creation, Heat creates any OpenStack service
-it usually does, such as Nova servers and Neutron networks and ports.
+resources such as Nova servers and Neutron networks and ports, and then creates
+the software configuration data necessary to configure the overcloud via
+SoftwareDeployment resources.
 
-The difference is that although Heat creates all the deployment data necessary
+The difference with ``config-download`` is that although Heat creates all the
-via SoftwareDeployment resources to perform the overcloud installation and
+deployment data necessary via SoftwareDeployment resources to perform the
-configuration, it does not apply any of the software deployments. The data is
+overcloud installation and configuration, it does not apply any of the software
-only made available via the Heat API, and an additional config-download
+deployments. The data is only made available via the Heat API. Once the stack
-Mistral workflow is triggered after the Heat stack is completed that downloads
+is created, an additional config-download Mistral workflow is triggered that
-all of the deployment data from Heat.
+downloads all of the deployment data from Heat.
 
-Using the downloaded data, the workflow generates Ansible playbooks and tasks
+Using the downloaded deployment data, the workflow then generates Ansible
-that are then used by the undercloud to complete the configuration of the
+playbooks and tasks that are used by the undercloud to complete the
-overcloud.
+configuration of the overcloud using ``ansible-playbook``.
 
 This diagram details the overall sequence of how using config-download
 completes an overcloud deployment:
@@ -50,49 +57,84 @@ completes an overcloud deployment:
     :scale: 40%
 
 
-Deployment workflow
+Deployment with config-download
--------------------
+-------------------------------
-Ansible and config-download will be used by default when ``openstack overcloud
+Ansible and ``config-download`` are used by default when ``openstack
-deploy`` (tripleoclient) is run. All of the workflow steps are automated by
+overcloud deploy`` (tripleoclient) is run. The command is backwards compatible
-tripleoclient and Mistral workflow(s).
+in terms of functionality, meaning that running ``openstack overcloud deploy``
+will still result in a full overcloud deployment.
 
-The workflow steps are summarized as:
+The deployment is done through a series of automated workflows and steps in
+tripleoclient. All of the workflow steps are automated by tripleoclient and
+Mistral workflow(s).  The workflow steps are summarized as:
 
-#. (Heat) Creating OpenStack resources (Neutron networks, Nova/Ironic instances, etc)
+#. Create deployment plan
-#. (Heat) Creating software configuration
+#. Create Heat stack along with any OpenStack resources (Neutron networks,
-#. (tripleoclient) Enable tripleo-admin ssh user
+   Nova/Ironic instances, etc)
-#. (ansible) Applying the created software configuration to the Nova/Ironic instances
+#. Create software configuration within the Heat stack
+#. Create tripleo-admin ssh user
+#. Download the software configuration from Heat
+#. Applying the downloaded software configuration to the overcloud nodes with
+   ``ansible-playbook``.
 
-The deployment procedure starts by creating the Heat stack, which creates the
+Creating the ``tripleo-admin`` user on each overcloud node is necessary since
-OpenStack resources and software configuration. Once the stack operation is
+ansible uses ssh to connect to each node to perform configuration.
-completed, tripleoclient creates a ``tripleo-admin`` user on each overcloud
-node.
 
 The following steps are done to create the ``tripleo-admin`` user:
 
 #. Create temporary ssh keys on the undercloud
-#. Use a deployer specified private ssh key (defaults to ``~/.ssh/id_rsa``) to
+#. Use a deployer-specified private ssh key (defaults to ``~/.ssh/id_rsa``) to
    connect to each overcloud node as a deployer specified user (defaults to
    ``heat-admin``) and adds the temporary public ssh key to
    ``~/.ssh/authorized_keys`` for that user.
 #. Executes a Mistral workflow to create ``tripleo-admin`` on each node,
    passing as input the temporary private ssh key and ssh user to Mistral.
-#. The workflow creates ``tripleo-admin`` and gives sudo permissions to the
+#. The workflow creates the ``tripleo-admin`` user and gives sudo permissions
-   user, as well as creates and stores a new ssh keypair specific to
+   to the user, as well as creates and stores a new ssh keypair specific to
    ``tripleo-admin``. This keypair (private and public) are stored in the
    Mistral database.
 #. After the completion of the workflow, the temporary ssh public key is
    deleted from ``~/.ssh/authorized_keys`` on each overcloud node, and the
    temporary keypair is then deleted from the undercloud.
 
+With these steps, the deployer-specified ssh key which is used for the inital
+connection is never sent or stored by any API service.
+
 To override the deployer specified ssh private key and user, there are cli args
 available with ``openstack overcloud deploy``::
 
-    --overcloud-ssh-user
+    --overcloud-ssh-user # defaults to heat-admin
-    --overcloud-ssh-key
+    --overcloud-ssh-key  # defaults to ~/.ssh/id_rsa
 
-After ``tripleo-admin`` is created, ``ansible-playbook`` will be used to apply
+The values for these cli arguments must be the same for all nodes in the
-the software configuration to the overcloud nodes.
+overcloud deployment. ``overcloud-ssh-key`` should be the private key that
+corresponds with the public key specified by the Heat parameter ``KeyName``
+when using Ironic deployed nodes.
+
+config-download related CLI arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There are some new CLI arguments for ``openstack overcloud deploy`` that can be
+used to influence the behavior of the overcloud deployment as it relates to
+``config-download``::
+
+    --overcloud-ssh-user   # Initial ssh user used for creating tripleo-admin.
+                           # Defaults to heat-admin
+
+    --overcloud-ssh-key    # Initial ssh private key (file path) to be used for
+                           # creating tripleo-admin.
+                           # Defaults to ~/.ssh/id_rsa
+
+    --override-ansible-cfg # path to an ansible config file, to inject any
+                           # arbitrary ansible config to be used when running
+                           # ansible-playbook
+
+    --stack-only           # Only update the plan and stack. Skips applying the
+                           # software configuration with ansible-playbook.
+
+    --config-download-only # Only apply the software configuration with
+                           # ansible-playbook. Skips the stack and plan update.
+
+See ``openstack overcloud deploy --help`` for further help text.
 
 .. include:: deployment_output.rst
 
@@ -103,9 +145,9 @@ the software configuration to the overcloud nodes.
 config-download with deployed-server
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 When using ``config-download`` with :doc:`deployed-server <deployed_server>`
-(pre-provisioned nodes), a ``HostnameMap`` parameter must be provided. Create
+(pre-provisioned nodes), a ``HostnameMap`` parameter **must** be provided.
-an environment file to define the parameter, and assign the node hostnames in
+Create an environment file to define the parameter, and assign the node
-the parameter value. The following example shows a sample value::
+hostnames in the parameter value. The following example shows a sample value::
 
   parameter_defaults:
     HostnameMap:
@@ -117,35 +159,39 @@ the parameter value. The following example shows a sample value::
       overcloud-novacompute-2: compute-02-rack01
 
 Write the contents to an environment file such as ``hostnamemap.yaml``, and
-pass it the environment as part of the deployment command.
+pass the environment as part of the deployment command with ``-e``.
 
 Mistral workflow
-^^^^^^^^^^^^^^^^
+----------------
-The Mistral workflow that runs config-download and ``ansible-playbook`` is
+The Mistral workflow that will be called by tripleoclient and runs
+config-download and ``ansible-playbook`` is
 ``tripleo.deployment.v1.config_download_deploy``.
 
-The workflow will create a working directory with the plan name under
+Ansible project directory
-``/var/lib/mistral`` where all of the ansible related files are stored.
+^^^^^^^^^^^^^^^^^^^^^^^^^
+The workflow will create an Ansible project directory with the plan name under
+``/var/lib/mistral``. For the default plan name of ``overcloud`` the working
+directory will be::
 
-Ansible working directory
+    /var/lib/mistral/overcloud
-_________________________
-The workflow uses a working directory with the plan name under
-``/var/lib/mistral`` to store the generated files needed to run
-``ansible-playbook``.
 
-All of the files under ``/var/lib/mistral/<plan name>`` are owned by the
+The project directory is where the downloaded software configuration from
-mistral user and readable by the mistral group. The interactive user account on
+Heat will be saved. It also includes other ansible-related files necessary to
-the undercloud can be granted read-only access to these files by adding the
+run ``ansible-playbook`` to configure the overcloud.
-user to the ``mistral`` group::
 
-    sudo usermod -a -G mistral $USER
+All of the files in the Ansible project directory at
+``/var/lib/mistral/<plan>`` are owned by the mistral user and readable by the
+mistral group from the mistral-executor container. The interactive user account
+on the undercloud can be granted read-only access to these files by using the
+following setacl command::
+
+    sudo setfacl -R -m u:$USER:rwx /var/lib/mistral
 
 Once a member of the ``mistral`` group, the contents of
-``/var/lib/mistral/<plan name>`` can be browsed, examined, and
+``/var/lib/mistral/<plan>`` can be browsed, examined, and
-``ansible-playbook`` rerun if needed for debugging purposes.
+``ansible-playbook`` rerun if desired.
 
-Within this directory, all the files are present to rerun
+The contents of the project directory include the following files:
-``ansible-playbook``:
 
 tripleo-ansible-inventory.yaml
   Ansible inventory file containing hosts and vars for all the overcloud nodes.
@@ -158,12 +204,9 @@ ansible-playbook-command.sh
 ssh_private_key
   Private ssh key used to ssh to the overcloud nodes.
 
-The rest of the files are the actual Ansible playbooks, tasks, templates, and
-vars to complete the deployment.
-
 Reproducing ansible-playbook
-____________________________
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Once in the ``mistral`` working directory, simply run
+Once in the project directory created by the Mistral workflow, simply run
 ``ansible-playbook-command.sh`` to reproduce the deployment::
 
     ./ansible-playbook-command.sh
@@ -173,48 +216,95 @@ Any additional arguments passed to this script will be passed unchanged to the
 
     ./ansible-playbook-command.sh --check
 
-Using this method it is possible to take advantage of Ansible features, such as
+Using this method it is possible to take advantage of various Ansible features,
-check mode (``--check``), limiting hosts (``--limit``), overriding variables
+such as check mode (``--check``), limiting hosts (``--limit``), or overriding
-(``-e``), etc.
+variables (``-e``).
 
-ansible-playbook manual execution
+Git repository
----------------------------------
+^^^^^^^^^^^^^^
+The ansible project directory is a git repository. Each time config-download
+downloads the software configuration data from Heat, the project directory will
+be checked for differences. A new commit will be created if there are any
+changes from the previous revision.
+
+From within the ansible project directory, standard git commands can be used to
+explore each revision. Commands such as ``git log``, ``git show``, and ``git
+diff`` are useful ways to describe how each commit to the software
+configuration differs from previous commits.
+
+Applying earlier versions of configuration
+__________________________________________
+Using commands such as ``git revert`` or ``git checkout``, it is possible to
+update the ansible project directory to an earlier version of the software
+configuration.
+
+It is possible to then apply this earlier version with ``ansible-playbook``.
+However, caution should be exercised as this could lead to a broken overcloud
+deployment. Only well understood earlier versions should be attempted to be
+applied.
+
+.. note::
+
+    Data migration changes will never be undone by applying an earlier version
+    of the software configuration with config-download. For example, database
+    schema migrations that had already been applied would never be undone by
+    only applying an earlier version of the configuration.
+
+    Software changes that were related to hardware changes in the overcloud
+    (such as scaling up or down) would also not be completely undone by
+    applying earlier versions of the software configuration.
+
+.. note::
+
+    Reverting to earlier revisions of the project directory has no effect on
+    the configuration stored in the Heat stack. A corresponding change should
+    be made to the deployment templates, and the stack updated to make the
+    changes permanent.
+
+.. _manual-config-download:
+
+Manual config-download
+----------------------
 The Mistral workflow that runs config-download can be skipped when running
 ``openstack overcloud deploy`` by passing ``--stack-only``. This will cause
 tripleoclient to only deploy the Heat stack.
 
-If not using the Mistral workflow, the deployment data needs to be pulled from
+When using ``--stack-only``, the deployment data needs to be pulled from Heat
-Heat with a separate command and ``ansible-playbook`` run manually. This
+with a separate command and ``ansible-playbook`` run manually. This enables
-enables more manual interaction and debugging.
+more manual interaction and debugging.
 
-These methods are described in the following sections.
+This method is described in the following sections.
 
-Manual ansible-playbook
+Run config-download
-^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^
-When using the ``--stack-only`` argument, the deployment data needs to be
+When using the ``--stack-only`` argument, the deployment data needs to be first
-downloaded from Heat and ``ansible-playbook`` run manually.
+downloaded from Heat. To manually download the software configuration data, use
-
+the ``openstack overcloud config download`` command::
-To manually download and generate all of the ansible playbook and deployment
-data, use the ``openstack overcloud config download`` command::
 
     openstack overcloud config download \
       --name overcloud \
       --config-dir config-download
 
 The ansible data will be generated under a directory called ``config-download``
-based on the ``--config-dir`` CLI argument.
+as specified by the ``--config-dir`` CLI argument.
 
-To generate an inventory file to use with ``ansible-playbook`` use
+Generate an inventory
-``tripleo-ansible-inventory``::
+^^^^^^^^^^^^^^^^^^^^^
+To generate an inventory file to use with ``ansible-playbook`` use the
+``tripleo-ansible-inventory`` command::
 
     tripleo-ansible-inventory \
       --ansible_ssh_user centos \
       --static-yaml-inventory inventory.yaml
 
 The above example shows setting the ansible ssh user as ``centos``. This can be
-changed depending on the environment.
+changed depending on the environment. See ``tripleo-ansible-inventory --help``
+for a full list of CLI arguments and options.
 
-The following illustrates an example execution of ``ansible-playbook``::
+Run ansible-playbook
+^^^^^^^^^^^^^^^^^^^^
+Once the configuration has been downloaded and the inventory genreated, run
+``ansible-playbook`` to configure the overcloud nodes::
 
     ansible-playbook \
       -i inventory.yaml \
@@ -222,27 +312,249 @@ The following illustrates an example execution of ``ansible-playbook``::
       --become \
       config-download/deploy_steps_playbook.yaml
 
-Adjust the command as needed for a given environment.
+.. note::
 
-Ansible playbook structure
+    ``--become`` is required when running ansible-playbook.
---------------------------
+
+All default ansible configuration values will be used when manually running
+``ansible-playbook`` in this manner. These values can be customized through
+`ansible configuration
+<https://docs.ansible.com/ansible/latest/installation_guide/intro_configuration.html>`_.
+
+The following minimum configuration is recommended and matches the default
+values used by the mistral workflow that runs ``config-download``::
+
+    [defaults]
+    log_path = ansible.log
+    forks = 25
+    timeout = 30
+
+    [ssh_connection]
+    ssh_args = -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o ControlMaster=auto -o ControlPersist=30m
+    retries = 8
+    pipelining = True
+
+
+Ansible project directory contents
+----------------------------------
 This section details the structure of the ``config-download`` generated
-playbooks and tasks.
+Ansible project directory.
 
 Playbooks
 ^^^^^^^^^
-The following playbooks are generated with ``config-download``:
+deploy_steps_playbook.yaml
+  Initial deployment or template update (not minor update)
+
+  Further detailed in :ref:`deploy_steps_playbook.yaml`
+fast_forward_upgrade_playbook.yaml
+  Fast forward upgrades
+post_upgrade_steps_playbook.yaml
+  Post upgrade steps for major upgrade
+pre_upgrade_rolling_steps_playbook.yaml
+  Pre upgrade steps for major upgrade
+update_steps_playbook.yaml
+  Minor update steps
+upgrade_steps_playbook.yaml
+  Major upgrade steps
+
+.. _deploy_steps_playbook.yaml:
 
 deploy_steps_playbook.yaml
-  Used for deployment and stack updates. Not for minor updates or major
+__________________________
-  upgrades.
+``deploy_steps_playbook.yaml`` is the playbook used for deployment and template
-update_steps_playbook.yaml
+update. It applies all the software configuration necessary to deploy a full
-  Used for minor updates.
+overcluod based on the templates provided as input to the deployment command.
+
+This section will summarize at high level the different ansible plays used
+within this playbook. The play names shown here are the same names used within
+the playbook and are what will be shown in the output when ``ansible-playbook`` is
+run.
+
+The ansible tags set on each play are also shown below.
+
+Gather facts from undercloud
+  Fact gathering for the undercloud node
+
+  tags: facts
+Gather facts from overcloud
+  Fact gathering for the overcloud nodes
+
+  tags: facts
+Load global variables
+  Loads all varaibles from `l`global_vars.yaml``
+
+  tags: always
+Common roles for TripleO servers
+  Applies common ansible roles to all overcloud nodes. Includes
+  ``tripleo-bootstrap`` for installing bootstrap packages and
+  ``tripleo-ssh-known-hosts`` for configuring ssh known hosts.
+
+  tags: common_roles
+Overcloud deploy step tasks for step 0
+  Applies tasks from the ``deploy_steps_tasks`` template interface
+
+  tags: overcloud, deploy_steps
+Server deployments
+  Applies server specific Heat deployments for configuration such as networking
+  and hieradata. Includes ``NetworkDeployment``, ``<Role>Deployment``,
+  ``<Role>AllNodesDeployment``, etc.
+
+  tags: overcloud, pre_deploy_steps
+Host prep steps
+  Applies tasks from the ``host_prep_steps`` template interface
+
+  tags: overcloud, host_prep_steps
+External deployment step [1,2,3,4,5]
+  Applies tasks from the ``external_deploy_steps_tasks`` template interface.
+  These tasks are run against the undercloud node only.
+
+  tags: external, external_deploy_steps
+Overcloud deploy step tasks for [1,2,3,4,5]
+  Applies tasks from the ``deploy_steps_tasks`` template interface
+
+  tags: overcloud, deploy_setps
+Overcloud common deploy step tasks [1,2,3,4,5]
+  Applies the common tasks done at each step to include puppet host
+  configuration, ``docker-puppet.py``, and ``paunch`` (container configuration).
+
+  tags: overcloud, deploy_setps
+Server Post Deployments
+  Applies server specific Heat deployments for configuration done after the 5
+  step deployment process.
+
+  tags: overcloud, post_deploy_steps
+External deployment Post Deploy tasks
+  Applies tasks from the ``external_post_deploy_steps_tasks`` template interface.
+  These tasks are run against the undercloud node only.
+
+  tags: external, external_deploy_steps
+
+
+Task files
+^^^^^^^^^^
+These task files include tasks specific to their intended function. The task
+files are automatically used by specific playbooks from the previous section.
+
+**boot_param_tasks.yaml**
+
+**common_deploy_steps_tasks.yaml**
+
+**docker_puppet_script.yaml**
+
+**external_deploy_steps_tasks.yaml**
+
+**external_post_deploy_steps_tasks.yaml**
+
+**fast_forward_upgrade_bootstrap_role_tasks.yaml**
+
+**fast_forward_upgrade_bootstrap_tasks.yaml**
+
+**fast_forward_upgrade_post_role_tasks.yaml**
+
+**fast_forward_upgrade_prep_role_tasks.yaml**
+
+**fast_forward_upgrade_prep_tasks.yaml**
+
+**fast_forward_upgrade_release_tasks.yaml**
+
+**upgrade_steps_tasks.yaml**
+
+**update_steps_tasks.yaml**
+
+**pre_upgrade_rolling_steps_tasks.yaml**
+
+**post_upgrade_steps_tasks.yaml**
+
+**post_update_steps_tasks.yaml**
+
+Heat Role directories
+^^^^^^^^^^^^^^^^^^^^^
+Each Heat role from the roles data file used in the deployment (specified with
+``-r`` from the ``openstack overcloud deploy`` command), will have a
+correspondingly named directory.
+
+When using the default roles, these directories would be:
+
+**Controller**
+
+**Compute**
+
+**ObjectStorage**
+
+**BlockStorage**
+
+**CephStorage**
+
+A given role directory contains role specific task files and a subdirectory for
+each host for that role. For example, when using the default hostnames, the
+**Controller** role directory would contain the following host subdirectories:
+
+**overcloud-controller-0**
+
+**overcloud-controller-1**
+
+**overcloud-controller-2**
+
+Variable and template related files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+group_vars
+  Directory which contains variables specific to different ansible inventory
+  groups.
+global_vars.yaml
+  Global ansible variables applied to all overcloud nodes
+templates
+  Directory containing any templates used during the deployment
+
+Other files
+^^^^^^^^^^^
+Files in this section are only present in the project directory if the mistral
+workflow was used to generate the project directory under
+``/var/lib/mistral/<plan>``
+
+ansible.cfg
+  Ansible configuration file
+ansible-errors.json
+  JSON structured file containing any deployment errors
+ansible.log
+  Ansilbe log file
+ansible-playbook-command.sh
+  Script to reproduce ansible-playbook command
+ssh_private_key
+  SSH private key used by ansible to access overcloud nodes
+tripleo-ansible-inventory.yaml
+  Ansible inventory file
+overcloud-config.tar.gz
+  Tarball of Ansible project directory
+
+Running specific tasks
+----------------------
+Running only specific tasks (or skipping certain tasks) can be done from within
+the ansible project directory.
+
+.. note::
+
+    Skipping tasks is only recommended for specific scenarios where the
+    deployer is aware of the impact of skipping or only running certain tasks.
+
+    This can be useful during troubleshooting and debugging scenarios, but
+    should be used with caution as it can result in an overcloud that is not
+    fully configured.
+
+Complete the :ref:`manual-config-download` steps to create the ansible project
+directory, or use the existing project directory at
+``/var/lib/mistral/<plan>``.
+
+.. note::
+
+    The project directory under ``/var/lib/mistral/<plan>`` is only updated
+    by ``openstack overcloud deploy`` if the mistral workflow is used for
+    ``config-download`` (e.g., ``--stack-only`` is **not** used).
 
 Tags
 ^^^^
-The playbooks use tagged tasks for finer grained control of what to apply if
+The playbooks use tagged tasks for finer-grained control of what to apply if
-desired. The enabled tags are:
+desired. Tags can be used with the ``ansible-playbook`` CLI arguments ``--tags`` or
+``--skip-tags`` to control what tasks are executed. The enabled tags are:
 
 facts
   fact gathering
@@ -263,6 +575,89 @@ external
 external_deploy_steps
   external deployments that run on the undercloud
 
+See :ref:`deploy_steps_playbook.yaml` for a description of which tags apply to
+specific plays in the deployment playbook.
+
+Server specific pre and post deployments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The list of server specific pre and post deployments run during the `Server
+deployments` and `Server Post Deployments` plays (see
+:ref:`deploy_steps_playbook.yaml`) are dependent upon what custom roles and
+templates are used with the deployment.
+
+The list of these tasks are defined in an ansible group variable that applies
+to each server in the inventory group named after the Heat role. From the
+ansible project directory, the value can be seen within the group variable file
+named after the Heat role::
+
+    $ cat group_vars/Compute
+    Compute_pre_deployments:
+      - UpgradeInitDeployment
+      - HostsEntryDeployment
+      - DeployedServerBootstrapDeployment
+      - InstanceIdDeployment
+      - NetworkDeployment
+      - ComputeUpgradeInitDeployment
+      - ComputeDeployment
+      - ComputeHostsDeployment
+      - ComputeAllNodesDeployment
+      - ComputeAllNodesValidationDeployment
+      - ComputeHostPrepDeployment
+      - ComputeArtifactsDeploy
+
+    Compute_post_deployments:  []
+
+``<Role>_pre_deployments`` is the list of pre deployments, and
+``<Role>_post_deployments`` is the list of post deployments.
+
+To specify the specific task to run for each deployment, the value of the
+variable can be defined on the command line when running ``ansible-playbook``,
+which will overwrite the value from the group variable file for that role.
+
+For example::
+
+    ansible-playbook \
+      -e Compute_pre_deployments=NetworkDeployment \
+      --tags pre_deploy_steps
+      # other CLI arguments
+
+Using the above example, only the task for the ``NetworkDeployment`` resource
+would get applied since it would be the only value defined in
+``Compute_pre_deployments``, and ``--tags pre_deploy_steps`` is also specified,
+causing all other plays to get skipped.
+
+Starting at a specific task
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To start the deployment at a specific task, use the ``ansible-playbook`` CLI
+argument ``--start-at-task``. To see a list of task names for a given playbook,
+``--list-tasks`` can be used to list the task names.
+
+Previewing changes
+------------------
+Changes can be previewed to see what will be changed before any changes are
+applied to the overcloud. To preview changes, the stack update must be run with
+the ``--stack-only`` cli argument::
+
+    openstack overcloud deploy \
+      --stack-only
+      # other CLI arguments
+
+Once the update is complete, complete the :ref:`manual-config-download` steps
+to create the ansible project directory.
+
+When ansible-playbook is run, use the ``--check`` CLI argument with
+ansible-playbook to preview any changes. The extent to which changes can be
+previewed is dependent on many factors such as the underlying tools in use
+(puppet, docker, etc) and the support for ansible check mode in the given
+ansible module.
+
+The ``--diff`` option can aloso be used with ``--check`` to show the
+differences that would result from changes.
+
+See `Ansible Check Mode ("Dry Run")
+<https://docs.ansible.com/ansible/2.5/user_guide/playbooks_checkmode.html>`_
+for more details.
+
 config-download with Heat SoftwareDeployment outputs
 ----------------------------------------------------
 ``config-download`` does not support outputs on Heat

doc/source/install/advanced_deployment/deployment_log.rst

@@ -1,5 +1,5 @@
 Deployment Log
---------------
+^^^^^^^^^^^^^^
 The ansible part of the deployment creates a log file that is saved on the
-undercloud. The log file is available  ``/var/lib/mistral/<plan
+undercloud. The log file is available at ``/var/lib/mistral/<plan
 name>/ansible.log``.

doc/source/install/advanced_deployment/deployment_output.rst

@@ -1,4 +1,9 @@
-The output from ``ansible-playbook`` will then begin to appear in the console
+Deployment Output
+^^^^^^^^^^^^^^^^^
+After the tripleo-admin user is created, ``ansible-playbook`` will be used to
+configure the overcloud nodes.
+
+The output from ``ansible-playbook`` will begin to appear in the console
 and will be updated periodically as more tasks are applied.
 
 When ansible is finished a play recap will be shown, and the usual overcloudrc

doc/source/install/advanced_deployment/deployment_status.rst

@@ -1,5 +1,5 @@
 Deployment Status
------------------
+^^^^^^^^^^^^^^^^^
 Since Heat is no longer the source of authority on the status of the overcloud
 deployment, a new tripleoclient command is available to show the overcloud
 deployment status::
@@ -8,7 +8,7 @@ deployment status::
 
 The output will report the status of the deployment, taking into consideration
 the result of all the steps to do the full deployment. The following is an
-example of the sample output::
+example of the output::
 
     [stack@undercloud ]$ openstack overcloud status
 

doc/source/install/advanced_deployment/features.rst

@@ -27,6 +27,5 @@ Documentation on how to enable and configure various features available in
    disable_telemetry
    server_blacklist
    split_stack
-   ansible_config_download
    ansible_config_download_differences
    rhsm

doc/source/install/index.rst

@@ -15,6 +15,7 @@ TripleO Install Guide
   containers_deployment/index
   post_deployment/post_deployment
   advanced_deployment/features
+  advanced_deployment/ansible_config_download.rst
   advanced_deployment/baremetal_nodes
   advanced_deployment/backends
   advanced_deployment/custom

doc/source/install/troubleshooting/troubleshooting-overcloud.rst

@@ -85,6 +85,16 @@ in the resulting table.
   ``virt-manager`` tool for virtual machines and vendor-specific virtual
   console (e.g. iDRAC for DELL) for bare metal machines.
 
+Showing deployment failures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Deployment failures can be shown with the following command::
+
+    [stack@undercloud ]$ openstack overcloud failures --plan my-deployment
+
+The command will show any errors encountered when running ``ansible-playbook``
+to configure the overcloud during the ``config-download`` process. See
+:ref:`config_download` for more information.
+
 Debugging Using Heat
 ^^^^^^^^^^^^^^^^^^^^