Passing Variables to an Ansible Playbook From the Command Line

1. Overview

Ansible is a popular tool that automates manual IT processes such as application deployment and configuration management. Since we can use the same playbook or task on different systems, we may need to differentiate the systems using variables. For example, while applying a patch to several servers using a single playbook, we may use variables to differentiate the server names.

One way of providing variables to a playbook is via the command line. In this tutorial, we’ll discuss how to pass a variable to an Ansible playbook from the command line. The version of Ansible we use in the examples is 2.12.0.

2. Example Playbook

We’ll use the following playbook, example_playbook.yml:

$ cat example_playbook.yml 
- hosts: localhost
  name: Example Ansible Playbook
  vars:
    user_name: '{{ firstname }}'
    user_surname: '{{ surname }}'
  tasks:
    - name: Print message
      debug:
        msg: Hello {{ user_name }} {{ user_surname }}

Our playbook has a single task that prints a greeting message using a person’s name and surname. We use the msg parameter of Ansible’s built-in debug module to print the greeting, Hello {{ user_name }} {{ user_surname }}.

The variables we use in the greeting message, namely user_name and user_surname, are defined in the vars directive.

The first variable definition, user_name: ‘{{ firstname }}’, defines the variable named user_name. This variable takes its value from another variable, firstname.

Similarly, the second variable, user_surname, takes its value from another variable, surname. We specify it using user_surname: ‘{{ surname }}’.

As we’ll see shortly, we’ll provide the values of firstname and surname from the command line.

Let’s look at the inventory file we’ll be using, which we’ve named inventory:

$ cat inventory
localhost ansible_connection=local

The only host within the inventory is localhost.

3. The -e Option

We can use the -e option of the ansible-playbook command to pass variables to a playbook from the command line. The –extra-vars option can also be used. It’s the long counterpart of the -e option.

There’s more than one format to pass variables using the -e option. We’ll see them in the following subsections.

3.1. Using Key-Value Pairs

One format is to pass the variables as a key-value pair:

$ ansible-playbook -i inventory example_playbook.yml -e "firstname=John surname=Doe"
 
PLAY [Example Ansible Playbook] ********************************************************************************************************
 
TASK [Gathering Facts] *****************************************************************************************************************
ok: [localhost]
 
TASK [Print message] *******************************************************************************************************************
ok: [localhost] => {
    "msg": "Hello John Doe" 
} 

PLAY RECAP *****************************************************************************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

The -i option of ansible-playbook specifies the inventory file, which is inventory in our case. We also pass the name of the playbook, example_playbook.yml, to ansible-playbook.

We set the firstname variable in example_playbook.yml using the firstname=John key-value pair. Similarly, we set the surname variable using the surname=Doe key-value pair. We pass these to the playbook using a single -e option, namely -e “firstname=John surname=Doe”.

As is apparent from the output of the Print message task, “msg”: “Hello John Doe”, we successfully passed the variables to the Ansible playbook.

It’s also possible to pass each variable using separate -e options:

$ ansible-playbook -i inventory example_playbook.yml -e firstname=John -e surname=Doe

The output will be the same as before.

3.2. Using JSON

Alternatively, we can pass variables to a playbook from the command line using the JSON format:

$ ansible-playbook -i inventory example_playbook.yml -e '{"firstname":"John", "surname":"Doe"}'

This time, we pass a JSON document, {“firstname”:”John”, “surname”:”Doe”}, using the -e option. The variables are the fields in the JSON document.

3.3. Using a JSON or YAML File

We can define variables in a separate file dedicated to variables and pass this file to ansible-playbook using the -e option. This file can be a JSON or YAML file:

$ cat variables.json
{    firstname: "John",
     surname:   "Doe"
}
$ cat variables.yml
firstname: "John"
surname:   "Doe"

Here, we store the variables in two files, variables.json and variables.yml. We can use either of them. However, we need to prepend the @ symbol to the file name:

$ ansible-playbook -i inventory example_playbook.yml -e "@variables.json"
$ ansible-playbook -i inventory example_playbook.yml -e "@variables.yml"

This method might be preferable if there are many variables we need to pass to the playbook.

4. Conclusion

In this article, we discussed how to pass a variable to an Ansible playbook from the command line using the -e option of ansible-playbook.

There are several formats that we can use with the -e option. We saw that passing the variables as key-value pairs is one option. Alternatively, we can also pass them in the JSON format. Finally, we learned that we can store the variables in a JSON or YAML file, and pass the file to ansible-playbook.