sjat
3b029352b6
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>
92 lines
2.6 KiB
Markdown
92 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
make new-role NAME=<rolename>
|
|
```
|
|
|
|
This creates the full directory structure and placeholder files under `roles/<rolename>/`.
|
|
|
|
### 2. Fill in meta/main.yml
|
|
|
|
```yaml
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
```
|