Secrets Management

Introduction

Secrets management is the practice of storing, distributing, rotating, and auditing sensitive values such as API tokens, database passwords, SSH private keys, and certificate material.

Purpose

Good secrets management helps you:

• Keep credentials out of Git and chat logs
• Reduce accidental disclosure in deployment pipelines
• Rotate credentials without rewriting every system by hand
• Apply least privilege to applications and operators

Architecture Overview

A practical secrets strategy distinguishes between:

• Human secrets: admin credentials, recovery codes, hardware token backups
• Machine secrets: database passwords, API tokens, TLS private keys
• Dynamic secrets: short-lived credentials issued on demand
• Encrypted configuration: secrets stored in version control in encrypted form

Common tooling patterns:

• Vault for centrally managed and dynamic secrets
• SOPS for Git-managed encrypted secret files
• Platform-native secret stores for specific runtimes

Operational Model

Centralized secret service

A service such as Vault handles storage, access policy, audit logging, and secret issuance. This is most useful when you need rotation, leasing, or many consumers across multiple environments.

Encrypted files in Git

Tools such as SOPS allow you to keep encrypted configuration alongside deployment code. This is useful for small teams and GitOps-style workflows, as long as decryption keys are managed carefully.

Runtime injection

Applications should receive secrets at runtime through a controlled delivery path rather than through hard-coded values inside images or repositories.

Configuration Example

Example placeholder environment file layout:

APP_DATABASE_URL=postgres://app:${DB_PASSWORD}@db.internal.example/app
APP_SMTP_PASSWORD=<provided-at-runtime>

Example SOPS-managed YAML structure:

database:
  user: app
  password: ENC[AES256_GCM,data:...,type:str]
smtp:
  password: ENC[AES256_GCM,data:...,type:str]

Troubleshooting Tips

Secret appears in logs or shell history

• Remove it from the source immediately if exposure is ongoing
• Rotate the credential instead of assuming it stayed private
• Review the delivery path that leaked it

Encrypted config exists but deployments still fail

• Verify the deployment environment has access to the correct decryption keys
• Check whether placeholders or environment interpolation are incomplete
• Confirm the application reads secrets from the documented location

Secret sprawl grows over time

• Inventory where secrets live and who owns them
• Standardize naming and rotation intervals
• Remove stale credentials from old hosts and repos

Best Practices

• Never commit plaintext secrets to Git
• Prefer short-lived or scoped credentials where the platform supports them
• Separate secret storage from application images
• Rotate credentials after incidents, staff changes, and major platform migrations
• Document ownership, rotation method, and recovery path for every critical secret

References

• HashiCorp Vault: What is Vault?
• HashiCorp Vault documentation
• SOPS documentation
• The Twelve-Factor App: Config