110 lines
3.6 KiB
Markdown
110 lines
3.6 KiB
Markdown
---
|
|
title: Secrets Management
|
|
description: Principles and tool choices for handling secrets safely in self-hosted and engineering environments
|
|
tags:
|
|
- security
|
|
- secrets
|
|
- devops
|
|
category: security
|
|
created: 2026-03-14
|
|
updated: 2026-03-14
|
|
---
|
|
|
|
# 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:
|
|
|
|
```text
|
|
APP_DATABASE_URL=postgres://app:${DB_PASSWORD}@db.internal.example/app
|
|
APP_SMTP_PASSWORD=<provided-at-runtime>
|
|
```
|
|
|
|
Example SOPS-managed YAML structure:
|
|
|
|
```yaml
|
|
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?](https://developer.hashicorp.com/vault/docs/what-is-vault)
|
|
- [HashiCorp Vault documentation](https://developer.hashicorp.com/vault/docs)
|
|
- [SOPS documentation](https://getsops.io/docs/)
|
|
- [The Twelve-Factor App: Config](https://12factor.net/config)
|