Chapter 13. Configuring the overcloud with Ansible

Ansible is the main method to apply the overcloud configuration. This chapter provides information about how to interact with the overcloud Ansible configuration.

Although director generates the Ansible playbooks automatically, it is a good idea to familiarize yourself with Ansible syntax. For more information about using Ansible, see


Ansible also uses the concept of roles, which are different to OpenStack Platform director roles. Ansible roles form reusable components of playbooks, whereas director roles contain mappings of OpenStack services to node types.

13.1. Ansible-based overcloud configuration (config-download)

The config-download feature is the method that director uses to configure the overcloud. Director uses config-download in conjunction with OpenStack Orchestration (heat) and OpenStack Workflow Service (mistral) to generate the software configuration and apply the configuration to each overcloud node. Although heat creates all deployment data from SoftwareDeployment resources to perform the overcloud installation and configuration, heat does not apply any of the configuration. Heat only provides the configuration data through the heat API. When director creates the stack, a mistral workflow queries the heat API to obtain the configuration data, generate a set of Ansible playbooks, and applies the Ansible playbooks to the overcloud.

As a result, when you run the openstack overcloud deploy command, the following process occurs:

  • Director creates a new deployment plan based on openstack-tripleo-heat-templates and includes any environment files and parameters to customize the plan.
  • Director uses heat to interpret the deployment plan and create the overcloud stack and all descendant resources. This includes provisioning nodes with the OpenStack Bare Metal service (ironic).
  • Heat also creates the software configuration from the deployment plan. Director compiles the Ansible playbooks from this software configuration.
  • Director generates a temporary user (tripleo-admin) on the overcloud nodes specifically for Ansible SSH access.
  • Director downloads the heat software configuration and generates a set of Ansible playbooks using heat outputs.
  • Director applies the Ansible playbooks to the overcloud nodes using ansible-playbook.

13.2. config-download working directory

Director generates a set of Ansible playbooks for the config-download process. These playbooks are stored in a working directory in the /var/lib/mistral/. This directory is named after the name of the overcloud, which is overcloud by default.

The working directory contains a set of sub-directories named after each overcloud role. These sub-directories contain all tasks relevant to the configuration of the nodes in the overcloud role. These sub-directories also contain additional sub-directories named after each specific node. These sub-directories contain node-specific variables to apply to the overcloud role tasks. As a result, the overcloud roles within the working directory use the following structure:

─ /var/lib/mistral/overcloud
  ├── Controller
  │   ├── overcloud-controller-0
  |   ├── overcloud-controller-1
  │   └── overcloud-controller-2
  ├── Compute
  │   ├── overcloud-compute-0
  |   ├── overcloud-compute-1
  │   └── overcloud-compute-2

Each working directory is a local Git repository that records changes after each deployment operation. Use the local Git repositories to track configuration changes between each deployment.

13.3. Enabling access to config-download working directories

The mistral user in the OpenStack Workflow service (mistral) containers own all files in the /var/lib/mistral/ working directories. You can grant the stack user on the undercloud access to all files in this directory. This helps with performing certain operations within the directory.


  1. Use the setfacl command to grant the stack user on the undercloud access to the files in the /var/lib/mistral directory:

    $ sudo setfacl -R -m u:stack:rwx /var/lib/mistral

    This command retains mistral user access to the directory.

13.4. Checking config-download log

During the config-download process, Ansible creates a log file on the undercloud in the config-download working directory.


  1. View the log with the less command within the config-download working directory. The following example uses the overcloud working directory:

    $ less /var/lib/mistral/overcloud/ansible.log

13.5. Separating the provisioning and configuration processes

The openstack overcloud deploy command runs the heat-based provisioning process and then the config-download configuration process. You can also run the command to execute each process individually.


  1. Source the stackrc file:

    $ source ~/stackrc
  2. Run the deployment command with the --stack-only option. Include any environment files required for your overcloud:

    $ openstack overcloud deploy \
      --templates \
      -e environment-file1.yaml \
      -e environment-file2.yaml \
  3. Wait until the provisioning process completes.
  4. Enable SSH access from the undercloud to the overcloud for the tripleo-admin user. The config-download process uses the tripleo-admin user to perform the Ansible-based configuration:

    $ openstack overcloud admin authorize
  5. Run the deployment command with the --config-download-only option. Include any environment files required for your overcloud:

    $ openstack overcloud deploy \
      --templates \
      -e environment-file1.yaml \
      -e environment-file2.yaml \
  6. Wait until the configuration process completes.

13.6. Running config-download manually

The working directory in /var/lib/mistral/overcloud contains the playbooks and scripts necessary to interact with ansible-playbook directly. This procedure shows how to interact with these files.


  1. Change to the directory of the Ansible playbook::

    $ cd /var/lib/mistral/overcloud/
  2. Run the command to reproduce the deployment:

    $ ./

    You can pass additional Ansible arguments to this script, which are then passed unchanged to the ansible-playbook command. This means that you can use other Ansible features, such as check mode (--check), limiting hosts (--limit), or overriding variables (-e). For example:

    $ ./ --limit Controller
  3. The working directory contains a playbook called deploy_steps_playbook.yaml, which runs the overcloud configuration. To view this playbook, run the following command:

    $ less deploy_steps_playbook.yaml

    The playbook uses various task files contained in the working directory. Some task files are common to all OpenStack Platform roles and some are specific to certain OpenStack Platform roles and servers.

  4. The working directory also contains sub-directories that correspond to each role that you define in your overcloud roles_data file. For example:

    $ ls Controller/

    Each OpenStack Platform role directory also contains sub-directories for individual servers of that role type. The directories use the composable role hostname format:

    $ ls Controller/overcloud-controller-0
  5. The Ansible tasks are tagged. To see the full list of tags, use the CLI argument --list-tags for ansible-playbook:

    $ ansible-playbook -i tripleo-ansible-inventory.yaml --list-tags deploy_steps_playbook.yaml

    Then apply tagged configuration using the --tags, --skip-tags, or --start-at-task with the script:

    $ ./ --tags overcloud
  6. When config-download configures Ceph, Ansible executes ceph-ansible from within the config-download external_deploy_steps_tasks playbook. When you run config-download manually, the second Ansible execution does not inherit the ssh_args argument. To pass Ansible environment variables to this execution, use a heat environment file. For example:

        ANSIBLE_PRIVATE_KEY_FILE: '/home/stack/.ssh/id_rsa'

When you use ansible-playbook CLI arguments such as --tags, --skip-tags, or --start-at-task, do not run or apply deployment configuration out of order. These CLI arguments are a convenient way to rerun previously failed tasks or to iterate over an initial deployment. However, to guarantee a consistent deployment, you must run all tasks from deploy_steps_playbook.yaml in order.

13.7. Performing Git operations on the working directory

The config-download working directory is a local Git repository. Every time a deployment operation runs, director adds a Git commit to the working directory with the relevant changes. You can perform Git operations to view configuration for the deployment at different stages and compare the configuration with different deployments.

Be aware of the limitations of the working directory. For example, if you use Git to revert to a previous version of the config-download working directory, this action affects only the configuration in the working directory. It does not affect the following configurations:

  • The overcloud data schema: Applying a previous version of the working directory software configuration does not undo data migration and schema changes.
  • The hardware layout of the overcloud: Reverting to previous software configuration does not undo changes related to overcloud hardware, such as scaling up or down.
  • The heat stack: Reverting to earlier revisions of the working directory has no effect on the configuration stored in the heat stack. The heat stack creates a new version of the software configuration that applies to the overcloud. To make permanent changes to the overcloud, modify the environment files applied to the overcloud stack before you rerun the openstack overcloud deploy command.

Complete the following steps to compare different commits of the config-download working directory.


  1. Change to the config-download working directory for your overcloud. In this example, the working directory is for the overcloud named overcloud:

    $ cd /var/lib/mistral/overcloud
  2. Run the git log command to list the commits in your working directory. You can also format the log output to show the date:

    $ git log --format=format:"%h%x09%cd%x09"
    a7e9063 Mon Oct 8 21:17:52 2018 +1000
    dfb9d12 Fri Oct 5 20:23:44 2018 +1000
    d0a910b Wed Oct 3 19:30:16 2018 +1000

    By default, the most recent commit appears first.

  3. Run the git diff command against two commit hashes to see all changes between the deployments:

    $ git diff a7e9063 dfb9d12

13.8. Creating config-download files manually

You can generate your own config-download files outside of the standard workflow. For example, you can generate the overcloud heat stack using the --stack-only option with the openstack overcloud deploy command so that you can apply the configuration separately. Complete the following steps to create your own config-download files manually.


  1. Generate the config-download files:

    $ openstack overcloud config download \
      --name overcloud \
      --config-dir ~/config-download
    • --name is the name of the overcloud that you want to use for the Ansible file export.
    • --config-dir is the location where you want to save the config-download files.
  2. Change to the directory that contains your config-download files:

    $ cd ~/config-download
  3. Generate a static inventory file:

    $ tripleo-ansible-inventory \
      --ansible_ssh_user heat-admin \
      --static-yaml-inventory inventory.yaml

Use the config-download files and the static inventory file to perform a configuration. To execute the deployment playbook, run the ansible-playbook command:

$ ansible-playbook \
  -i inventory.yaml \
  --private-key ~/.ssh/id_rsa \
  --become \

To generate an overcloudrc file manually from this configuration, run the following command:

$ openstack action execution run \
  --save-result \
  --run-sync \
  tripleo.deployment.overcloudrc \
  '{"container":"overcloud"}' \
  | jq -r '.["result"]["overcloudrc.v3"]' > overcloudrc.v3

13.9. config-download top level files

The following file are important top level files within a config-download working directory.

Ansible configuration and execution

The following files are specific to configuring and executing Ansible within the config-download working directory.

Configuration file used when running ansible-playbook.
Log file from the last run of ansible-playbook.
JSON structured file that contains any deployment errors.
Executable script to rerun the ansible-playbook command from the last deployment operation.
Private SSH key that Ansible uses to access the overcloud nodes.
Ansible inventory file that contains hosts and variables for all the overcloud nodes.
Archive of the working directory.


The following files are playbooks within the config-download working directory.

Main deployment steps. This playbook performs the main configuration operations for your overcloud.
Pre upgrade steps for major upgrade
Major upgrade steps.
Post upgrade steps for major upgrade.
Minor update steps.
Fast forward upgrade tasks. Use this playbook only when you want to upgrade from one long-life version of Red Hat OpenStack Platform to the next.

13.10. config-download tags

The playbooks use tagged tasks to control the tasks that they apply to the overcloud. Use tags with the ansible-playbook CLI arguments --tags or --skip-tags to control which tasks to execute. The following list contains information about the tags that are enabled by default:

Fact gathering operations.
Ansible roles common to all nodes.
All plays for overcloud deployment.
Deployments that happen before the deploy_steps operations.
Host preparation steps.
Deployment steps.
Steps that happen after the deploy_steps operations.
All external deployment tasks.
External deployment tasks that run on the undercloud only.

13.11. config-download deployment steps

The deploy_steps_playbook.yaml playbook configures the overcloud. This playbook applies all software configuration that is necessary to deploy a full overcloud based on the overcloud deployment plan.

This section contains a summary of the different Ansible plays used within this playbook. The play names in this section are the same names that are used within the playbook and that are displayed in the ansible-playbook output. This section also contains information about the Ansible tags that are set on each play.

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 variables from global_vars.yaml.

Tags: always

Common roles for TripleO servers

Applies common Ansible roles to all overcloud nodes, including 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. Ansible runs these tasks only against the undercloud node.

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_steps

Overcloud common deploy step tasks [1,2,3,4,5]

Applies the common tasks performed at each step, including puppet host configuration,, and paunch (container configuration).

Tags: overcloud, deploy_steps

Server Post Deployments

Applies server specific heat deployments for configuration performed 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. Ansible runs these tasks only against the undercloud node.

Tags: external, external_deploy_steps

13.12. Next Steps

You can now continue your regular overcloud operations.