vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(#2862): document the snapshot store, drop the dedicated option

Browse source 
mara: the option was the wrong shape for the concern. "this host runs
nothing else" is a deployment expectation, not something a module
should assert about its own host — and asserting it made co-location
look like a config toggle rather than what it is.

Replaced with docs/snapshot-store.md, which the module had no docs
page at all before: enabling it, why the mesh is the authentication
(cryptokey routing already binds source address to pubkey, so certs
would authenticate the same fact twice and add an expiry), why the
destination is keyed per agent (a per-hive prefix splits an agent's
chain the first time it migrates), what the sender may and may not
choose, why the firewall rule is interface-scoped, what a snapshot
does and does not contain, and what the pull side still needs.

The dedicated-host expectation is stated there as an operational
assumption with its own failure mode — true on day one, quietly false
the day someone notices the box has spare disk — rather than as an
assertion someone flips to false to make the build proceed.

Linked from CLAUDE.md's reading paths.
This commit is contained in:
atlas 2026-07-31 18:34:34 +02:00 • committed by mara
commit c051cd9717
3 changed files with 193 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

36
nix/host-modules/hive-snapshot-store.nix
View file

@ -16,7 +16,8 @@
# Confinement is a property of the DEPLOYMENT, not of this unit: in a
# real swarm the store is its own small VM (the machine is the
# boundary); in the all-local case it's a container on the c0re host.
# The module therefore hardcodes neither --- see `dedicated` below.
# The module hardcodes neither. docs/snapshot-store.md covers what the
# deployment is expected to provide.
{
pkgs,
lib,
@ -129,23 +130,6 @@ in
'';
};
dedicated = lib.mkOption {
type = lib.types.bool;
default = true;
description = ''
Assert that this host runs no other hyperhive role. The store
aggregates every agent's state from every hive in the swarm, so
the intended deployment is a dedicated machine (or a container
in the all-local case) where the machine itself is the security
boundary.
That assumption is true on day one and silently false the day
someone notices the box has spare disk. This option makes it a
thing the build checks rather than a thing the deployer
remembers. Set to `false` to co-locate deliberately --- the
point is that it becomes a decision, not an accident.
'';
};
};
config = lib.mkIf cfg.enable {
@ -170,20 +154,6 @@ in
fall back to a wildcard.
'';
}
{
assertion = !cfg.dedicated || !config.services.hyperhive.c0re.enable;
message = ''
services.hyperhive.snapshotStore is enabled alongside
services.hyperhive.c0re on the same host. The store holds
every agent's state from every hive, so it is meant to run on
a machine of its own where the machine is the boundary.
If the co-location is deliberate (the all-local single-host
deployment, where the store runs as a container), set
services.hyperhive.snapshotStore.dedicated = false to record
that decision explicitly.
'';
}
];
# The store root must exist before the first connection arrives ---
@ -231,7 +201,7 @@ in
# nature. The hardening below is defence in depth and NOT a
# boundary: a process holding CAP_SYS_ADMIN can call mount(2) and
# undo the namespace these directives set up. The real boundary is
# the deployment (dedicated host / container) --- see `dedicated`.
# the deployment --- see docs/snapshot-store.md.
systemd.services."hive-snapshot-store@" = {
description = "hyperhive swarm snapshot store receiver";
after = [ "hive-snapshot-store.socket" ];