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

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.

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.