railiance-apps/docs/operator-setup.md

Operator Setup

Run these checks before deploying any S5 workload:

make check-tools

When the app release work touches encrypted SOPS files, also verify the operator age identity against the encrypted file being changed:

SOPS_SENTINEL=<encrypted-file> make check-sops

Required Tools

• kubectl
• helm
• sops
• python3
• curl

Install the CNPG plugin for better database diagnostics:

kubectl krew install cnpg

make check-tools fails when required tools are missing and warns when kubectl cnpg is unavailable. The Makefile status targets fall back to plain Kubernetes resources, but the plugin output is the preferred view for primary/replica health and backup state.

Production Cluster Kubeconfig

S5 production app releases belong on Railiance01. CoulombCore may still host bootstrap or prerelease services, so do not rely on the workstation's ambient kubectl context for production app deploys.

Name	IP	Role
Railiance01	92.205.62.239	Production k3s; deploy S5 apps here
CoulombCore	92.205.130.254	Bootstrap / prerelease only

Hostname	Production DNS A	Notes
reuse.coulomb.social	92.205.62.239	Production reuse-surface hub
hub.coulomb.social	92.205.62.239	Target production inter-hub host; bootstrap may still point at CoulombCore until cutover

The production Makefile targets default to:

~/.kube/config-hosteurope

Restore it from Railiance01 when missing:

ssh tegwick@92.205.62.239 'sudo cat /etc/rancher/k3s/k3s.yaml' \
  | sed 's|127.0.0.1|92.205.62.239|' > ~/.kube/config-hosteurope
chmod 600 ~/.kube/config-hosteurope
export KUBECONFIG=~/.kube/config-hosteurope

The app-specific targets also accept explicit overrides:

REUSE_KUBECONFIG=~/.kube/config-hosteurope make reuse-status
INTER_HUB_KUBECONFIG=~/.kube/config-hosteurope make inter-hub-status

SOPS Age Key Bootstrap

SOPS-encrypted values used by app release work expect an age identity at:

~/.config/sops/age/keys.txt

Bootstrap procedure:

1. Receive the operator age identity through an out-of-band channel.
2. Create the directory with owner-only permissions:

   mkdir -p ~/.config/sops/age
   chmod 700 ~/.config/sops ~/.config/sops/age
   

3. Write the identity to ~/.config/sops/age/keys.txt.
4. Restrict the file:

   chmod 600 ~/.config/sops/age/keys.txt
   

5. Verify decryption against the encrypted file being changed:

   SOPS_SENTINEL=<encrypted-file> make check-sops
   

Do not commit age identities, decrypted values, or copied SOPS plaintext to this repo.

Rotation

To rotate access, add the new recipient to the relevant SOPS files, re-encrypt, verify with both old and new operators, then remove the old recipient in a separate change. Keep at least one known-good recovery operator key available during the transition.