home-network-k3s-impl/bootstrap/sops/age-key-secret.md

Installing the age private key as the sops-age Secret (out-of-band)

Phase 1, T-1.4 · ADR-0007 (SOPS+age) · R-SEC-01 · spec docs/07 "Secrets management".

This is the one sanctioned non-GitOps action in the secrets model (ADR-0007 Consequences, docs/07): the age private key is bootstrapped into the cluster out-of-band as a Kubernetes Secret that Flux's kustomize-controller reads to decrypt SOPS at reconcile time. The key is never committed (.gitignore guards age.key, *.key); no key material appears in git, PRs, or logs (AGENTS.md §5).

AUTHOR-ONLY runbook. Nothing here has been executed. The operator runs these steps once, after the age key exists (age-keygen.sh) and Flux controllers are installed (../flux/bootstrap.sh).

Prerequisites

1. age-keygen.sh has been run → private key at ~/.config/sops/age/keys.txt (outside the repo).
2. The flux-system namespace exists (created by flux install / flux bootstrap).
3. kubectl context points at the dev cluster.

Create the Secret (command template — NOT run)

Flux discovers age keys inside the sops-age Secret by the .agekey filename suffix, so the data key MUST end in .agekey:

# Reads the private key file and stores it under data key "age.agekey".
cat ~/.config/sops/age/keys.txt | kubectl create secret generic sops-age \
  --namespace=flux-system \
  --from-file=age.agekey=/dev/stdin

Idempotent re-apply variant (avoids "already exists" on re-runs):

kubectl create secret generic sops-age \
  --namespace=flux-system \
  --from-file=age.agekey="$HOME/.config/sops/age/keys.txt" \
  --dry-run=client -o yaml | kubectl apply -f -

• Secret name sops-age and namespace flux-system MUST match the decryption.secretRef.name on the platform/apps Flux Kustomizations (see ../flux/patches/).
• This Secret is created imperatively and is NOT in git — it holds the private key, so it must never be committed, encrypted or otherwise. (It is the trust anchor, not a managed resource.)

Verify (read-only — NOT run)

kubectl -n flux-system get secret sops-age                       # exists
kubectl -n flux-system get secret sops-age \
  -o jsonpath='{.data.age\.agekey}' | base64 -d | age-keygen -y  # prints PUBLIC recipient only

The printed public recipient MUST equal the age: value in .sops.yaml. (This command derives the public key from the private key; it never exposes the private key.)

Rotation (documented per ADR-0007 "Key custody/rotation")

1. Generate a NEW key with age-keygen.sh (to a fresh path; the script refuses to clobber).
2. Add the new public recipient to .sops.yaml alongside the old (multi-recipient), then sops updatekeys every encrypted file so both keys can decrypt.
3. Update the sops-age Secret to contain both private keys (two *.agekey data entries) so Flux can still decrypt existing files during the transition.
4. Once all files are re-encrypted to the new recipient, remove the old recipient from .sops.yaml, sops updatekeys again, and drop the old key from the Secret.

Key custody / DR (ADR-0007: "losing it blocks decryption")

• The age private key is DR-critical: without it Flux cannot decrypt any committed Secret.
• Keep an off-cluster backup of keys.txt in the operator's password manager / offline store (NOT in this repo, NOT on the cluster it protects). This mirrors the off-cluster-mirror posture for Gitea (docs/05 "Circularity & DR").