summaryrefslogtreecommitdiff
path: root/subplot.md
blob: 952ba9538a71e9d112994b5318a219d843099c61 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
---
title: "debian-ansible—Ansible roles for Debian systems"
author: Lars Wirzenius
bindings:
- subplot.yaml
impls:
  python:
  - subplot.py
  - lib/runcmd.py
...


# 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
~~~