openstack/tripleo-docs
Code Issues Proposed changes

Merge "Update config-download documentation"

Browse Source
This commit is contained in:
Zuul 2022-11-02 06:03:10 +00:00 committed by Gerrit Code Review
commit cb39bb97d2
2 changed files with 26 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
deploy-guide/source/_images/tripleo_ansible_arch.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 201 KiB

After

Width:  |  Height:  |  Size: 165 KiB

144
deploy-guide/source/deployment/ansible_config_download.rst
View File

@ -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
same parameter values and environment files are passed to Heat as they were
previously. During the stack creation, Heat creates any OpenStack service
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.
Heat is still used to create the stack, then the ansible playbooks are saved
to the filesystem in a git repository. These playbook are used to deploy the
openstack services and configuration to the Overcloud nodes.
The same parameter values and environment files are passed to Heat as they were
previously. During the stack creation, Heat simply takes the user inputs from the
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,
Nova/Ironic instances, etc)
#. Create Heat stack
#. 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
with a separate command and ``ansible-playbook`` run manually. This enables
more manual interaction and debugging.
When running ``openstack overcloud deploy`` with the ``--stack-only`` option, this
will still download the ansible content to the default directory
``$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
``ansible-playbook`` to configure the overcloud nodes::
Once the baremetal nodes have been configured, and the configuration has been
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.