Ansible lab: configure a machine with a playbook, in your browser

This lab gives each student an Ubuntu machine of their own and an unfinished Ansible playbook. They finish it so that it installs a package, makes a file from a template with a variable in it and writes a systemd unit file, then run it a second time and see that nothing changes. Nothing is installed on the student’s computer, and a script marks the result, so you do not have to read each machine.

What students learn

What a playbook is: a list of tasks in YAML, each naming a module that does one job. Variables, and a template that fills a file in from one. The difference between describing the state a machine should be in and typing the commands that get it there. Above all idempotence: a good playbook run twice leaves the machine as the first run left it, and the recap at the end says changed=0.

The task

The lab leaves a project in the home folder: an inventory with this one machine over a local connection, a settings file, a template with a variable in it and a playbook with three jobs missing. Job 1 is a package, tree. Job 2 is the file /etc/ansible-lab/welcome.txt, made from the template, owned by root with mode 0644. Job 3 is the unit file /etc/systemd/system/lab-greeter.service, whose description carries the variable. The README says what to do in each and gives no tasks, modules or answers. The student only writes the file: the service is not started.

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 machine is small: one CPU, 1 GB of memory and 10 GB of disk.

  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 basics. 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 from Ubuntu’s archive and writes the project and the README the first time the VM starts, in about ten seconds.
  4. Open the terminal. Open its terminal and read README.md in the home folder: it says the three jobs to finish in the playbook and gives none of the answers.

A basic lesson on this lab

Ansible Basics is a small lesson worked in this lab, which is an Ubuntu VM: each step is explained and has a Run button that types its command into the machine’s terminal and shows what it printed. A student lists the project, reads the unfinished playbook, runs it and sees that it changes nothing, and asks a module whether the lab’s folder exists yet.

The lesson looks around and leaves the lab’s own task, finishing the playbook, to the student, so it hands out no answers. It is deliberately small: it shows a teacher what a lesson worked in a lab is, and the lab does the rest. Copy it into a module of your own to change it.

How it is marked

The lab has a check. It runs on a copy of the saved machine after a fresh start, so it sees only what the student saved. It reads the playbook and refuses one made of shell, command, raw or script tasks, or one that hides them in an include or a role. It reads the saved package and files. Then it runs the student’s playbook twice with a site name nobody has seen: the files it makes must carry that name, which a file typed by hand does not, and the second run must report changed=0, which a task that changes something every time does not. The first line of what the check printed says what is not right.

What it cannot stop is a determined student with administrator rights on their own machine, who could tamper with Ansible itself. It is a check for a classroom, not a proof.

  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 file that does not carry the variable or the task that changed on a second run. 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 package, the paths or the jobs to make a lab of your own.

Questions people ask

Does the check start the service?
No. It reads the unit file and never starts it: the lab is about writing the file with Ansible, and what is marked is the file’s owner, mode and content.
Can the lab teach Terraform as well?
Not in this lab. The machine reaches only Ubuntu’s archive, PyPI, npm and GitHub, and Terraform downloads its providers from a registry the machine cannot reach, so only Ansible is offered. Ansible is installed from Ubuntu’s archive when the VM starts.
What does the playbook manage?
The VM itself, over a local connection, since each student has one machine. The real commands work: ansible-playbook, ansible-doc and --check for a dry run.