Chapter 11. Configuring the overcloud with Ansible

Ansible is the main method to apply the overcloud configuration. This chapter provides steps how to interact with the overcloud’s Ansible configuration.

Although director generates the Ansible playbooks automatically, it is a good idea to familiarize yourself with Ansible syntax. See for more information about how to use Ansible.


Ansible also uses the concept of roles, which are different to OpenStack Platform director roles.

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

The config-download feature is the director’s method of configuring the overcloud. The 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 the 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 running the openstack overcloud deploy command, the following process occurs:

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

11.2. config-download working directory

The director generates a set of Ansible playbooks for the config-download process. These playbooks are stored in a working directory within 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. This helps you track configuration changes between each deployment.

11.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.

11.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

11.5. 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 makes it is possible to take further advantage of 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 with 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 defined in your overcloud’s 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. For example:

    $ 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. For example:

    $ ./ --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 using 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 iterating over an initial deployment. However, to guarantee a consistent deployment, you must run all tasks from deploy_steps_playbook.yaml in order.

11.6. Performing Git operations on the working directory

The config-download working directory is a local Git repository. Each time a deployment operation runs, the 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, using Git to revert to a previous version of the config-download working directory only affects 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 prior to rerunning openstack overcloud deploy.

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 case, 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

11.7. Creating config-download files manually

In certain circumstances, you might 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 overcloud to use for the Ansible file export.
    • --config-dir is the location 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

11.8. 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 upgrading from one long-life version of OpenStack Platform to the next. Do not use this playbook for this release of OpenStack Platform.

11.9. config-download tags

The playbooks use tagged tasks to control the tasks applied 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.

11.10. config-download deployment steps

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

This section contains a summary the different Ansible plays used within this playbook. The play names in this section are the same names used within the playbook and 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 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_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 against the undercloud node only.

Tags: external, external_deploy_steps

11.11. Next Steps

You can now continue your regular overcloud operations.