sjat/boma

sjat 3b029352b6 Add per-service SECURITY.md convention; one role per service

Revise ADR-004 to a service-role standard: every service is its own
self-contained role with a required file set including SECURITY.md, uniform
deploy mechanics, and a deferred shared-engine option (with revisit trigger)
recorded in the ADR.

Add the per-service security record:
- docs/security/service-security-template.md — canonical SECURITY.md template
  (exposure, checklist status, service-specific hardening, residual risks)
- roles/<service>/SECURITY.md is where each service records how it meets the bar;
  /security-review aggregates roles/*/SECURITY.md and cross-checks against config
- service-checklist.md noted as the generic bar the record answers

Wire-up: new-role runbook step writes SECURITY.md from the template; ADR-002
governance bullet points at it; CLAUDE.md role conventions require it and mandate
one-role-per-service; STATUS records the convention as defined-not-yet-applied.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-04 16:09:33 +02:00

2.6 KiB

Raw Blame History

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. Write the per-service security record (services)

For a service role, copy docs/security/service-security-template.md to roles/<rolename>/SECURITY.md and fill it in: exposure, the checklist status (from docs/security/service-checklist.md), service-specific hardening, and any residual/accepted risks. Filling the Checklist status section is how the service clears the security bar — record any conscious deviation in docs/security/accepted-risks.md. The bar is established by ADR-002; enforcement is manual in review today, with the planned /security-review aggregating every roles/*/SECURITY.md to automate it.

10. 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

2.6 KiB Raw Blame History