StackPractices
intermediate Por Mathias Paulenko

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 ENV y ARG quedan en docker history.
  • La convención del sufijo _FILE le 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étodoSeguridadComplejidadUsar Cuando
Swarm secretsAltaBajaDocker Swarm producción
BuildKit mountAltaMediaRegistros privados durante build
Vault / Secrets ManagerAltaAltaEnterprise, rotación necesaria
.env fileBajaBajaSolo desarrollo
Variables de entornoBajaBajaConfig no sensible
flowchart diagram: El contenedor necesita un secreto

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=secret de BuildKit.
  • Sigue la convención _FILE para que tu app lea secretos desde archivos, no desde variables de entorno.
  • Añade .env y secrets/ al .gitignore antes 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 ls y el log de auditoría de Vault existen por algo: revisa quién tiene acceso.

Errores Comunes

  • ENV o ARG para secretos. Quedan grabados en docker history y en cada copia de la imagen.
  • Subir .env a 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 inspect y en la lista de procesos del host.
  • Apps que solo leen variables de entorno. Sin la convención _FILE no 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

  1. 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
  1. 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:
  1. 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

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.