---
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)