Three machines, one way to set them up
A school sets up three computer rooms. The first playbook is one long file that everybody edits, and by June nobody dares touch it. A role is that file cut into a fixed set of folders, so one piece of the setup can be reused, shared and changed alone.
By the end of this lesson
Note
I can say what a role holds and why a handler runs only once.
Key words
- Role: a playbook cut into a fixed set of folders, such as tasks and defaults.
- Variable: a name that holds a value a task can use.
- Precedence: the order that decides which variable wins when two share a name.
- Handler: a task that runs only when another task tells it to.
- Vault: Ansible's way of keeping a file encrypted.
Starter: what you already know
Note
Answer in your head. 1. What is a playbook? 2. What does it mean that a playbook is idempotent? 3. What does a task name, such as ansible.builtin.file, say? You learnt all three in the Ansible Basics lab.
Before you start
Note
Press Start the lab on the bar at the top of this lesson. This lab is a whole Ubuntu machine of your own with Ansible installed, so it takes a little longer to come up than a container. Each Run button types its command into the machine's terminal, one after another in the same session. If one says the machine is still starting, wait a few seconds and press it again. To watch them, or to type your own, press Open terminal on the bar.
A role is a folder with a fixed layout
ansible-galaxy role init makes the folders of an empty role, and it works with no network. Here it makes a role called hello in /tmp, not in your lab. The listing shows the folders. tasks holds what the role does and defaults and vars hold its variables. templates and files hold what it copies, handlers the tasks that wait to be told, and meta says who made it. tests and README.md are extras.
ansible-galaxy role init --init-path /tmp/demo-roles helloShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
ls /tmp/demo-roles/helloShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Check
Tip
Where would a role keep a value that a playbook is meant to be able to change? Answer: in defaults, the weakest place for a variable. A value nobody should change goes in vars.
The same name, two values: one wins
A variable can be set in many places, and the order decides. A role's defaults lose to almost everything. A play's vars beat them, a role's own vars beat the play, and a value given with -e on the command line beats all. This playbook, written to /tmp, sets colour to blue on the play and has two tasks that make a file and tell a handler. Run it, then run it with -e colour=red: the recap says changed=2 both times, because the files are touched each time, and the colour printed follows the order.
printf -- '- hosts: web1\n gather_facts: false\n vars:\n colour: blue\n tasks:\n - ansible.builtin.debug:\n var: colour\n - ansible.builtin.file:\n path: /tmp/demo-a\n state: touch\n notify: Say hello\n - ansible.builtin.file:\n path: /tmp/demo-b\n state: touch\n notify: Say hello\n handlers:\n - name: Say hello\n ansible.builtin.debug:\n msg: hello\n' > /tmp/demo.ymlShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
ansible-playbook -i ~/roles-lab/inventory.ini /tmp/demo.ymlShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
ansible-playbook -i ~/roles-lab/inventory.ini /tmp/demo.yml -e colour=redShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Check
Tip
Why did the colour become red? Answer: a value given with -e has the highest precedence, so it beats the vars of the play.
A common mistake
Warning
Many people think a handler runs every time a task tells it to. A handler waits until the end of the play and then runs once, however many tasks told it to, and only if one of them really changed something. If nothing changed, it does not run at all.
A handler runs once, however many tasks ask
In the playbook, both tasks said notify: Say hello. The output has two changed tasks and then one RUNNING HANDLER line. This command runs the playbook again and keeps only the lines with RUNNING in them: there is one. Ansible can also run the waiting handlers in the middle of a play, with a task called flush_handlers, which a role uses when a later task needs the handler's work to be done.
ansible-playbook -i ~/roles-lab/inventory.ini /tmp/demo.yml | grep RUNNINGShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Check
Tip
Three tasks change something and all notify one handler. How many times does the handler run? Answer: once, at the end of the play, unless it was flushed earlier.
Vault keeps a value encrypted
ansible-vault encrypt_string encrypts one value with a password. The password is in a file: this lab has vault-password.txt, a fake password for practice. What prints starts with demo_var: !vault | and then the header $ANSIBLE_VAULT;1.1;AES256, and the rest is unreadable. You can put that block in a vars file. A whole file can be encrypted too, with ansible-vault create or encrypt, and view shows it again.
ansible-vault encrypt_string --vault-password-file ~/roles-lab/vault-password.txt demo --name demo_varShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Exit check
Tip
Answer without looking back. 1. Which role folder holds the tasks? 2. Which variable wins, one in defaults or one given with -e? 3. How many times does a handler run when two tasks notify it? 4. What does the header $ANSIBLE_VAULT tell you about a file? Answers: tasks; the one given with -e; once; that it is encrypted. Now do the lab: read README.md in your home folder with cat README.md in the terminal.
For teachers
Tip
This lesson is a small example of a lesson worked in a lab: the steps and the Run buttons are the lesson, and the lab is each student's own copy. This lesson is worked in a VM lab: each student has an Ubuntu machine of their own with Ansible on it, and a Run types into its terminal and shows what it printed. Key learning points: 1. A role is a playbook in a fixed set of folders. 2. When two variables share a name, the order of precedence decides, and -e is the strongest. 3. A handler runs once at the end, however many tasks notify it. 4. Vault encrypts a value or a file, and the password is kept apart. Common mistake: believing a handler runs once for every notify. Equipment: the lab and a browser. Tip: before the second run, ask the class which colour will print and why. The lab itself has a check that runs the role and marks the files it makes. Copy it into your own module and change it, or build one from scratch with the Lab menu in the lesson builder.