boma/docs/runbooks/new-role.md

Runbook — Adding a new Ansible role

When to create a new role

Create a new role when you need to manage a distinct, reusable unit of configuration — a service, a system component, or a behaviour applied to a group of hosts.

Do not create a role for a single task that logically belongs in an existing role.

Procedure

1. Scaffold the role

make new-role NAME=<rolename>

This creates the full directory structure and placeholder files under roles/<rolename>/.

2. Fill in meta/main.yml

galaxy_info:
  role_name: <rolename>
  author: <your name>
  description: <one sentence>
  min_ansible_version: "2.15"
  platforms:
    - name: Debian
      versions:
        - trixie  # Debian 13

3. Define defaults

Add all tuneable variables to defaults/main.yml with inline comments explaining each variable. Use the rolename__varname namespace convention.

4. Write tasks

• Use FQCN for all modules
• Every task must have a name: that reads as a sentence
• Every task must have at least one tags: entry
• Notify handlers by listen: topic string, not handler name

5. Configure Molecule

Edit molecule/default/molecule.yml to use the Debian 13 test image. Write a converge.yml that applies the role. Write a verify.yml that asserts the expected state.

6. Write the README

Document:

• Purpose of the role (one paragraph)
• All variables from defaults/main.yml with types, defaults, and descriptions
• Example playbook usage
• Any dependencies or prerequisites

7. Test locally

make test ROLE=<rolename>

Fix any lint or test failures before committing.

8. Add to a playbook

Add the role to the appropriate playbook in playbooks/ and add the host group to inventories/staging/hosts.yml for integration testing.

9. Commit

git checkout -b role/<rolename>
git add roles/<rolename>
git commit -m "Add <rolename> role"
# merge to main once make test passes, then delete the branch