Recipe reference

Every recipe in this repository, what it does, and which ones need a credential. Use it to find the command; the pages linked from each section explain the procedure around it.

Everything an operator runs goes through just. The root justfile is only a set of mod declarations. The real definitions are one file per namespace under .just/.

just help          # every recipe, namespace by namespace
just ks help       # one namespace's recipes

Arguments are positional: just ks logs media sonarr. A recipe documented as <x> requires that argument, and [<x>] takes an optional one.

ops, the operator machine

just itself is the one thing ops deps cannot install for you. It has to be there to run the recipe. sudo dnf install just first.

Every tool that is only a binary on PATH is pinned in mise.toml and installed with mise install; the dnf packages, their daemons and the uv tools are the rest of the recipe. The binaries land in ~/.local/share/mise/shims, which Cold bootstrap covers putting on PATH.

The tf init inside ops setup skips any module with a backend.tf while config/sops/ops.sops.yaml does not exist yet, and says so. That is the cold-bootstrap case: setup runs at step 3, the encrypted files land at step 5. Run just tf init <module> for it afterwards.

ops mesh only reports: netbird up is an interactive SSO login, and the admin group it has to land in is filled from the dashboard, not from tofu/netbird. ops deps installs the client either way.

ops age-key is not part of ops setup: it mints key material, so it is deliberately explicit. It prints the public recipient for .sops.yaml and leaves the private key in a temporary file for you to store in Proton Pass and shred.

ops sops takes either name, foo.sops.yaml or foo.sops.yaml.example, and always edits the real file. If it does not exist yet, the template is copied, opened, and encrypted on save. It fails closed: an aborted edit or a failed encrypt deletes the plaintext rather than leaving it at a *.sops.* path.

just ops sops                                 # what is still missing
just ops sops config/sops/ops.sops.yaml           # create it, or edit it

ops rekey re-seals every *.sops.* file to the recipients .sops.yaml currently names, and prints the resulting diff. Run it after editing .sops.yaml, since a rotation that changes the recipients there leaves the files themselves sealed to the old ones.

ans, hosts

setup and k8s both depend on render-secrets, so you rarely run it by hand.

setup is variadic after the hostname, so playbooks/setup.yml’s tags are reachable. Pass '' as the hostname to mean all of them:

just ans setup brokkr --tags podman        # one node's container plane
just ans setup '' --skip-tags podman       # the fleet's base layers only
just ans setup kenaz --tags mesh           # re-converge one node's mesh join

fx, Flux

ks, the cluster

Every ks, fx and bak recipe points KUBECONFIG at ansible/.generated/kubeconfig itself, so you do not need it in your environment. Re-converging the cluster is just ans k8s.

bak, backups

A size of 0 in bak snapshots is a run that copied nothing, which is otherwise indistinguishable from one that worked. bak ls shows what such a snapshot does and does not hold; bak logs is where the file and byte counts for a single run are.

bak restore deletes data. It prints which PVCs it will destroy and which it will leave alone, and requires you to type the namespace back before it proceeds. Only local-path PVCs are ever wiped, so the rclone-backed classes are never touched. It is deliberately not reachable from any other recipe, and restores the newest snapshot of each volume. Backup and recovery covers what it does behind that prompt, and why a hand-written Restore is not equivalent.

bak restore postgres does nothing useful: that namespace’s data is a pg_dumpall object rather than a volume snapshot, and K8up cannot restore anything it took from stdin. The two pg-* recipes are its equivalent, going through restic dump and split so the reading half is safe to run on its own. bak pg-restore prompts the same way, then suspends the tenants’ Flux Kustomizations, scales them to zero, replays the dump, and resumes them.

tf, the cloud plane

plan, apply and adopt need a Proton Pass session and the GPG smartcard plugged in, and so does init for a module that ships a backend.tf, because initialising a remote backend authenticates against it. There is no editing secrets from here. Secret values live in Proton Pass, and each module’s tofu.<module> section of config/sops/ops.sops.yaml holds only identifying values and the pass:// references that point at them. Edit it with just ops sops.

docs, this book