Ansible variables and Vault cheat sheet

The chapter on one page: what to remember, the commands and patterns to have at your fingertips, and flashcards for quick revision.

The chapter in eight sentences

Variables let you reuse values across an entire Ansible project; reference them with {{ name }}, and quote the value when the reference comes first.
You can define variables for hosts and host groups in the inventory, and preferably in host_vars and group_vars directories.
You can define variables for plays and tasks in the playbook (vars) or in external files (vars_files).
Precedence decides which value wins: narrower beats wider, the playbook beats the inventory, and extra variables (-e) beat everything.
Dictionaries group related values; read them with dict['key'] or dict.key.
register captures a task's result in a variable for later tasks.
Ansible Vault encrypts sensitive data such as passwords and keys, so the project can be shared safely.
Facts are variables Ansible discovers from each managed host, stored in ansible_facts; you can add your own with custom facts.

Cheat sheet

Variables

- name: Example play
  hosts: webservers
  vars:
    web_pkg: httpd
  vars_files:
    - vars/common.yml
    - vars/secret.yml          # may be Vault-encrypted
  tasks:
    - name: Install {{ web_pkg }}
      ansible.builtin.dnf:
        name: "{{ web_pkg }}"  # quoted: the value starts with {{
      register: install_result

    - ansible.builtin.debug:
        var: install_result['changed']

Project layout

Facts

- name: Facts demo
  hosts: all
  gather_facts: true            # the default; false skips setup
  tasks:
    - ansible.builtin.debug:
        msg: >
          {{ ansible_facts['fqdn'] }} runs
          {{ ansible_facts['distribution'] }} {{ ansible_facts['distribution_version'] }}
          at {{ ansible_facts['default_ipv4']['address'] }}

    - name: Refresh or limit facts
      ansible.builtin.setup:
        gather_subset:
          - '!hardware'

Vault task	Command
Create an encrypted file	`ansible-vault create secret.yml`
Read it	`ansible-vault view secret.yml`
Change it	`ansible-vault edit secret.yml`
Encrypt existing files	`ansible-vault encrypt a.yml b.yml`
Remove encryption	`ansible-vault decrypt a.yml [--output=plain.yml]`
Change the password	`ansible-vault rekey secret.yml`
Run with a prompt	`ansible-navigator run -m stdout --playbook-artifact-enable false site.yml --vault-id @prompt`
Run with a password file	`ansible-navigator run -m stdout site.yml --vault-password-file=vault-pass`

Want	Use
Override for one run	`-e "name=value"`
Every fact of a host	`ansible.builtin.debug: var=ansible_facts`
A custom fact	`ansible_facts['ansible_local']['FILE']['SECTION']['KEY']`
Another host's variables	`hostvars['HOST']['VAR']`
This host's groups	`group_names`
All groups and hosts	`groups`
This host's inventory name	`inventory_hostname`

What characters can a variable name contain?: Letters, numbers and underscores, and it must **start with a letter**.
When must a variable reference be quoted?: When it is the **first thing in the value**: `name: "{{ user }}"`.
Where do group variables go, by recommended practice?: `group_vars/GROUP` (and `host_vars/HOST` for hosts), not in the inventory file.
Which beats which: host_vars or group_vars?: **host_vars**. Narrower scope wins.
Which beats which: inventory variables or play vars?: **Play vars**. The playbook beats the inventory.
What has the highest precedence of all?: Extra variables: `-e` / `--extra-vars` on the command line.
What does register store?: The full JSON result of the task, in a variable you name.
view vs edit in ansible-vault?: `view` only reads; `edit` rewrites the file (shows as a change in Git).
Why must playbook artifacts be disabled for --vault-id @prompt?: Otherwise ansible-navigator cannot prompt and **hangs**.
Which module gathers facts?: `ansible.builtin.setup`, run automatically as Gathering Facts unless `gather_facts: false`.
Where are custom facts stored on the host?: `/etc/ansible/facts.d/*.fact`, in INI or JSON (or an executable printing JSON).
Where do custom facts appear?: `ansible_facts['ansible_local']['FILE']['SECTION']['KEY']`
group_names vs groups?: `group_names`: this host’s groups. `groups`: every group and its hosts.