Chapter 10. Configuring the overcloud with Ansible


This feature is available in this release as a Technology Preview, and therefore is not fully supported by Red Hat. It should only be used for testing, and should not be deployed in a production environment. For more information about Technology Preview features, see Scope of Coverage Details.

It is possible to use Ansible as the main method to apply the overcloud configuration. This chapter provides steps on enabling this feature on your overcloud.

Although director automatically generates the Ansible playbooks, 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.

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

The config-download feature:

  • Enables application of the overcloud configuration with Ansible instead of Heat.
  • Replaces the communication and transport of the configuration deployment data between Heat and the Heat agent (os-collect-config) on the overcloud nodes

Heat retains the standard functionality with or without config-download enabled:

  • The director passes environment files and parameters to Heat.
  • The director uses Heat to create the stack and all descendant resources.
  • Heat still creates any OpenStack service resources, including bare metal node and network creation.

Although Heat creates all deployment data from SoftwareDeployment resources to perform the overcloud installation and configuration, it does not apply any of the configuration. Instead, Heat only provides the data through its API. Once the stack is created, a Mistral workflow queries the Heat API for the deployment data and applies the configuration by running ansible-playbook with an Ansible inventory file and a generated set of playbooks.

10.2. Switching the overcloud configuration method to config-download

The following procedure switches the overcloud configuration method from OpenStack Orchestration (heat) to an Ansible-based config-download method. In this situation, the undercloud acts as the Ansible control node i.e. the node running ansible-playbook. The terms control node and undercloud refer to the same node where the undercloud installation has been performed.


  1. Source the stackrc file.

    $ source ~/stackrc
  2. Run the overcloud deployment command and include the --config-download option and the environment file to disable heat-based configuration:

    $ openstack overcloud deploy --templates \
        --config-download \
        -e /usr/share/openstack-tripleo-heat-templates/environments/config-download-environment.yaml \
        --overcloud-ssh-user heat-admin \
        --overcloud-ssh-key ~/.ssh/id_rsa \

    Note the use of the following options:

    • --config-download enables the additional Mistral workflow, which applies the configuration with ansible-playbook instead of Heat.
    • -e /usr/share/openstack-tripleo-heat-templates/environments/config-download-environment.yaml is a required environment file that maps the Heat software deployment configuration resources to their Ansible-based equivalents. This provides the configuration data through the Heat API without Heat applying configuration.
    • --overcloud-ssh-user and --overcloud-ssh-key are used to SSH into each overcloud node, create an initial tripleo-admin user, and inject an SSH key into /home/tripleo-admin/.ssh/authorized_keys. To inject the SSH key, the user specifies credentials for the initial SSH connection with --overcloud-ssh-user (defaults to heat-admin) and --overcloud-ssh-key (defaults to ~/.ssh/id_rsa). To limit exposure to the private key specified with --overcloud-ssh-key, the director never passes this key to any API service, such as Heat or Mistral, and only the director’s openstack overcloud deploy command uses this key to enable access for the tripleo-admin user.

    When running this command, make sure you also include any other files relevant to your overcloud. For example:

    • Custom configuration environment files with -e
    • A custom roles (roles_data) file with --roles-file
    • A composable network (network_data) file with --networks-file
  3. The overcloud deployment command performs the standard stack operations. However, when the overcloud stack reaches the configuration stage, the stack switches to the config-download method for configuring the overcloud:

    2018-05-08 02:48:38Z [overcloud-AllNodesDeploySteps-xzihzsekhwo6]: UPDATE_COMPLETE  Stack UPDATE completed successfully
    2018-05-08 02:48:39Z [AllNodesDeploySteps]: UPDATE_COMPLETE  state changed
    2018-05-08 02:48:45Z [overcloud]: UPDATE_COMPLETE  Stack UPDATE completed successfully
     Stack overcloud UPDATE_COMPLETE
    Deploying overcloud configuration

    Wait until the overcloud configuration completes.

  4. After the Ansible configuration of the overcloud completes, the director provides a report of the successful and failed tasks and the access URLs for the overcloud:

    PLAY RECAP **********************************************************        : ok=173  changed=42   unreachable=0    failed=0        : ok=133  changed=42   unreachable=0    failed=0
    localhost          : ok=2    changed=0    unreachable=0    failed=0
    Ansible passed.
    Overcloud configuration completed.
    Started Mistral Workflow tripleo.deployment.v1.get_horizon_url. Execution ID: 0e4ca4f6-9d14-418a-9c46-27692649b584
    Overcloud Endpoint:
    Overcloud Horizon Dashboard URL:
    Overcloud rc file: /home/stack/overcloudrc
    Overcloud Deployed

If using pre-provisioned nodes, you need to perform an additional step to ensure a successful deployment with config-download.

10.3. Enabling config-download with pre-provisioned nodes

When using config-download with pre-provisioned nodes, you need to map Heat-based hostnames to their actual hostnames so that ansible-playbook can reach a resolvable host. Use the HostnameMap to map these values.


  1. Create an environment file (e.g. hostname-map.yaml) and include the HostnameMap parameter and the hostname mappings. Use the following syntax:


    The [HEAT HOSTNAME] usually follows the following convention: [STACK NAME]-[ROLE]-[INDEX]. For example:

        overcloud-controller-0: controller-00-rack01
        overcloud-controller-1: controller-01-rack02
        overcloud-controller-2: controller-02-rack03
        overcloud-compute-0: compute-00-rack01
        overcloud-compute-1: compute-01-rack01
        overcloud-compute-2: compute-02-rack01
  2. Save the contents of hostname-map.yaml.
  3. When running a config-download deployment, include the environment file with the -e option. For example:

    $ openstack overcloud deploy --templates \
        --config-download \
        -e /usr/share/openstack-tripleo-heat-templates/environments/config-download-environment.yaml \
        -e /home/stack/templates/hostname-map.yaml \
        --overcloud-ssh-user heat-admin \
        --overcloud-ssh-key ~/.ssh/id_rsa \

10.4. Enabling access to config-download working directories

Mistral performs the execution of the Ansible playbooks for the config-download feature. Mistral saves the playbooks, configuration files, and logs in a working directory. You can find these working directories in /var/lib/mistral/ and are named using the UUID of the Mistral workflow execution.

Before accessing these working directories, you need to set the appropriate permissions for your stack user.


  1. The mistral group can read all files under /var/lib/mistral. Grant the interactive stack user on the undercloud read-only access to these files:

    $ sudo usermod -a -G mistral stack
  2. Refresh the stack user’s permissions with the following command:

    [stack@director ~]$ exec su -l stack

    The command prompts you to log in again. Enter the stack user’s password.

  3. Test read access to the /var/lib/mistral directory:

    $ ls /var/lib/mistral/

10.5. Checking config-download logs and working directory

During the config-download process, Ansible creates a log file on the undercloud at /var/lib/mistral/<execution uuid>/ansible.log. The <execution uuid> is a UUID that corresponds to the Mistral execution that ran ansible-playbook.


  1. List all executions using the openstack workflow execution list command and find the workflow ID of the chosen Mistral execution that executed config-download:

    $ openstack workflow execution list
    $ less /var/lib/mistral/<execution uuid>/ansible.log

    <execution uuid> is the UUID of the Mistral execution that ran ansible-playbook.

  2. Alternatively, look for the most recently modified directory under /var/lib/mistral to quickly find the log for the most recent deployment:

    $ less /var/lib/mistral/$(ls -t /var/lib/mistral | head -1)/ansible.log

10.6. Running config-download manually

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


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

    $ cd /var/lib/mistral/<execution uuid>/

    <execution uuid> is the UUID of the Mistral execution that ran ansible-playbook.

  2. Once in the mistral working directory, run to reproduce the deployment:

    $ ./
  3. You can pass additional Ansible arguments to this script, which in turn are 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
  4. The working directory contains a playbook called deploy_steps_playbook.yaml, which runs the overcloud configuration. To view this playbook:

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

  5. 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
  6. 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

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.

10.7. Disabling config-download

To switch back to the standard Heat-based configuration method, remove the relevant option and environment file the next time you run openstack overcloud deploy.


  1. Source the stackrc file.

    $ source ~/stackrc
  2. Run the overcloud deployment command but do not include the --config-download option or the 'config-download-environment.yaml` environment file:

    $ openstack overcloud deploy --templates \

    When running this command, make sure you also include any other files relevant to your overcloud. For example:

    • Custom configuration environment files with -e
    • A custom roles (roles_data) file with --roles-file
    • A composable network (network_data) file with --networks-file
  3. The overcloud deployment command performs the standard stack operations, including configuration with Heat.

10.8. Next Steps

You can now continue your regular overcloud operations.