Secrets Management

SOPS + age

SOPS with age encryption is the standard across all projects. A single .sops.yaml at the repo root defines path-based encryption rules.

File Naming

.sops.yaml path-based rules match specific filename patterns (e.g., **/*secret*.yaml)
Non-secret files must NOT contain secret in their name, or the pre-commit hook will encrypt them
KSOPS generator files should be named ksops-generator.yaml, not secret-generator.yaml

encrypted_regex Gotcha

When using encrypted_regex for selective field encryption (e.g., Ansible group_vars), variable names must contain a keyword that matches the regex (e.g., password|private_key|api_key|secret|token). Arbitrary key names are silently left unencrypted.

SOPS Vars Plugin

Each Ansible project needs vars_plugins_enabled = host_group_vars,community.sops.sops in ansible.cfg. Files in group_vars/ must be named after a group (e.g., all.sops.yaml), not arbitrary names.

Interactive Editor Pitfalls

sops <file> opens an interactive editor — fails in non-interactive sessions
sops -e /tmp/file fails when the temp path doesn't match .sops.yaml rules
Multiple sops --set calls can corrupt files — use the interactive editor for multi-field edits

Credential Handling

Never pass secrets via command-line arguments — visible in ps output
Use @file references, environment variables sourced at runtime, or stdin
For Ansible, use temp files with trap rm cleanup: -e "@${tmpfile}"
Read secrets at execution time and use them ephemerally — never cache or persist values
Reference the existence of a secret file in docs, never its contents

Bootstrap Secrets

Some secrets are chicken-and-egg (e.g., the age decryption key for ArgoCD's KSOPS). These must be created manually as a bootstrap step and documented clearly.

Credential Lifecycle Management

Track credential expiry dates. OAuth client secrets, API tokens, and certificates have expiry dates that can cause silent failures. Document expiry dates when creating credentials.
Set alerts before expiry. For long-lived credentials (e.g., 720-day OAuth client secrets), set calendar reminders or automated monitoring alerts well before they expire.
Rotation plan. Know the rotation procedure before you need it — some credential types (e.g., Azure app registrations) require coordinated updates across multiple systems.

Multi-Field Secret Files

Secret files that contain multiple fields (e.g., repo URL, token, username) cannot be used as bare values. Consumers must parse individual fields (e.g., grep + awk or structured YAML/JSON parsing).

The multi-field format is preferable because it's self-documenting — all related credentials live together. But any automation reading the file needs extraction logic, not just cat.

Generating Secrets with gen-secret

Use the gen-secret script (from small-scripts, symlinked to ~/sbin/gen-secret) to generate cryptographically random strings that are safe for bash, YAML, and JSON without escaping.

Workflow: Generate + SOPS Encrypt

Generate the secret value — use gen-secret with an appropriate length:

SESSION_SECRET=$(gen-secret 48)    # 48-char session key
API_KEY=$(gen-secret 20)           # 20-char access key
API_SECRET=$(gen-secret 40)        # 40-char secret key

Write plaintext YAML to the target path — the file must be at the path matched by .sops.yaml rules (e.g., **/*secret*.yaml):

cat > path/to/my-secret.sops.yaml <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: my-credentials
  namespace: my-namespace
type: Opaque
stringData:
  SESSION_SECRET: ${SESSION_SECRET}
  API_KEY: ${API_KEY}
EOF

Encrypt in-place — SOPS reads .sops.yaml to determine the encryption key and regex:
```
sops -e -i path/to/my-secret.sops.yaml
```
Verify — decrypt and confirm no placeholders remain:
```
sops -d path/to/my-secret.sops.yaml
```

Key Points

Always encrypt at the target path. sops -e /tmp/file.yaml fails because /tmp/ doesn't match .sops.yaml path rules. Write the plaintext to the final location, then sops -e -i in-place.
Use shell variables, not files, for ephemeral secrets. Generate into a variable (SECRET=$(gen-secret 48)), interpolate into the YAML, then encrypt. The plaintext never touches disk as a standalone file.
Appropriate lengths: 32 chars is the default and sufficient for most use cases. Use 48+ for session secrets, 20 for access key IDs, 40 for secret keys (matching common API patterns).
For credentials from external systems (e.g., Gitea API tokens, registry passwords), read them from ~/dev/claude/secrets/ at point of use — don't generate random replacements for values that must match an external system.
Clean up temp files if you write plaintext to a temporary location. Use trap cleanup or rm -f after encryption.

Replacing Placeholder Secrets

When SOPS-encrypted files contain placeholder values (e.g., PLACEHOLDER_SESSION_SECRET):

Decrypt: sops -d secret.sops.yaml — inspect current values
Write the corrected plaintext YAML to the same path (overwriting the encrypted file)
Re-encrypt: sops -e -i secret.sops.yaml
Verify: sops -d secret.sops.yaml | grep -c PLACEHOLDER — should return 0

Backup Considerations

Backup plans must include encryption keys (age private keys, etc.) so that encrypted data in Git repos remains recoverable.

5.5 KiB Raw Blame History