feat: the Core overlay packages (0041 step 2) #20

Merged

marcos-mendez merged 4 commits from feat/core-overlay-packages into 19.x

2026-09-30 14:00:45 -03:00

marcos-mendez commented

2026-09-30 12:29:46 -03:00

(Migrated from github.com)

Step 2 of handbook decision 0041's first implementation: one Debian source package per overlay under packages/<name>/, each with its own changelog and version (0.1.0), its manifest beside debian/, installed as /usr/share/keel/overlays/<name>.yaml exactly as docs/manifest-v1.md gives it.

Package	Depends
keel-overlay-installer	inithooks (>= 2.3.6+keel14), confconsole (>= 2.2.3+keel8), keel (>= 0.12.0)
keel-overlay-wireguard	wireguard-tools (>= 1.0.20210914), keel
keel-overlay-etcd	etcd-server (>= 3.5.16), keel-overlay-wireguard (its manifest `requires` it), keel
keel-overlay-crowdsec	crowdsec (>= 1.4.6-10), crowdsec-firewall-bouncer (>= 0.0.25), keel

CrowdSec is trixie's: 0029's open task has not chosen a newer one.

Unit state

etcd and both CrowdSec units end up disabled and stopped. Two parts do it (packages/README.md):

The overlay's postinst, on its first installation only, runs deb-systemd-helper disable and, where systemd runs, deb-systemd-invoke stop. Later upgrades of the Debian packages keep that state: their snippets re-enable only while was-enabled holds, and deb-systemd-invoke never starts a disabled unit. Overlay upgrades do nothing, so a state set by keel apply stays.
A preset disable (20-keel-overlay-<name>.preset). Measured: on a first boot with /etc/machine-id set to uninitialized and the presets moved aside, all three units were enabled and active. With the presets they stayed disabled.

No mask, so keel apply can enable them.

Tests

CI packages / build: packages/build (dpkg-buildpackage and lintian, failing on any warning; no overrides were needed).
CI packages / install: installs the four packages with keel, inithooks and confconsole built from pinned commits in a trixie container, then runs tests/overlay-install.bats (13 tests).
Real test on a fresh debootstrap trixie LXC container (ov-test, now destroyed):
- image path: a chroot install under policy-rc.d, then the first boot;
- live path: apt install with systemd running;
- the bats suite: 13/13.
Final state on the booted container: etcd, crowdsec and crowdsec-firewall-bouncer were all disabled and inactive, and keel manifest validate returned ok for each overlay. As a control, the same apt install without the overlays left all three enabled and active.

For the maintainer

keel manifest validate does not run inside the package build. The unit files and hooks it checks belong to the dependencies, so it runs on the installed machine.
The manifests' screen paths (Networking/wireguard.py, Security/crowdsec.py) do not exist in confconsole yet. The existing screen is Instance/Overlay_network.py. Validation does not check whether screen files exist.
crowdsec's own postinst registers with CrowdSec's central API at install time and fails without network. An image build would therefore bake one CAPI identity and LAPI credentials into every image. This matters for step 4.

Step 2 of handbook decision 0041's first implementation: one Debian source package per overlay under `packages/<name>/`, each with its own changelog and version (0.1.0), its manifest beside `debian/`, installed as `/usr/share/keel/overlays/<name>.yaml` exactly as docs/manifest-v1.md gives it. | Package | Depends | | --- | --- | | keel-overlay-installer | inithooks (>= 2.3.6+keel14), confconsole (>= 2.2.3+keel8), keel (>= 0.12.0) | | keel-overlay-wireguard | wireguard-tools (>= 1.0.20210914), keel | | keel-overlay-etcd | etcd-server (>= 3.5.16), keel-overlay-wireguard (its manifest `requires` it), keel | | keel-overlay-crowdsec | crowdsec (>= 1.4.6-10), crowdsec-firewall-bouncer (>= 0.0.25), keel | CrowdSec is trixie's: 0029's open task has not chosen a newer one. ## Unit state etcd and both CrowdSec units end up disabled and stopped. Two parts do it (packages/README.md): 1. The overlay's `postinst`, **on its first installation only**, runs `deb-systemd-helper disable` and, where systemd runs, `deb-systemd-invoke stop`. Later upgrades of the Debian packages keep that state: their snippets re-enable only while `was-enabled` holds, and `deb-systemd-invoke` never starts a disabled unit. Overlay upgrades do nothing, so a state set by `keel apply` stays. 2. A **preset** `disable` (`20-keel-overlay-<name>.preset`). Measured: on a first boot with `/etc/machine-id` set to `uninitialized` and the presets moved aside, all three units were enabled and active. With the presets they stayed disabled. No mask, so `keel apply` can enable them. ## Tests - CI `packages / build`: `packages/build` (dpkg-buildpackage and lintian, failing on any warning; no overrides were needed). - CI `packages / install`: installs the four packages with keel, inithooks and confconsole built from pinned commits in a trixie container, then runs `tests/overlay-install.bats` (13 tests). - Real test on a fresh debootstrap trixie LXC container (ov-test, now destroyed): - image path: a chroot install under policy-rc.d, then the first boot; - live path: `apt install` with systemd running; - the bats suite: 13/13. Final state on the booted container: `etcd`, `crowdsec` and `crowdsec-firewall-bouncer` were all `disabled` and `inactive`, and `keel manifest validate` returned ok for each overlay. As a control, the same `apt install` without the overlays left all three enabled and active. ## For the maintainer - `keel manifest validate` does not run inside the package build. The unit files and hooks it checks belong to the dependencies, so it runs on the installed machine. - The manifests' `screen` paths (`Networking/wireguard.py`, `Security/crowdsec.py`) do not exist in confconsole yet. The existing screen is `Instance/Overlay_network.py`. Validation does not check whether screen files exist. - crowdsec's own postinst registers with CrowdSec's central API at install time and fails without network. An image build would therefore bake one CAPI identity and LAPI credentials into every image. This matters for step 4.