Gestión de Secretos Docker Sin Hardcodear Credenciales
Inyecta secretos en contenedores usando Docker secrets, archivos env y gestores externos sin hardcodearlos en imágenes.
Visión General
Hardcodear secretos (contraseñas, API keys, tokens) en imágenes Docker o archivos Compose es un riesgo crítico de seguridad. Las imágenes se comparten, quedan en caché y se inspeccionan — cualquiera que pueda descargar la imagen puede extraer los secretos. Esta receta muestra los patrones idiomáticos para inyectar secretos en contenedores en tiempo de ejecución.
Cuándo Usar
- Necesitas pasar contraseñas de base de datos, API keys o certificados TLS a contenedores
- Quieres evitar subir secretos al control de versiones
- Usas Docker Swarm o Compose en producción
- Necesitas rotar secretos sin reconstruir imágenes
Solución
Docker Swarm secrets (más seguro)
# Crear un secret desde un archivo
echo "my-super-secret-password" | docker secret create db_password -
# Crear un secret desde stdin
printf "AKIAIOSFODNN7EXAMPLE" | docker secret create aws_access_key -
# Listar secrets
docker secret ls
# Usar en un servicio Swarm
docker service create \
--name api \
--secret db_password \
--secret aws_access_key \
-e DB_PASSWORD_FILE=/run/secrets/db_password \
-e AWS_KEY_FILE=/run/secrets/aws_access_key \
my-api:latest
Docker monta los secretos como archivos en /run/secrets/<secret_name>. Nunca se exponen como variables de entorno y se encriptan en tránsito.
Leer secretos desde archivos en tu app
import os
def get_secret(name: str) -> str:
"""Leer un secret desde un archivo (patrón Docker Swarm)."""
file_path = os.environ.get(f"{name}_FILE")
if file_path:
with open(file_path, "r") as f:
return f.read().strip()
# Fallback a env var para dev local
return os.environ.get(name, "")
const fs = require("fs");
function getSecret(name) {
const filePath = process.env[`${name}_FILE`];
if (filePath) {
return fs.readFileSync(filePath, "utf8").trim();
}
return process.env[name] || "";
}
Docker Compose con secrets
# docker-compose.yml
services:
api:
build: .
secrets:
- db_password
- api_key
environment:
- DB_PASSWORD_FILE=/run/secrets/db_password
- API_KEY_FILE=/run/secrets/api_key
db:
image: postgres:16-alpine
environment:
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets:
- db_password
secrets:
db_password:
file: ./secrets/db_password.txt
api_key:
file: ./secrets/api_key.txt
.env file (solo desarrollo)
# .env (NUNCA subir esto al repo — añadir a .gitignore)
DB_PASSWORD=my-dev-password
API_KEY=dev-api-key-12345
JWT_SECRET=dev-jwt-secret
# docker-compose.dev.yml
services:
api:
build: .
env_file:
- .env
environment:
- NODE_ENV=development
# .gitignore
.env
.env.*
secrets/
Gestor de secretos externo (HashiCorp Vault)
El servicio Vault de este ejemplo corre en modo dev — vale para pruebas locales, no para producción. wait-for-vault.sh es un simple bucle de reintento hasta que Vault responde; está incluido en el repo companion.
# docker-compose.yml
services:
api:
build: .
environment:
- VAULT_ADDR=https://vault.internal:8200
- VAULT_TOKEN_FILE=/run/secrets/vault_token
secrets:
- vault_token
command: ["./wait-for-vault.sh", "node", "server.js"]
vault:
image: hashicorp/vault:1.15
ports:
- "8200:8200"
environment:
VAULT_DEV_ROOT_TOKEN_ID: root # solo modo dev — nunca en producción
cap_add:
- IPC_LOCK
secrets:
vault_token:
file: ./secrets/vault_token.txt
import os
import hvac
def get_vault_secret(path: str) -> dict:
"""Obtener un secret desde HashiCorp Vault."""
client = hvac.Client(
url=os.environ["VAULT_ADDR"],
token=get_secret("VAULT_TOKEN")
)
result = client.secrets.kv.v2.read_secret_version(path=path)
return result["data"]["data"]
Secretos durante el build con BuildKit
# Dockerfile
# syntax=docker/dockerfile:1.6
FROM node:20-alpine
# Montar secret durante build solo — no se almacena en capas de imagen
RUN --mount=type=secret,id=npm_token \
npm config set //registry.npmjs.org/:_authToken=$(cat /run/secrets/npm_token) && \
npm ci --omit=dev && \
npm config delete //registry.npmjs.org/:_authToken
# Build con secret de BuildKit
docker build --secret id=npm_token,source=$HOME/.npmrc -t my-api .
Secretos en ejecución con variables de entorno (menos seguro)
# docker-compose.prod.yml
services:
api:
build: .
environment:
- DB_PASSWORD=${DB_PASSWORD} # Desde --env-file o shell
# --env-file mantiene los secretos fuera del historial del shell y de los
# archivos Compose, pero igual llegan al env del contenedor — visibles con docker inspect
docker compose --env-file .env.prod up -d
Explicación
Estas opciones forman un espectro. En el extremo seguro, los Swarm secrets están cifrados en reposo y en tránsito, se montan como archivos de solo lectura en /run/secrets/ y nunca aparecen en docker inspect. Los mounts de BuildKit son igual de seguros pero acotados al build: el archivo existe solo mientras se ejecuta el RUN, así que nada queda en las capas de la imagen. Los gestores externos como Vault o AWS Secrets Manager van un paso más allá — añaden rotación, logs de auditoría y políticas de acceso — a cambio de mantener un servicio extra.
En el extremo arriesgado, los .env guardan secretos en texto plano en disco, lo cual vale para desarrollo y nada más. Las variables de entorno en bruto son la opción más débil: se ven en docker inspect, docker exec env y /proc/<pid>/environ del host, y tienden a filtrarse a logs y volcados de error.
Dos principios lo unen todo:
- Nunca incrustes secretos en capas de imagen — los valores
ENVyARGquedan endocker history. - La convención del sufijo
_FILEle dice a tu app que lea el secreto desde una ruta de archivo en lugar del valor de la variable. Es lo que hace funcionar los secrets de Swarm y Compose sin tocar tu código. - Rota los secretos actualizándolos en el gestor, no reconstruyendo imágenes.
Variantes
| Método | Seguridad | Complejidad | Usar Cuando |
|---|---|---|---|
| Swarm secrets | Alta | Baja | Docker Swarm producción |
| BuildKit mount | Alta | Media | Registros privados durante build |
| Vault / Secrets Manager | Alta | Alta | Enterprise, rotación necesaria |
| .env file | Baja | Baja | Solo desarrollo |
| Variables de entorno | Baja | Baja | Config no sensible |
Gestores de Secretos Externos
Los secrets de Swarm cubren el caso nativo de Docker. Cuando necesitas rotación centralizada, trazas de auditoría o secretos compartidos entre plataformas, mejor usar un gestor externo.
AWS Secrets Manager
import boto3
import json
def get_aws_secret(secret_name: str, region: str = "us-east-1") -> dict:
"""Obtener un secret desde AWS Secrets Manager."""
client = boto3.client("secretsmanager", region_name=region)
response = client.get_secret_value(SecretId=secret_name)
return json.loads(response["SecretString"])
# Uso
db_creds = get_aws_secret("prod/db/credentials")
db_password = db_creds["password"]
# docker-compose.yml con AWS Secrets Manager
services:
api:
build: .
environment:
- AWS_REGION=us-east-1
- AWS_SECRET_NAME=prod/db/credentials
# Credenciales AWS vía IAM role, no env vars
Kubernetes Secrets
Si tus contenedores corren en Kubernetes en lugar de Swarm, la primitiva equivalente es el objeto Secret — montado como volumen de solo lectura o expuesto vía secretKeyRef. Consulta Montar ConfigMaps y Secrets en pods de Kubernetes para la guía completa.
# k8s-secret.yaml
apiVersion: v1
kind: Secret
metadata:
name: db-credentials
type: Opaque
stringData:
password: my-super-secret-password
username: dbadmin
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
template:
spec:
containers:
- name: api
image: my-api:latest
env:
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: db-credentials
key: password
# O montar como archivo
volumeMounts:
- name: secrets
mountPath: /run/secrets
readOnly: true
volumes:
- name: secrets
secret:
secretName: db-credentials
Rotación de Secretos en Swarm
Los secrets en Swarm son inmutables — rotar uno significa crear un secret nuevo y reapuntar el servicio. Este script automatiza el intercambio:
#!/bin/bash
# rotate-secrets.sh
set -e
SECRET_NAME="db_password"
NEW_VALUE=$(openssl rand -base64 32)
# Crear el nuevo secret
echo "$NEW_VALUE" | docker secret create "${SECRET_NAME}_v2" -
# Reapuntar el servicio: quitar el montaje viejo, montar el nuevo con el mismo nombre
docker service update \
--secret-rm "$SECRET_NAME" \
--secret-add "source=${SECRET_NAME}_v2,target=${SECRET_NAME}" \
api
# Esperar el rollout
sleep 30
# Remover secret viejo
docker secret rm "$SECRET_NAME"
echo "Rotación completa para $SECRET_NAME"
Pautas
- Mantén los secretos fuera de Dockerfiles (
ENV,ARG) y archivos Compose — esos valores acaban en el historial de la imagen. - En Swarm, usa
docker secret; para builds, el--mount=type=secretde BuildKit. - Sigue la convención
_FILEpara que tu app lea secretos desde archivos, no desde variables de entorno. - Añade
.envysecrets/al.gitignoreantes de que lleguen a un commit. - Para cualquier cosa de nivel empresarial — rotación, trazas de auditoría, secretos compartidos entre plataformas — usa Vault o AWS Secrets Manager.
- Dale a cada servicio solo los secretos que realmente necesita.
docker secret lsy el log de auditoría de Vault existen por algo: revisa quién tiene acceso.
Errores Comunes
ENVoARGpara secretos. Quedan grabados endocker historyy en cada copia de la imagen.- Subir
.enva Git. Una vez en el historial, cambiar la contraseña no basta — el archivo la sigue filtrando. - Secretos como argumentos de línea de comandos. Aparecen en
docker inspecty en la lista de procesos del host. - Apps que solo leen variables de entorno. Sin la convención
_FILEno puedes usar secrets montados como archivo. - Un secreto para todos los servicios. El menor privilegio también aplica a los secretos.
- No rotar nunca. Un secreto filtrado debería poder reemplazarse en minutos, sin interrupciones.
- Los mismos secretos en dev y prod. Entornos distintos necesitan secretos distintos — una filtración en dev no debería abrir producción.
Tips de Rendimiento
- Guarda en memoria los secretos ya leídos. Evita pedir el mismo secret en cada petición:
import time
_secret_cache = {}
def get_cached_secret(name: str, ttl: int = 300) -> str:
if name in _secret_cache:
cached_time, value = _secret_cache[name]
if time.time() - cached_time < ttl:
return value
value = get_secret(name)
_secret_cache[name] = (time.time(), value)
return value
- Usa el patrón sidecar para obtener secretos. Un contenedor sidecar obtiene los secretos y los escribe en un volumen compartido:
services:
secret-fetcher:
image: vault-sidecar:latest
volumes:
- secrets:/run/secrets
api:
image: my-api:latest
volumes:
- secrets:/run/secrets:ro
volumes:
secrets:
- Agrupa las peticiones de secretos a Vault. Reduce llamadas a la API pidiendo todas las rutas que necesitas en una sola pasada al arrancar:
def get_multiple_secrets(paths: list[str]) -> dict:
results = {}
for path in paths:
results[path] = get_vault_secret(path)
return results
Lectura Adicional
- Manage sensitive data with Docker secrets — documentación oficial de Swarm secrets.
- Build secrets with BuildKit — referencia de
--mount=type=secret. - Secrets top-level element in Compose — secrets basados en archivo sin Swarm.
- Documentación de HashiCorp Vault — gestión externa de secretos con rotación y auditoría.
- Kubernetes Secrets — objetos Secret, volúmenes e inyección por env.
- Repositorio companion — los ejemplos de Compose, BuildKit, Vault y rotación de esta página como archivos ejecutables.
Preguntas frecuentes
¿Son los Docker Compose secrets tan seguros como los Swarm secrets?
No. Los Compose secrets se montan como archivos desde el sistema de archivos del host y no están cifrados en reposo. Los Swarm secrets están cifrados y los gestiona el Swarm manager. Usa Compose secrets para desarrollo y Swarm secrets para producción.
¿Puedo usar Docker secrets sin Swarm?
Sí — Docker Compose admite secrets con la clave secrets y origen file:, que monta el archivo directamente en el contenedor. Es menos seguro que los Swarm secrets, pero sigue siendo mejor que las variables de entorno.
¿Cómo roto secretos sin interrumpir el servicio?
En Swarm, crea un secret nuevo y reapunta el servicio hacia él: docker service update --secret-rm db_password --secret-add source=db_password_v2,target=db_password api. El servicio se reinicia ya montando el secreto nuevo. Para no interrumpir el servicio, usa rolling updates.
¿Por qué debo evitar variables de entorno para secretos?
Las variables de entorno son visibles en docker inspect, docker exec env y /proc/<pid>/environ en el host. Pueden filtrarse a logs y volcados de error. Los secretos basados en archivos son más seguros porque solo el proceso del contenedor puede leerlos.
Recursos Relacionados
Aislamiento de Red Docker y Seguridad Entre Contenedores
Asegura la comunicación entre contenedores con redes Docker personalizadas, segmentación de red y políticas de control de acceso.
RecipeSeguridad en imágenes Docker: escanea, endurece y firma
Escanea imágenes de contenedor en busca de CVEs y secretos con Trivy y Grype. Endurece Dockerfiles, genera SBOMs, firma con Cosign y controla los despliegues.
RecipeSobrescribe la Configuración de Docker Compose por Entorno
Cómo usar archivos override de Docker Compose para configuraciones por entorno: desarrollo, test, staging y producción, con profiles y secrets.
RecipeGestionar Secretos de Aplicaciones de Forma Segura
Cómo almacenar, rotar e inyectar API keys, contraseñas de base de datos y certificados sin hardcodearlos en código fuente o archivos de entorno.
RecipeMontar ConfigMaps y Secrets en Pods de Kubernetes
Cómo montar ConfigMaps y Secrets en pods de Kubernetes usando variables de entorno, volúmenes, volúmenes proyectados y gestores externos de secrets.
DocPlantilla de Rotación de Secretos
Plantilla para programar y rastrear la rotación de claves API, tokens y certificados.