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>
1.9 KiB
1.9 KiB
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)
---
# 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 playname:.# 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/credentialis 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
stewardaccount (passwordless sudo; usebecome: true) or one-time bootstrap creds.
Be idempotent — Steward re-runs playbooks (updates, schedules, retries).