bvandeusen
42f7840c26
Extend the playbook metadata convention with a namespaced `# steward:<key>:` comment block: - steward:category — free-text grouping label, shown as a badge in the browse list and on the run form. - steward:confirm — true/yes/1/on marks a playbook destructive; the run form then requires a confirmation tick (required checkbox in the shared vars fragment) before it can launch. sources.discover_playbook_meta() parses description + category + confirm (first match per key; `# description:` still primary, `# steward:description:` alias). discover_playbook_description() now delegates to it. The browse list reads per-playbook meta to show category badges + descriptions; the run-form and playbook-vars fragments render the badge + confirm gate. Bundled playbooks tagged: docker_prune → category maintenance + confirm true; provision/install/update → category host-agent. Docs: docs/reference/playbook-authoring.md updated (keys now implemented) and a quick reference added next to the code at steward/ansible/PLAYBOOK_CONVENTIONS.md. Tests added for category/confirm/alias parsing. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
40 lines
1.9 KiB
Markdown
40 lines
1.9 KiB
Markdown
# Steward playbook conventions (quick reference)
|
|
|
|
What Steward reads from a playbook in this subsystem. Full guide:
|
|
`docs/reference/playbook-authoring.md`. Parser:
|
|
`steward/ansible/sources.py` — `discover_playbook_meta()` and
|
|
`discover_playbook_variables()`.
|
|
|
|
## Magic comments (metadata)
|
|
|
|
```yaml
|
|
---
|
|
# description: One line on what this playbook does. # shown on selection
|
|
# steward:category: maintenance # grouping badge
|
|
# steward:confirm: true # require confirm to run
|
|
- name: … # used as the description if no `# description:` comment
|
|
hosts: all # Steward generates the inventory from the chosen target/group
|
|
```
|
|
|
|
- `# description:` — first match wins; case-insensitive; falls back to first
|
|
play `name:`.
|
|
- `# steward:<key>: <value>` — namespaced metadata. Implemented keys:
|
|
- `category` — free-text grouping label (badge in browse + run form).
|
|
- `confirm` — `true`/`yes`/`1`/`on` → run form requires a confirmation tick.
|
|
- `description` — alias for `# description:` (unprefixed wins if both present).
|
|
- Unknown `# steward:*` keys are ignored (namespace reserved for future use).
|
|
|
|
## Structural cues (no comments needed)
|
|
|
|
- **`vars:` scalars** → editable run-time fields (default shown as placeholder;
|
|
blank = keep default; values sent as highest-precedence extra-vars).
|
|
- **`vars_prompt:`** → run-time fields (required when no default; `private: true`
|
|
→ masked).
|
|
- **Secret naming** — a var whose name contains `password`/`passwd`/`secret`/
|
|
`token`/`api_key`/`private_key`/`credential` is masked **and not persisted**.
|
|
- **`hosts: all`** — target via the run form's scope; don't hardcode hosts.
|
|
- **Credentials** — never embed them. Steward connects as the managed `steward`
|
|
account (passwordless sudo; use `become: true`) or one-time bootstrap creds.
|
|
|
|
Be idempotent — Steward re-runs playbooks (updates, schedules, retries).
|