Docker Secrets en producción: proteger credenciales en VPS

El riesgo real: tus secretos viajan dentro de tus imágenes

5 errores de configuración que exponen tus secretos

• Variables de entorno en texto plano en docker-compose.yml — environment: DB_PASSWORD: hunter2 es legible por cualquiera que acceda al archivo o la imagen.
• Archivo .env confirmado en el repositorio — un error en .gitignore y el secreto queda en el historial de git para siempre (incluso después de git rm, accesible vía git log).
• ARG pasado en el build y copiado en la imagen — los ARG quedan grabados en los metadatos de la capa de imagen y son legibles con docker history.
• Secretos en los logs — una aplicación que registra sus variables de entorno al arrancar (Spring Boot, Rails en modo debug, algunos servidores Node) imprime las credenciales en docker logs.
• Volúmenes bind-mount en /root o el directorio del proyecto — un archivo .env montado desde el host sigue siendo accesible para cualquier proceso del contenedor con privilegios root.

Requisitos previos

Método 1 — Docker Secrets en Compose sin Swarm (paso a paso)

1. 01

   Verificar la versión de Compose

   Docker Secrets funciona sin Swarm desde Docker Compose v2.24.0 (lanzado el 11 de enero de 2024). Verifica:

   docker compose version
   # Docker Compose version v2.27.1

   Si estás por debajo de v2.24, actualiza Compose antes de continuar (apt-get install docker-compose-plugin en Debian/Ubuntu).

2. 02

   Crear los archivos de secretos

   Los secretos de Docker Compose en modo no-Swarm son archivos en el host, montados como tmpfs dentro del contenedor. Créalos fuera del directorio del proyecto:

   mkdir -p /etc/myapp/secrets
   echo -n 'contraseña-db-segura' > /etc/myapp/secrets/db_password
   echo -n 'clave-api-stripe-xxxxx' > /etc/myapp/secrets/stripe_key
   chmod 600 /etc/myapp/secrets/*
   chown root:root /etc/myapp/secrets/*

   La opción -n de echo evita el salto de línea final — algunas aplicaciones leen el archivo completo incluido el salto de línea, lo que invalida la clave.

3. 03

   Declarar los secretos en docker-compose.yml

   services:
     app:
       image: miapp:latest
       secrets:
         - db_password
         - stripe_key
       environment:
         # indicamos la RUTA, no el valor
         DB_PASSWORD_FILE: /run/secrets/db_password
         STRIPE_KEY_FILE: /run/secrets/stripe_key
   
   secrets:
     db_password:
       file: /etc/myapp/secrets/db_password
     stripe_key:
       file: /etc/myapp/secrets/stripe_key

   Observa el uso de la convención *_FILE: tu aplicación debe leer la variable DB_PASSWORD_FILE, abrir el archivo indicado y leer su contenido. Las imágenes oficiales de PostgreSQL, MySQL, Redis y la mayoría de imágenes Bitnami soportan esta convención de forma nativa — consulta la documentación de tu imagen.

4. 04

   Verificar el montaje dentro del contenedor

   Tras docker compose up -d, inspecciona el montaje:

   docker compose exec app ls -la /run/secrets/
   # -r-------- 1 root root 20 Sep 20 08:12 db_password
   # -r-------- 1 root root 28 Sep 20 08:12 stripe_key
   
   docker inspect miapp_app_1 | grep -A5 Mounts
   # "Type": "tmpfs",
   # "Destination": "/run/secrets",

   El tipo de montaje es tmpfs: el contenido vive en RAM, nunca escrito en el disco del contenedor. Desaparece al detener el contenedor.

5. 05

   Lo que Docker Secrets NO hace — entiéndelo antes de continuar

   Docker Secrets no es una caja fuerte hermética. Lo que no protege:

   - El archivo fuente (/etc/myapp/secrets/db_password) permanece en el disco del host en texto plano — root en la VM siempre tiene acceso.
   - Cualquier proceso del contenedor (PID 1 o un subproceso lanzado por la app) puede leer /run/secrets/*.
   - Una variable de entorno derivada del secreto (DB_PASSWORD=$(cat /run/secrets/db_password) en un entrypoint) vuelve a poner el secreto en el entorno, visible vía docker inspect.

   Docker Secrets protege contra fugas en capas de imagen y en docker-compose.yml. No protege contra un proceso comprometido dentro del contenedor.

Docker Secrets vs .env.vault vs SOPS — qué método para qué contexto

Desplace la tabla

Configuración complementaria: rotación y cifrado en reposo

# 1. Escribir el nuevo valor
echo -n 'nueva-contraseña' > /etc/myapp/secrets/db_password
# 2. Reiniciar el servicio afectado
docker compose restart app

# Generar una clave age
age-keygen -o /root/.config/sops/age/keys.txt
# Cifrar el archivo de secreto
sops --encrypt --age $(age-keygen -y /root/.config/sops/age/keys.txt) \
  /etc/myapp/secrets/db_password > /etc/myapp/secrets/db_password.enc
# En el script de arranque, descifrar antes de docker compose up
sops --decrypt /etc/myapp/secrets/db_password.enc > /etc/myapp/secrets/db_password

Resolución de problemas — errores comunes

Tus secretos bajo control — y los siguientes pasos