From d3068ba8f66f4a2c2c4c5684a36fa8e0df8b69aa Mon Sep 17 00:00:00 2001 From: CroneKorkN Date: Sun, 10 May 2026 20:27:52 +0200 Subject: [PATCH] agents: nodes carry only node-specific metadata When the left4me bundle was first integrated, ovh.left4me's node file carried ~40 lines of left4me-related metadata (git_url, secret_key, full nginx vhost, monitoring, backups, nftables rules). The maintainer pushed back: per-node metadata should be only what genuinely varies per host. Refactor brought it down to {'domain': 'left4.me'} with everything else in bundle defaults or in a reactor deriving from the domain. Add the rule to bundles/AGENTS.md from the bundle-author angle (use defaults / vault-keyed-on-node for secrets, cite left4me and postgresql for the established pattern). Add the reviewer's form to nodes/AGENTS.md Pitfalls. Co-Authored-By: Claude Opus 4.7 (1M context) --- bundles/AGENTS.md | 10 ++++++++++ nodes/AGENTS.md | 6 ++++++ 2 files changed, 16 insertions(+) diff --git a/bundles/AGENTS.md b/bundles/AGENTS.md index 2b339c8..02c196a 100644 --- a/bundles/AGENTS.md +++ b/bundles/AGENTS.md @@ -41,6 +41,16 @@ bundles// more than one bundle. Don't duplicate logic across bundles. - **Custom item types** (e.g. `download:`) live in [`items/`](../items/AGENTS.md), not per-bundle. +- **Bundles own application-wide knowledge; nodes carry only the few + per-host knobs the bundle actually needs.** When designing a bundle, + identify the per-node knobs (e.g. domain, uplink interface, a + vault-id suffix) and put everything else in `defaults`, or in a + reactor that derives from those knobs. Per-node random secrets + belong in `defaults` via `repo.vault.random_bytes_as_base64_for(...)` + keyed on the node — not in the node file. See + `bundles/left4me/metadata.py:10` (`secret_key` derived in defaults) + and `bundles/postgresql/metadata.py:4` (vault-derived `password_for` + at module scope). ## How to add a new bundle diff --git a/nodes/AGENTS.md b/nodes/AGENTS.md index 150ed45..d51c31d 100644 --- a/nodes/AGENTS.md +++ b/nodes/AGENTS.md @@ -81,6 +81,12 @@ This loader shape has consequences: These are intentional parks/buffers, not bugs. - **`id` must be unique.** A pre-apply hook (`hooks/unique_node_ids.py`) enforces this; duplicate IDs fail `bw test` and `bw apply`. +- **Bloated per-node metadata is usually a bundle smell.** If a + bundle's metadata block in the node file has more than 3-5 keys, + the bundle is probably under-using `defaults` / reactors. Push the + contribution into the bundle (see + [`bundles/AGENTS.md`](../bundles/AGENTS.md#conventions)) rather than + growing the node file. ## See also