Configuración como código con dockup.yaml: planificar y aplicar de forma segura

dockup.yaml convierte la configuración de los servicios en un artefacto del repositorio que se puede revisar. En lugar de depender del estado del dashboard, que alguien debe recordar, el equipo puede declarar en un único archivo la rama, el puerto, los comandos de build y start, las comprobaciones de salud, los valores de entorno ordinarios y los dominios.

Dockup separa la inspección de la mutación. dockup plan muestra la diferencia entre el manifest y el servicio activo sin modificar nada. dockup up aplica los cambios declarados. La eliminación sigue siendo opcional mediante --prune.

¿Qué se puede declarar en dockup.yaml?

Un manifest de servicio puede contener la configuración de producción que se beneficia de una revisión de código:

service:
  branch: main
  port: 3000
  dockerfile: Dockerfile
  build: npm run build
  start: npm start
  healthcheck:
    path: /health
    interval: 5
    timeout: 3
    retries: 5
  env:
    NODE_ENV: production
    API_URL: https://api.example.com
  domains:
    - api.example.com
    - { domain: admin.example.com, port: 4000 }

De forma predeterminada, el archivo se coloca en la raíz del repositorio. Puedes seleccionar una ruta diferente con --file.

No coloques secretos en el mapping env. El manifest se confirma, revisa, almacena en caché y copia igual que otros archivos fuente. Usa dockup env set --secret o un proceso aprobado de inyección de secretos para las credenciales.

El consumo de CPU, RAM y disco sigue basándose en el uso y se mide por minuto respecto al saldo del plan; el manifest debe describir la configuración del servicio, no supuestos de facturación.

¿Cómo muestra dockup plan la deriva de configuración?

Ejecuta una comparación de solo lectura antes de cada aplicación:

dockup plan production/api --json

El resultado contiene cambios con aspectos, campos, valores anteriores, valores nuevos y acciones. Un plan puede mostrar que la rama ha cambiado, que una ruta de healthcheck es diferente, que se añadirá un dominio o que un valor de entorno sin secretos ha sufrido drift.

Un plan resulta útil en cinco situaciones:

Situación	Qué revela el plan
Un pull request modifica el manifest	El efecto previsto en producción antes del merge
Se edita el dashboard manualmente	La deriva respecto al origen del repositorio
Un agente propone una actualización	Los campos exactos que el agente pretende modificar
Recuperación de un incidente	Si el estado activo ya difiere de la configuración conocida
Configuración multi-entorno	Las diferencias entre los manifests de producción y staging

La planificación no bloquea el servicio. El estado activo puede cambiar entre el plan y la aplicación, por lo que los workflows de alto riesgo deben mantener la revisión y up lo más cerca posible y revisar el resultado de la aplicación.

Un agente de coding debería devolver el JSON del plan o un resumen conciso campo por campo. “La configuración parece correcta” no es un artefacto de revisión suficiente.

¿Cómo aplica dockup up la configuración como código?

Aplica el manifest predeterminado:

dockup up production/api --json

Aplica la configuración y, después, activa un deployment:

dockup up production/api --deploy --json

Usa otro archivo para staging:

dockup plan production/api \
  --file dockup.production.yaml \
  --json

dockup up production/api \
  --file dockup.production.yaml \
  --deploy \
  --json

El resultado de la aplicación indica qué cambios se aplicaron o se omitieron y puede incluir el ID del deployment cuando se usa --deploy. El deployment posterior debe seguir utilizando, cuando corresponda, la verificación del estado terminal; una mutación de configuración y un release saludable en producción son resultados independientes.

Los valores secretos permanecen fuera del manifest. Configúralos mediante el workflow de entorno de secretos antes de aplicar la configuración; después, haz el deploy y verifica el contenedor resultante sin mostrar el valor almacenado.

¿Por qué la configuración como código es aditiva de forma predeterminada?

La interpretación más segura de un manifest incompleto es “gestionar estos valores declarados”, no “eliminar todo lo demás”. Por eso, Dockup deja sin cambios las variables de entorno y los dominios que no aparecen en el archivo.

Esto es importante durante una adopción gradual. Es posible que un servicio ya tenga variables secretas, dominios operativos o configuración temporal que aún no se haya modelado. El primer up no debería eliminarlos.

Las garantías de seguridad son específicas:

• dockup up no elimina servicios, bases de datos ni volúmenes.
• Las variables secretas existentes no se sobrescriben con valores ordinarios del manifest.
• Las variables secretas no se eliminan mediante prune.
• La aplicación automática del manifest durante el deploy es aditiva.
• Un manifest no válido no se convierte silenciosamente en una limpieza destructiva.

El comportamiento aditivo hace que dockup.yaml sea adecuado para un workflow de GitOps incremental. También significa que el manifest no es automáticamente un inventario completo, a menos que el equipo adopte deliberadamente el pruning para los campos compatibles.

¿Cómo se debe revisar --prune?

--prune elimina los valores de entorno sin secretos y los dominios compatibles que no aparecen en el manifest:

dockup plan production/api --json
dockup up production/api --prune --json

Trata el flag como una solicitud destructiva. Revisa el plan, indica el objetivo exacto y obtén aprobación humana cuando un agente opere en producción.

La operación no incluye secretos, servicios, bases de datos ni volúmenes. Esos recursos tienen su propio ciclo de vida y sus propios procesos de confirmación. Esta separación evita que una pequeña modificación del manifest se convierta en una eliminación amplia de infraestructura.

Un registro de aprobación útil dice: “Aplicar dockup.yaml a production/api y podar las dos variables sin secretos y el dominio que aparecen en el plan X”. No debe ser un permiso general reutilizable para planes futuros.

El modelo general de confirmación se explica en guardrails de producción para agentes de IA.

¿Cómo pueden los equipos operar un workflow de GitOps con dockup.yaml?

Mantén el workflow sencillo:

1. Un desarrollador o agente edita dockup.yaml.
2. CI valida la sintaxis de YAML y las pruebas de la aplicación.
3. Se ejecuta un dockup plan de solo lectura contra el objetivo previsto.
4. El pull request muestra tanto el diff del código fuente como el plan del estado activo.
5. Un revisor aprueba el cambio.
6. dockup up --deploy lo aplica.
7. El deploy espera a que finalice correctamente.
8. Se conservan el estado, los logs y las evidencias de auditoría.

El manifest no debe convertirse en un cajón de sastre. Mantén la configuración de negocio de la aplicación dentro de la propia aplicación cuando corresponda. Usa dockup.yaml para los ajustes de deployment y runtime que pertenecen al límite del servicio.

Los archivos específicos por entorno pueden ser más claros que un único archivo con una capa de templating no documentada. Por ejemplo, usa dockup.staging.yaml y dockup.production.yaml, y pasa explícitamente el archivo previsto.

Un preview de una rama es un deployment aislado, mientras que la configuración de producción sigue siendo un objetivo de revisión independiente. En proyectos con networking privado, los previews pueden unirse a la red del proyecto y recibir acceso de solo lectura a la base de datos sin modificar el manifest de producción.

Consulta la guía de variables de entorno y secretos para gestionar credenciales y deployments sin downtime para el readiness gate.

Playbook para responder al drift

Cuando dockup plan informa de cambios inesperados en el entorno activo, no los sobrescribas automáticamente. Determina si la edición del dashboard fue una corrección de emergencia, un cambio no autorizado o un ajuste previsto que nunca se confirmó en el repositorio.

Después, elige un único source of truth:

• Actualiza el manifest para conservar el valor activo previsto.
• Aplica el manifest para restaurar el valor revisado.
• Documenta una excepción temporal con un responsable y una fecha de caducidad.
• Investiga el audit log cuando se desconozca el origen.

dockup audit --writes --json

Este proceso mantiene dockup.yaml como fuente de autoridad sin borrar el contexto del incidente.

La referencia de Dockup CLI es la fuente de información sobre los campos actuales del manifest y las opciones de plan/up.

Diseña cambios de manifest fáciles de revisar

Mantén cada cambio lo bastante acotado para que el plan tenga un único objetivo claro. Combinar en un pull request un cambio de rama, un aumento de recursos, un dominio nuevo, una reescritura del healthcheck y una limpieza del entorno dificulta tanto la revisión como el rollback.

Usa comentarios para explicar valores inusuales, pero no dupliques la documentación operativa dentro del archivo. Enlaza el runbook del repositorio con el target del servicio, la semántica del healthcheck y la política de aprobación. El manifest debe seguir siendo YAML válido que se pueda analizar sin un preprocessor personalizado.

Una plantilla útil para pull requests solicita el resultado de dockup plan --json, el efecto esperado del deployment, si se ha solicitado --prune y el ID del deployment anterior. Esto proporciona las mismas evidencias a un agente de IA o a un revisor humano.

Introduce el manifest sin alterar el estado activo

En un servicio existente, empieza por los campos que puedas verificar. Ejecuta dockup info production/api --json, escribe un dockup.yaml mínimo y compáralo con dockup plan. Añade la configuración por etapas en lugar de intentar reconstruir de una vez todas las decisiones históricas del dashboard.

Como la aplicación es aditiva, los valores sin secretos y los dominios no gestionados permanecen mientras avanza la adopción. Cuando el manifest represente correctamente la configuración prevista que no contiene secretos, decide si el equipo usará pruning alguna vez. Algunos equipos mantienen la limpieza como un proceso manual; otros permiten --prune únicamente en un pipeline protegido y después de aprobar el plan.

El objetivo de la configuración como código no es maximizar el número de líneas en Git. Es hacer que la intención de producción sea comprensible, revisable y recuperable.

Mantén los planes libres de material secreto

Un plan debería poder adjuntarse de forma segura a un pull request o a un registro de incidentes. Como dockup.yaml solo contiene valores sin secretos y los valores secretos existentes siguen protegidos, los revisores pueden inspeccionar la configuración prevista sin recibir credenciales de producción. Aun así, revisa los valores ordinarios por si contienen hostnames internos, identificadores de clientes u otros datos que no deban ser públicos.

Mantén juntos el origen y el objetivo

Indica el project/service previsto en el pull request y en el job de deployment. Un dockup.yaml válido aplicado al objetivo equivocado sigue siendo un fallo operativo. La detección del objetivo y la revisión del manifest son comprobaciones obligatorias independientes.

Valida el YAML antes del plan

Analiza el manifest en CI antes de llamar a Dockup para que los errores de indentación o de tipo fallen cerca del cambio de código fuente. La validación de sintaxis no sustituye a dockup plan; evita solicitudes innecesarias con un archivo ilegible.

Prefiere una única fuente

Un dockup.yaml revisado debería explicar la intención de producción.

Empieza con un deployment verificable

Añade un manifest mínimo a un servicio, ejecuta un plan de solo lectura y revisa todos los campos indicados antes de la primera aplicación.

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.

Preguntas frecuentes

¿Qué es dockup.yaml?

Es el manifest de config as code de Dockup para declarar la rama, el puerto, la configuración de build y start, los healthchecks, los valores de entorno sin secretos y los dominios de un servicio.

¿dockup plan modifica producción?

No. dockup plan es de solo lectura y muestra la diferencia entre el manifest y el servicio activo.

¿dockup up elimina la configuración que no está en el archivo?

No de forma predeterminada. La aplicación es aditiva. Los valores de entorno sin secretos y los dominios compatibles solo se eliminan cuando se usa explícitamente --prune.

¿Se pueden guardar secretos en dockup.yaml?

No deberían guardarse. Confirma únicamente valores sin secretos; configura los secretos mediante el comando de entorno de secretos o mediante inyección de secretos en runtime. Los secretos existentes están protegidos frente al pruning.

¿Puede dockup up hacer deploy después de aplicar la configuración?

Sí. La opción documentada --deploy aplica el manifest y activa un deployment, cuyo resultado terminal debe verificarse posteriormente.