Variables de entorno y secretos en Dockup

Las variables de entorno y los secretos conectan el código de la aplicación con la configuración de producción, pero tienen requisitos diferentes de exposición y ciclo de vida. Una URL base pública de una API puede ser segura en los logs; una contraseña de base de datos o una clave de firma, no. Dockup representa esta diferencia de forma explícita y enmascara los valores de secretos almacenados en la salida de lectura.

Los cambios de configuración también requieren un redeploy. Establecer un valor nuevo actualiza la configuración deseada del servicio, pero el proceso que ya está en ejecución conserva el entorno que recibió al iniciarse.

¿Cuál es la diferencia entre una variable y un secreto?

Ambos valores llegan al proceso de la aplicación como datos de entorno, pero su tratamiento operativo es diferente.

Tipo	Ejemplo	¿Puede aparecer en la salida de lectura?	Tratamiento recomendado
Variable normal	NODE_ENV=production	Sí	Configuración revisable
Variable normal	PUBLIC_API_URL=https://...	Sí	Puede estar en dockup.yaml
Secreto	DATABASE_URL=postgres://...	No se almacena el valor	Comando de secretos o almacén de CI
Secreto	JWT_SIGNING_KEY=...	No se almacena el valor	Rotar y restringir
Secreto	DOCKUP_TOKEN=...	No almacenar nunca como configuración de la aplicación salvo que sea necesario	Autenticación a nivel de proceso

Marca un valor como secreto cuando su exposición pudiera permitir acceso, suplantación, descifrado, firma o movimiento lateral. «El frontend ya lo contiene» indica que el valor es configuración pública, no un secreto.

No incluyas secretos en el control de versiones, dockup.yaml, ejemplos de salida, capturas de pantalla, prompts de agentes ni descripciones de incidencias. Un marcador redactado es más seguro que un token con aspecto realista, porque los ejemplos copiados tienden a convertirse en prácticas de producción.

¿Cómo se establece y consulta la configuración del entorno?

Enumera las claves actuales para un destino exacto:

dockup env list -s production/api --json

La respuesta incluye cada clave, indica si es un secreto y muestra el valor solo cuando no está protegido.

Establece una variable normal:

dockup env set NODE_ENV=production \
  -s production/api \
  --json

Establece un secreto desde el entorno del shell actual:

dockup env set DATABASE_URL="$DATABASE_URL" \
  --secret \
  -s production/api \
  --json

Elimina un valor obsoleto:

dockup env remove OLD_FEATURE_FLAG \
  -s production/api \
  --json

Importa de forma masiva un archivo con formato .env:

dockup env import .env.production \
  -s production/api \
  --json

Usa --secret al importar solo cuando todos los valores importados deban tratarse como secretos. Los archivos mixtos son más difíciles de revisar y suelen fomentar que se clasifique como secreto demasiada configuración inofensiva o que no se clasifiquen credenciales que sí lo son. Sepáralos cuando sea posible.

La interfaz exacta de comandos se mantiene en la referencia de Dockup CLI.

¿Por qué se necesita un redeploy después de cambiar la configuración?

Las variables de entorno se leen cuando se inicia un proceso. Actualizar la configuración de la plataforma no modifica la memoria de un proceso de Node.js, Python, Go u otro proceso que ya esté en ejecución. El servicio debe iniciar un contenedor nuevo con el entorno actualizado.

La secuencia correcta es:

dockup env set FEATURE_FLAG=on \
  -s production/api \
  --json

dockup deploy production/api --wait --json

--wait permite verificar el segundo paso. El tiempo de espera predeterminado es de 900 segundos, el código de salida 0 indica éxito y los errores devuelven un código distinto de cero junto con códigos estructurados.

El proceso blue-green de Dockup sin downtime inicia la versión nueva, aplica el health gate y solo después cambia el tráfico. Así se evita reiniciar el contenedor actual in situ con una configuración no verificada.

Si una rotación de secretos cambia tanto el productor como el consumidor, planifica la compatibilidad. Rotar una contraseña de base de datos antes de que la aplicación reciba el nuevo valor puede provocar una interrupción. Usa un periodo de solapamiento, compatibilidad con claves duales o un cambio ordenado cuando el sistema externo lo permita.

Los mecanismos de deployment se explican en deployments sin downtime.

¿Cómo reduce el enmascarado de secretos el riesgo para los agentes?

Los agentes de coding suelen resumir la salida de los comandos. Una herramienta que devuelve secretos almacenados convierte una solicitud inofensiva como «muestra la configuración actual» en una exposición de credenciales.

Dockup enmascara los valores de los secretos. El agente puede ver que DATABASE_URL existe y está marcado como secreto, pero no puede leer la cadena de conexión almacenada. Puede sustituir el valor cuando el usuario proporciona uno nuevo mediante un entorno seguro.

Esto permite dar una instrucción más segura:

Confirma que existen las claves de secretos necesarias, pero no muestres nunca sus valores. Si es necesario cambiar un valor, léelo únicamente del entorno del proceso y devuelve el nombre de la clave, no el secreto.

El enmascarado de secretos también debe extenderse a los diagnósticos. Evita:

printenv

en una transcripción de un agente, aunque el comando exec de PRO pueda ejecutar comandos de un solo uso en contenedores. Prefiere una comprobación específica de la aplicación que informe de la presencia, la categoría de longitud o el éxito de la conexión sin revelar el valor.

La guía sobre guardrails de producción para agentes de IA cubre conjuntamente los límites de los prompts y las herramientas.

¿Cómo deben rotarse y auditarse los secretos?

La rotación es un cambio de producción controlado, no una edición de texto. Usa esta secuencia:

1. Crea u obtén la credencial nueva en el sistema propietario.
2. Guárdala en el entorno aprobado de CI u operadores.
3. Establece el secreto nuevo en Dockup sin mostrarlo.
4. Haz el deployment con --wait.
5. Verifica el estado y el comportamiento de la aplicación.
6. Revoca la credencial antigua cuando la versión nueva esté activa.
7. Revisa el audit log de Dockup.
8. Registra la fecha y el responsable de la rotación sin registrar el valor.

dockup audit --writes --json

Las evidencias de auditoría deben mostrar que la configuración cambió y que después se realizó un deployment. No deben contener el valor del secreto.

En el caso de las credenciales de bases de datos, ten en cuenta los connection pools. Es posible que las conexiones existentes sigan autenticadas después de la rotación, mientras que las nuevas conexiones usan la contraseña nueva. La verificación debe incluir una conexión nueva, no solo solicitudes atendidas por un pool antiguo.

En el caso de las API keys con permisos, captura el valor generado de forma segura durante su creación. Guárdalo inmediatamente en el sistema de secretos aprobado, limita sus permisos a los necesarios y rótalo sin reproducirlo en la salida del deployment.

¿Qué política de configuración evita el drift?

Define qué valores pertenecen a cada origen:

Origen	Contenido adecuado
Código del repositorio	Valores predeterminados que no dependen del entorno
dockup.yaml	Configuración de deployment normal y revisable
Variables de secretos de Dockup	Credenciales de runtime
Almacén de secretos de CI	Token de deployment y valores inyectados para la rotación
Salida de la base de datos gestionada	Datos de conexión entregados al servicio consumidor
.env local	Valores exclusivos del desarrollador, excluidos de Git

La aplicación de dockup.yaml es aditiva de forma predeterminada. Los valores de entorno normales que no estén en el archivo permanecen hasta que se usa explícitamente --prune, y los secretos nunca se eliminan mediante esa ruta. Revisa dockup.yaml como configuration as code antes de adoptar la limpieza mediante manifests.

Usa nombres de claves coherentes en todos los entornos, pero no des por hecho que los valores son intercambiables. Una clave de staging no debe conceder acceso a producción. Los preview deployments de un proyecto con private networking reciben un usuario de base de datos de solo lectura creado automáticamente para acceder a los datos de producción; no deben heredar credenciales de escritura de forma predeterminada.

Respuesta ante incidentes por filtración de un secreto

Si un secreto aparece en una transcripción, un log, un commit o una captura de pantalla, no basta con enmascararlo después. Trátalo como comprometido:

1. Revócalo o rótalo en el sistema de origen.
2. Actualiza el secreto de Dockup.
3. Haz el redeploy y verifica el resultado.
4. Elimina el material expuesto cuando sea posible.
5. Busca indicios de uso indebido en los logs de auditoría y acceso.
6. Documenta la causa y el cambio preventivo.

Reescribir el historial de Git puede reducir futuros descubrimientos, pero no demuestra que una credencial copiada haya desaparecido. La revocación es la acción decisiva.

Checklist de revisión del entorno

Antes de cada release de producción, verifica que existan las claves necesarias, que las claves secretas estén marcadas como secretas, que no haya ningún secreto committeado, que los valores normales coincidan con el entorno previsto y que el redeploy forme parte del cambio. Después, comprueba el estado y el uptime:

dockup status production/api --json
dockup uptime production/api --hours 24 --json

El monitoring se ejecuta cada minuto e incluye el tiempo de respuesta p95. Un deployment de configuración correcto debe seguir observándose para detectar regresiones en runtime.

Para crear servicios y realizar la configuración inicial, sigue Del repositorio de Git a producción.

Valida la configuración sin revelarla

Las aplicaciones deben fallar claramente cuando falta una clave necesaria, pero los diagnósticos no deben mostrar el valor. Una comprobación de inicio puede informar de una lista como missing: ["DATABASE_URL"] o invalid format: ["PUBLIC_URL"] y después salir con un código distinto de cero.

Para un valor opcional, define el fallback en el código y documenta si es seguro en producción. Los valores predeterminados silenciosos de desarrollo —hosts de bases de datos locales, modos de depuración, CORS permisivo o credenciales de prueba— no deben activarse simplemente porque falte una clave de producción.

Esta validación hace observables las variables de entorno y los secretos sin convertir los logs en un inventario de credenciales.

Gestiona varios servicios y credenciales compartidas de forma deliberada

Copiar un secreto en varios servicios crea una dependencia de rotación. Prefiere credenciales específicas por servicio cuando el sistema externo las admita. Un token de un worker comprometido no debe conceder el mismo acceso que la API pública.

Cuando no se pueda evitar compartir un valor, mantén una lista de responsables y consumidores. Rota todos los consumidores durante una ventana coordinada y verifica las conexiones nuevas después de cada redeploy. No pidas a un agente que «encuentre todos los servicios que probablemente usan esta clave» basándose en la similitud de los nombres; usa un inventario explícito y evidencias de auditoría.

La private networking puede reducir la exposición del tráfico de la base de datos, pero no elimina la necesidad de credenciales. Los hostnames internos controlan la ruta; la autenticación controla quién puede usar la base de datos.

Empieza con un deployment verificable

Clasifica cada clave antes de establecerla, verifica que las lecturas de secretos estén enmascaradas e incluye el redeploy necesario en el mismo cambio revisado.

Empieza gratis en app.dockup.ai. El plan Free cuesta 0 $ al mes, incluye 10 $ de crédito inicial y admite un workspace, tres bases de datos y tres deployments.

FAQ

¿Devuelve Dockup los valores de secretos almacenados?

No. Los valores de los secretos están enmascarados en la salida de lectura. Las claves y los indicadores de secreto siguen visibles para que los operadores puedan verificar que existe la configuración necesaria.

¿Por qué tengo que hacer un redeploy después de cambiar una variable de entorno?

El proceso en ejecución recibió su entorno al iniciarse. Un deployment nuevo crea un contenedor nuevo con los valores actualizados y lo verifica mediante el health gate.

¿Puedo incluir secretos en dockup.yaml?

No. Usa dockup.yaml para la configuración normal y revisable, y utiliza comandos de entorno para secretos o la inyección de secretos de CI para las credenciales.

¿Cómo importo varias variables de entorno?

Usa dockup env import con un archivo con formato .env y el destino exacto del servicio. Usa la opción import --secret solo cuando todos los valores importados sean secretos.

¿Qué debo hacer si un secreto queda expuesto en un log?

Revócalo o rótalo inmediatamente, actualiza el secreto de Dockup, haz el redeploy, investiga los logs de acceso y corrige el proceso que permitió la exposición.