Defining Variables in Playbooks

The simplest way to define variables is to put a vars section in your playbook with the names and values of your variables. Recall from Example 2-8 that we used this approach to define several configuration-related variables, like this:

vars:
  tls_dir: /etc/nginx/ssl/
  key_file: nginx.key
  cert_file: nginx.crt
  conf_file: /etc/nginx/sites-available/default
  server_name: localhost

Ansible also allows you to put variables into one or more files, using a section called vars_files. Let’s say you want to take the preceding example and put the variables in a file named nginx.yml instead of putting them right in the playbook. You would replace the vars section with a vars_files that looks like this:

vars_files:
 - nginx.yml

The nginx.yml file would look like Example 4-1.

key_file: nginx.key
cert_file: nginx.crt
conf_file: /etc/nginx/sites-available/default
server_name: localhost 

You’ll see an example of vars_files in action in Chapter 6 when we use it to separate out the variables that hold sensitive information.

As we discussed in Chapter 3, Ansible also lets you define variables associated with hosts or groups in the inventory. You’ll do this in separate directories that live alongside either the inventory hosts file or your playbooks.

Viewing the Values of Variables

For debugging, it’s often handy to be able to view the output of a variable. You saw in Chapter 2 how to use the debug module to print out an arbitrary message. You can also use it to output the value of the variable. It works like this:

- debug: var=myvarname

This shorthand notation, without a name and in pure-YAML style, is practical in development. We’ll use this form of the debug module several times in this chapter. We typically remove debug statements before going to production.

Registering Variables

Often, you’ll need to set the value of a variable based on the result of a task. Remember that each ansible module returns results in JSON format. To use these results, you create a registered variable using the register clause when invoking a module. Example 4-2 shows how to capture the output of the whoami command to a variable named login.

- name: capture output of whoami command
  command: whoami
  register: login

In order to use the login variable later, you need to know the type of value to expect. The value of a variable set using the register clause is always a dictionary, but the specific keys of the dictionary will be different depending on the module that you use.

Unfortunately, the official Ansible module documentation doesn’t contain information about what the return values look like for each module. It does often mention examples that use the register clause, which can be helpful. I’ve found the simplest way to find out what a module returns is to register a variable and then output that variable with the debug module.

Let’s say we run the playbook shown in Example 4-3.

---
- name: show return value of command module
  hosts: fedora
  gather_facts: false
  tasks:
    - name: capture output of id command
      command: id -un
      register: login
    - debug: var=login
    - debug: msg="Logged in as user {{ login.stdout }}"

The output of the debug module looks like this:

TASK [debug] *******************************************************************
ok: [fedora] => {
    "login": {
        "changed": true,				
        "cmd": [					
            "id",
            "-un"
        ],
        "delta": "0:00:00.002262",
        "end": "2021-05-30 09:25:41.696308",
        "failed": false,
        "rc": 0,					
        "start": "2021-05-30 09:25:41.694046",
        "stderr": "",					
        "stderr_lines": [],
        "stdout": "vagrant",				
        "stdout_lines": [				
            "vagrant"
        ]
    }
}

The changed key is present in the return value of all Ansible modules, and Ansible uses it to determine whether a state change has occurred. For the command and shell module, this will always be set to true unless overridden with the changed_when clause, which we cover in Chapter 8.

The cmd key contains the invoked command as a list of strings.

The rc key contains the return code. If it is nonzero, Ansible will assume the task failed to execute.

The stderr key contains any text written to standard error, as a single string.

The stdout key contains any text written to standard out, as a single string.

The stdout_lines key contains any text written to split by newline. It is a list, and each element of the list is a line of output.

If you’re using the register clause with the command module, you’ll likely want access to the stdout key, as shown in Example 4-4.

- name: capture output of id command
  command: id -un
  register: login
- debug: msg="Logged in as user {{ login.stdout }}"

Sometimes it’s useful to do something with the output of a failed task: for instance, when running a program fails. However, if the task fails, Ansible will stop executing tasks for the failed host. You can use the ignore_errors clause, as shown in Example 4-5, so Ansible does not stop on the error. That allow you to print the program’s output.

- name: run myprog
  command: /opt/myprog
  register: result
  ignore_errors: true
- debug: var=result

The shell module has the same output structure as the command module, but other modules have different keys.

Example 4-6 shows the relevant piece of the output of the stat module that collects properties of a file.

TASK [display result.stat] ***************************************************************************************
ok: [ubuntu] => {
    "result.stat": {
        "atime": 1622724660.888851,
        "attr_flags": "e",
        "attributes": [
            "extents"
        ],
        "block_size": 4096,
        "blocks": 8,
        "charset": "us-ascii",
        "checksum": "7df51a4a26c00e5b204e547da4647b36d44dbdbf",
        "ctime": 1621374401.1193385,
        "dev": 2049,
        "device_type": 0,
        "executable": false,
        "exists": true,
        "gid": 0,
        "gr_name": "root",
        "inode": 784,
        "isblk": false,
        "ischr": false,
        "isdir": false,
        "isfifo": false,
        "isgid": false,
        "islnk": false,
        "isreg": true,
        "issock": false,
        "isuid": false,
        "mimetype": "text/plain",
        "mode": "0644",
        "mtime": 1621374219.5709288,
        "nlink": 1,
        "path": "/etc/ssh/sshd_config",
        "pw_name": "root",
        "readable": true,
        "rgrp": true,
        "roth": true,
        "rusr": true,
        "size": 3287,
        "uid": 0,
        "version": "1324051592",
        "wgrp": false,
        "woth": false,
        "writeable": true,
        "wusr": true,
        "xgrp": false,
        "xoth": false,
        "xusr": false
    }
}

The results from the stat module tell you everything there is to know about a file.

{{ result.stat }}

{{ result[ stat ] }}

result['stat']['mode']
result['stat'].mode
result.stat['mode']
result.stat.mode

Facts

As you’ve already seen, when Ansible runs a playbook, before the first task runs, this happens:

TASK [Gathering Facts] *********************************************************
ok: [debian]
ok: [fedora]
ok: [ubuntu]

When Ansible gathers facts, it connects to the hosts and queries it for all kinds of details about the hosts: CPU architecture, operating system, IP addresses, memory info, disk info, and more. This information is stored in variables that are called facts, and they behave just like any other variable.

Here’s a playbook that prints out the operating system details of each server:

---
- name: 'Ansible facts.'
  hosts: all
  gather_facts: true
  tasks:
    - name: Print out operating system details
      debug:
        msg: >-
          os_family:
          {{ ansible_os_family }},
          distro:
          {{ ansible_distribution }}
          {{ ansible_distribution_version }},
          kernel:
          {{ ansible_kernel }} 

Here’s what the output looks like for the virtual machines running Debian, Fedora, and Ubuntu:

PLAY [Ansible facts.] **********************************************************
TASK [Gathering Facts] *********************************************************
ok: [debian]
ok: [fedora]
ok: [ubuntu]
TASK [Print out operating system details] **************************************
ok: [ubuntu] => {
    "msg": "os_family: Debian, distro: Ubuntu 20.04, kernel: 5.4.0-73-generic"
}
ok: [fedora] => {
    "msg": "os_family: RedHat, distro: Fedora 34, kernel: 5.11.12-300.fc34.x86_64"
}
ok: [debian] => {
    "msg": "os_family: Debian, distro: Debian 10, kernel: 4.19.0-16-amd64"
}
PLAY RECAP *********************************************************************
debian                     : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
fedora                     : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
ubuntu                     : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

$ ansible ubuntu -m setup

ubuntu | SUCCESS => {
    "ansible_facts": {
        "ansible_all_ipv4_addresses": [
            "192.168.4.10",
            "10.0.2.15"
        ],
        "ansible_all_ipv6_addresses": [
            "fe80::a00:27ff:fef1:d47",
            "fe80::a6:4dff:fe77:e100"
        ],
(many more facts)

$ ansible all -m setup -a 'filter=ansible_all_ipv6_addresses'

debian | SUCCESS => {
    "ansible_facts": {
        "ansible_all_ipv6_addresses": [
            "fe80::a00:27ff:fe8d:c04d",
            "fe80::a00:27ff:fe55:2351"
        ]
    },
    "changed": false
}
fedora | SUCCESS => {
    "ansible_facts": {
        "ansible_all_ipv6_addresses": [
            "fe80::505d:173f:a6fc:3f91",
            "fe80::a00:27ff:fe48:995"
        ]
    },
    "changed": false
}
ubuntu | SUCCESS => {
    "ansible_facts": {
        "ansible_all_ipv6_addresses": [
            "fe80::a00:27ff:fef1:d47",
            "fe80::a6:4dff:fe77:e100"
        ]
    },
    "changed": false
}

- name: show a fact returned by a module
  hosts: debian
  gather_facts: false
  tasks:
    - name: get services facts
      service_facts:
    - debug: var=ansible_facts.services['sshd.service'] 

TASK [debug] *******************************************************************
ok: [debian] => {
    "ansible_facts.services['sshd.service']": {
        "name": "sshd.service",
        "source": "systemd",
        "state": "active",
        "status": "enabled"
    }
} 

[book]
title=Ansible: Up and Running
authors=Meijer, Hochstein, Moser
publisher=O'Reilly

- name: print ansible_local
  debug: var=ansible_local
- name: print book title
  debug: msg="The title of the book is {{ ansible_local.example.book.title }}"

TASK [print ansible_local] *****************************************************
ok: [fedora] => {
    "ansible_local": {
        "example": {
            "book": {
                "authors": "Meijer, Hochstein, Moser",
                "publisher": "O'Reilly",
                "title": "Ansible: Up and Running"
            }
        }
    }
}
TASK [print book title] ********************************************************
ok: [fedora] => {
    "msg": "The title of the book is Ansible: Up and Running"
}

Using set_fact to Define a New Variable

Ansible also allows you to set a fact (effectively the same as defining a new variable) in a task by using the set_fact module. I often like to use set_fact immediately after service_facts to make it simpler to refer to a variable.

- name: set nginx_state
  when: ansible_facts.services['nginx.service'] is defined
  set_fact:
    nginx_state: "{{  ansible_facts.services[' nginx.service']['state'] }}"

Example 4-11 demonstrates how to use set_fact so that a variable can be referred to as nginx_state instead of ansible_facts.services[' nginx.service']['state'] .

Built-in Variables

Ansible defines several variables that are always available in a playbook. Some are shown in Table 4-1.

The hostvars, inventory_hostname, and groups variables merit some additional discussion.

{{ hostvars['db.example.com'].ansible_eth1.ipv4.address }}

ubuntu ansible_host=192.168.4.10

- debug: var=hostvars[inventory_hostname]

backend web-backend
{% for host in groups.web %}
  server {{ hostvars[host].inventory_hostname }} 
  {{ hostvars[host].ansible_default_ipv4.address }}:80
{% endfor %}

backend web-backend
  server georgia.example.com 203.0.113.15:80
  server newhampshire.example.com 203.0.113.25:80
  server newjersey.example.com 203.0.113.38:80

Setting Variables on the Command Line

Variables set by passing -e var=value to ansible-playbook have the highest precedence, which means you can use this to override variables that are already defined. Example 4-12 shows how to set the value of the variable named greeting to the value hiya.

$ ansible-playbook 4-12-greet.yml -e greeting=hiya 

Use the ansible-playbook -e variable=value method when you want to use a playbook as you would a shell script that takes a command-line argument. The -e flag effectively allows you to pass variables as arguments.

Example 4-13 shows the playbook that outputs a message specified by a variable.

---
- name: pass a message on the command line
  hosts: localhost
  vars:
    greeting: "you didn't specify a message"
  tasks:
    - name: output a message
      debug:
        msg: "{{ greeting }}"

You can invoke it like this:

$ ansible-playbook 4-12-greet.yml -e greeting=hiya

The output will look like this:

PLAY [pass a message on the command line] **************************************
TASK [Gathering Facts] *********************************************************
ok: [localhost]
TASK [output a message] ********************************************************
ok: [localhost] => {
    "msg": "hiya"
}
PLAY RECAP *********************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

If you want to put a space in the variable, you need to use quotes like this:

$ ansible-playbook greet.yml -e 'greeting="hi there"'

You have to put single quotes around the entire 'greeting="hi there"' so that the shell interprets that as a single argument to pass to Ansible, and you have to put double quotes around "hi there" so that Ansible treats that message as a single string.

Ansible also allows you to pass a file containing the variables instead of passing them directly on the command line by passing @filename.yml as the argument to -e; for example, say you have a file that looks like Example 4-14.

greeting: hiya

You can pass this file to the command line like this:

$ ansible-playbook 4-12-greet.yml -e @4-13-greetvars.yml

Example 4-15 shows a simple technique to display any variable given with the -e flag on the command line.

---
- name: show any variable during debugging.
  hosts: all
  gather_facts: false
  tasks:
    - debug: var="{{ variable }}"

Using this technique effectively gives you a “variable variable” that you can use for debugging.

Precedence

We’ve covered several ways of defining variables. It is possible to define the same variable multiple times for a host, using different values. Avoid this when you can, but if you can’t, then keep in mind Ansible’s precedence rules. When the same variable is defined in multiple ways, the precedence rules determine which value wins (or overrides).

Ansible does apply variable precedence, and you might have a use for it. Here is the order of precedence, from least to greatest. The last listed variables override all other variables:

1. command line values (for example, -u my_user, these are not variables)

2. role defaults (defined in role/defaults/main.yml) 1

3. inventory file or script group vars 2

4. inventory group_vars/all 3

5. playbook group_vars/all 3

6. inventory group_vars/* 3

7. playbook group_vars/* 3

8. inventory file or script host vars 2

9. inventory host_vars/* 3

10. playbook host_vars/* 3

11. host facts / cached set_facts 4

12. play vars

13. play vars_prompt

14. play vars_files

15. role vars (defined in role/vars/main.yml)

16. block vars (only for tasks in block)

17. task vars (only for the task)

18. include_vars

19. set_facts / registered vars

20. role (and include_role) params

21. include params

22. extra vars (for example, -e “user=my_user”)

In this chapter, we covered several ways to define and access variables and facts. Separating variables from tasks and creating inventories with the proper values for the variables allows you to create staging environments for your software. Ansible is very powerful in its flexibility to define data at the appropriate level. The next chapter focuses on a realistic example of deploying an application.