Merge "Update config-download documentation"

deploy-guide/source/deployment/ansible_config_download.rst

@@ -31,12 +31,12 @@ undercloud by default.
 manner, and will often be used to refer to the method detailed in this
 documentation.
 
-Heat is still used to create the stack and all of the OpenStack resources. The
+Heat is still used to create the stack, then the ansible playbooks are saved
-same parameter values and environment files are passed to Heat as they were
+to the filesystem in a git repository. These playbook are used to deploy the
-previously. During the stack creation, Heat creates any OpenStack service
+openstack services and configuration to the Overcloud nodes.
-resources such as Nova servers and Neutron networks and ports, and then creates
+The same parameter values and environment files are passed to Heat as they were
-the software configuration data necessary to configure the overcloud via
+previously. During the stack creation, Heat simply takes the user inputs from the
-SoftwareDeployment resources.
+templates and renders the required playbooks for the deployment.
 
 The difference with ``config-download`` is that although Heat creates all the
 deployment data necessary via SoftwareDeployment resources to perform the
@@ -67,8 +67,7 @@ workflow steps are automated by tripleoclient. The workflow steps are summarized
 as:
 
 #. Create deployment plan
-#. Create Heat stack along with any OpenStack resources (Neutron networks,
+#. Create Heat stack
-   Nova/Ironic instances, etc)
 #. Create software configuration within the Heat stack
 #. Create tripleo-admin ssh user
 #. Download the software configuration from Heat
@@ -109,11 +108,11 @@ used to influence the behavior of the overcloud deployment as it relates to
                            # arbitrary ansible config to be used when running
                            # ansible-playbook
 
-    --stack-only           # Only update the plan and stack. Skips applying the
+    --stack-only           # Only update the 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.
+                           # ansible-playbook. Skips the stack update.
 
 See ``openstack overcloud deploy --help`` for further help text.
 
@@ -152,32 +151,13 @@ take precendence over the defaults::
       --override-ansible-cfg /home/stack/ansible.cfg
 
 
-config-download with deployed-server
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When using ``config-download`` with :doc:`deployed-server <../features/deployed_server>`
-(pre-provisioned nodes), a ``HostnameMap`` parameter **must** be provided.
-Create an environment file to define the parameter, and assign the node
-hostnames in the parameter value. The following example shows a sample value::
-
-  parameter_defaults:
-    HostnameMap:
-      overcloud-controller-0: controller-00-rack01
-      overcloud-controller-1: controller-01-rack02
-      overcloud-controller-2: controller-02-rack03
-      overcloud-novacompute-0: compute-00-rack01
-      overcloud-novacompute-1: compute-01-rack01
-      overcloud-novacompute-2: compute-02-rack01
-
-Write the contents to an environment file such as ``hostnamemap.yaml``, and
-pass the environment as part of the deployment command with ``-e``.
-
 Ansible project directory
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 The workflow will create an Ansible project directory with the plan name under
-``$HOME/config-download``. For the default plan name of ``overcloud`` the working
+``$HOME/overcloud-deploy/<stack>/config-download``. For the default plan name of ``overcloud`` the working
 directory will be::
 
-    $HOME/config-download/overcloud
+    $HOME/overcloud-deploy/overcloud/config-download/overcloud
 
 The project directory is where the downloaded software configuration from
 Heat will be saved. It also includes other ansible-related files necessary to
@@ -257,64 +237,32 @@ applied.
 
 Manual config-download
 ----------------------
+Prior to running the ansible playbooks generated by config-download, it is necessary
+to ensure the baremetal nodes have already been provisioned. See the baremetal deployment
+guide first:
+
+:doc:`configure-nodes-before-deployment <./network_v2>`
+
 The config-download steps can be skipped when running ``openstack overcloud deploy``
 by passing ``--stack-only``. This will cause tripleoclient to only deploy the Heat
 stack.
 
-When using ``--stack-only``, the deployment data needs to be pulled from Heat
+When running ``openstack overcloud deploy`` with the ``--stack-only`` option, this
-with a separate command and ``ansible-playbook`` run manually. This enables
+will still download the ansible content to the default directory
-more manual interaction and debugging.
+``$HOME/overcloud-deploy/overcloud/config-download``. But it will stop before running
+the ``ansible-playbook`` command.
 
 This method is described in the following sections.
 
-Enable tripleo-admin via SSH
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The tripleo-admin user must be `authorized on the overcloud nodes`_ for use by
-``ansible-playbook``, if using the default user set by
-``tripleo-ansible-inventory``. Authorizing the tripleo-admin user is done by
-running the ``openstack overcloud admin authorize`` command::
-
-    openstack overcloud admin authorize \
-      --overcloud-ssh-user heat-admin \
-      --overcloud-ssh-key ~/.ssh/id_rsa
-
-Alternatively, a user and key that are already authorized on the overcloud
-nodes can be used if that user and key are specified when running
-``tripleo-ansible-inventory``. See `Generate an inventory`_.
-
-Run config-download
-^^^^^^^^^^^^^^^^^^^
-When using the ``--stack-only`` argument, the deployment data needs to be first
-downloaded from Heat. To manually download the software configuration 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``
-as specified by the ``--config-dir`` CLI argument.
-
-Generate an 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. See ``tripleo-ansible-inventory --help``
-for a full list of CLI arguments and options.
 
 Run ansible-playbook
 ^^^^^^^^^^^^^^^^^^^^
-Once the configuration has been downloaded and the inventory generated, run
+Once the baremetal nodes have been configured, and the configuration has been
-``ansible-playbook`` to configure the overcloud nodes::
+downloaded during the ``--stack-only`` run of ``openstack overcloud deploy``. 
+You can then run ``ansible-playbook`` manually to configure the overcloud nodes::
 
     ansible-playbook \
-      -i inventory.yaml \
+      -i /home/stack/config-download/overcloud/tripleo-ansible-inventory.yaml \
       --private-key /path/private/ssh/key \
       --become \
       config-download/deploy_steps_playbook.yaml
@@ -340,20 +288,6 @@ The following minimum configuration is recommended::
     retries = 8
     pipelining = True
 
-.. admonition:: Ceph
-   :class: ceph
-
-   When config-download configures Ceph, Ansible executes ceph-ansible
-   from within the config-download external_deploy_steps_tasks
-   playbook. When config-download is run manually the `ssh_args`
-   argument above will not be inherited by the second Ansible
-   execution. To pass Ansible environment variables to this execution
-   use a Heat environment file like the following::
-
-     parameter_defaults:
-       CephAnsibleEnvironmentVariables:
-         ANSIBLE_HOST_KEY_CHECKING: 'False'
-         ANSIBLE_PRIVATE_KEY_FILE: '/home/stack/.ssh/id_rsa'
 
 .. note::
 
@@ -588,12 +522,8 @@ the ansible project directory.
 
 Complete the :ref:`manual-config-download` steps to create the ansible project
 directory, or use the existing project directory at
-``$HOME/config-download/<plan>``.
+``$HOME/overcloud-deploy/<stack-name>/config-download/<stack-name>``.
 
-.. note::
-
-    The project directory under ``$HOME/config-download/<plan>`` is only updated
-    by ``openstack overcloud deploy`` if ``--stack-only`` is **not** used.
 
 Tags
 ^^^^
@@ -712,8 +642,6 @@ the ``--stack-only`` cli argument::
       --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
@@ -727,23 +655,3 @@ 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.
-
-Generating overcloudrc
-----------------------
-In some cases, it may be required to manually generate the ``overcloudrc``
-file if ``ansible-playbook`` was used manually outside of the workflow.
-
-The following command can be used to generate the ``overcloudrc`` file::
-
-    openstack overcloud credential overcloud
-
-It will generate the ``overcloudrc`` file in the current directory. The
-``--directory`` option can be used to generate it in a different location.
-If needed, substitute the name of the deployment for overcloud.
-
-config-download with Heat SoftwareDeployment outputs
-----------------------------------------------------
-``config-download`` does not support outputs on Heat
-SoftwareDeployment/SoftwareConfig resources. Often, ``deploy_steps_tasks`` can
-be used to reproduce the same behavior that would be handled by an output, by
-using Ansible tasks and the ``register`` keyword.