Ansible roles lab: a role, handlers and Vault on one Ubuntu VM

This lab is the second level of the Ansible Basics lab. Each student gets an Ubuntu VM of their own with ansible-core installed, a small project and a README, and builds one role from nothing: its variables, a template, tasks with tags, a handler and a token kept in Ansible Vault. The machine itself is the target, over a local connection, so nothing else is needed.

Nothing is installed on the student’s computer. Ansible Basics comes first: it teaches a playbook, a package, a template and running a playbook twice, and this lab does not repeat them.

What students learn

How a playbook grows into a role. The student makes the standard folders with ansible-galaxy role init, which works with no network, and fills in tasks, defaults, vars, templates, handlers and meta. They find out in which order variables win: the role’s defaults lose to a variable set on the play, the role’s own vars beat it, and a value given with -e beats all. They write a Jinja2 template with a loop and a condition and see it with --check and --diff, use loop, register and when, and run only some tasks with --tags and --limit.

A handler that three tasks tell to run must run once, and the student has to make the role run its handlers part way. The last part is Ansible Vault: a file made with ansible-vault, opened with a password file, and a token that is written in plain text nowhere else. Everything is done with Ansible’s own modules, on files, folders and a system user, which a check can see.

The project

The student starts in a folder with an inventory of two names for this one machine, a playbook that uses a role that does not exist yet, and a fake vault password that says it is not a secret. The playbook already sets two variables on the play, so the order of precedence is something the student has to get right, not read. The machine is small: one CPU, 1 GB of memory and 10 GB of disk.

Run it in your browser

VM labs are set as a lab task in a module, and the sample is on the lab’s page. The lab uses only Ubuntu’s archive, so a free account’s VM runs it too.

  1. Add the lab. In a module you teach, add a task and choose the Ubuntu VM lab card. The page shows a short description of the machine instead of a compose file.
  2. Start from the sample. The page offers ready-made labs to start from. Choose Ansible roles, handlers and vault. Using a sample replaces the text, and Undo brings yours back.
  3. Publish and start your own copy. Publish, then Start. The lab’s own setup script installs ansible-core from Ubuntu’s archive and writes the project, the playbook, a fake vault password and the README, the first time the VM starts, in a minute or two.
  4. Open the terminal. Open its terminal and read README.md in the home folder: it says what to do in seven steps and gives none of the answers.

A basic lesson on this lab

Ansible Roles Basics is a small lesson worked in this lab, which is an Ubuntu VM. It has a hook, an I can outcome, key words, a starter, a check after each idea, a common mistake and an exit check, and each step has a Run button that types its command into the machine’s terminal. A student makes a throwaway role to see its folders, runs a small playbook twice to see a variable beaten by -e, sees one handler run for two notifies, and encrypts a value with Vault.

The lesson looks around and leaves the lab’s own role to the student, so it hands out no answers.

How it is marked

The lab has a check. It runs on a copy of the saved machine after a fresh start. It reads the role first: the standard folders, a filled-in meta file, six tasks in the role and not in the playbook, a handler, a loop, tags, and a template with a for loop and an if. It refuses shell, command, raw and script, and a lookup that runs a program. It opens the vault file with the lab’s password and refuses a token written in plain text in the project.

Then it runs the student’s own playbook seven times with values nobody has seen: on a clean machine, again with nothing left to change, as a dry run that must show the change and write nothing, with other values, with each tag, and with --limit on the host the play does not use. It counts the handler runs in the real output, so a handler that runs three times is refused, and reads the files that came out. The first line of what it printed says why.

  1. Hand it out. Assign the lab like any task, with a due date if you want one. Each student gets a VM of their own, kept between sessions.
  2. Run the check. On a student’s row in the class list, press Run the check. It starts a copy of their saved machine that is not saved back, runs the lab’s check script as root and shows whether it passed, what it printed and when. The student is not told the result.
  3. Mark it. Read the first line of what the check printed: it says what is not right, such as a handler that ran three times, a variable in the wrong place or a vault file that does not open. Send the work back with a reason if it needs more.

The definition on GitHub

The file is the whole lab definition, the same text the platform runs: size, setup script, README and check. Copy it and change the role, the variables or the handler to make a longer lab.

Try this lab, and what it costs

A free personal account can work through the basic lessons in this lab, with enough free credit each month to follow most lessons and no card. For a class, a school or college has its first 365 days free for up to 50 students, then pays per student a year, with every lab included and staff free.

Questions people ask

Does the lab need a licence or a paid Ansible?
No. ansible-core is open source and in Ubuntu’s archive, and it is installed when the student’s VM starts. Nothing of it is distributed by us, and nothing is downloaded from anywhere else.
Why is there no service to restart?
The lab shows a handler by what a check can see: how many times it ran, counted in the output of the real run, and a file it writes. A restart of a real service is not something a check can prove, so the lab leaves it out and says so.
Can students harm anything?
Only their own copy. The machine reaches Ubuntu’s archive, PyPI, npm and GitHub and nothing else. The vault password is a fake that is in the project for the lab, and the token is demo data, never a real secret.
Was the lab tested in a real student VM?
The setup, the lesson’s commands and the check, with what a fake does to it, were run in a real Ubuntu 26.04 in a container standing in for the VM. A booted student VM, which starts from a disk image, is worth one try before a class.