# Introduction `debian-ansible` is a collection of Ansible roles for managing Debian systems. The roles are re-usable and parameterised so that they can be adapted to some variations. This document describes the roles and also acts as an acceptance test suite for them. The [Subplot][] program can generate a test program based on this document, and the test program tests that the roles work as intended. [Subplot]: https://subplot.liw.fi/ ## Using these roles Eventually, all the roles included with `debian-ansible` will follow the same principles: * the playbook using a role defines which version of each role they expect to use by defining a variable such as `unix_users_version` - the role checks that it's defined to the right value and fails if it isn't * the role is parameterized via variables, with names prefixed with the role name - the role `unix_users` expects a variable `unix_users` that lists all the users to create * any variables used by role have "empty" default values, unless the variable must be defined by the playbook using the role - the role will check that the necessary variables are defined, before doing anything # Implementation and testing of these roles If you're just using the roles, you don't need to care about this chapter. ## Source files At the root of the `debian-ansible` source tree is a `subplot.md`, and the subdirectory `subplot` with some other files used by the main file. Each role directory should have a `subplot.md`, and may also have `subplot.yaml` and `subplot.py`. The files in role directories get combined with the main ones the the `./check` script. ## Scenario structure Each `subplot.md` file is meant to contain at least one scenario. All scenarios have the same structure: * create a new VM * construct an Ansible playbook that uses the role in a specific way * run the playbook against the VM * examine the VM to verify it has been changed in the expected way The VM is created using a base image, which the user must specify to the test program by setting the `BASEIMAGE` environment variable. ## Sanity check Verify that everything looks OK and that other scenarios can be run. ~~~scenario given a host running Debian then I can run /bin/true on the host ~~~ --- title: "debian-ansible—Ansible roles for Debian systems" author: Lars Wirzenius bindings: - subplot.yaml functions: - subplot.py ...