Cómo documentar una infraestructura basada en Docker

Introducción

Documentar una infraestructura basada en Docker significa dejar suficiente información para que una persona autorizada pueda comprender qué proyectos existen, cómo se relacionan, qué imágenes utilizan, dónde están sus datos, qué redes comparten, cómo se despliegan y cómo deben recuperarse si algo falla. No consiste en copiar la salida de docker ps ni en guardar una captura de un panel gráfico. Es convertir una plataforma que cambia continuamente en un sistema comprensible y reproducible.

Docker facilita crear y recrear contenedores, pero esa facilidad puede generar una falsa sensación de que la infraestructura ya está documentada porque existe un archivo Compose. Ese archivo describe una parte importante del despliegue, pero normalmente no explica por qué existe el proyecto, qué función cumple, qué dependencias externas utiliza, dónde se custodian los secretos, qué datos deben copiarse, qué servicio debe recuperarse primero o qué procedimiento confirma que la aplicación vuelve a funcionar correctamente.

La necesidad de documentación aumenta cuando la plataforma crece. Un host con dos proyectos puede entenderse inspeccionándolo. Cuando aparecen diez o veinte aplicaciones, redes compartidas, volúmenes persistentes, imágenes propias, bases de datos, proxys, monitorización y automatizaciones, reconstruir el contexto únicamente desde Docker se convierte en una tarea lenta y arriesgada.

Una buena documentación debe combinar inventario, arquitectura, procedimientos y registro de cambios. El inventario responde qué existe. La arquitectura explica cómo se relaciona. Los procedimientos indican cómo operar, desplegar, actualizar y recuperar. El historial ayuda a comprender por qué la plataforma está como está.

Este artículo se centra exclusivamente en esa documentación Docker. La documentación general de una máquina se desarrolla en cómo documentar correctamente un servidor Linux, mientras que cómo inventariar servicios instalados en un servidor Linux ayuda a descubrir qué ejecuta el host. Aquí el objetivo es construir una capa documental específica para proyectos, contenedores, imágenes, redes, volúmenes y procedimientos Docker.

Índice

• Qué debe conseguir la documentación Docker
• Separar inventario, arquitectura y procedimientos
• Definir una fuente de verdad documental
• Documentar el host Docker
• Crear un inventario de proyectos
• Qué debe contener la ficha de cada proyecto
• Documentar archivos Compose y variantes
• Documentar servicios y contenedores
• Registrar imágenes y procedencia
• Documentar redes y comunicaciones
• Documentar volúmenes y datos persistentes
• Registrar puertos y exposición
• Documentar variables de entorno
• Registrar secretos sin exponerlos
• Mapear dependencias entre proyectos
• Documentar servicios compartidos
• Documentar propiedad y criticidad de los datos
• Documentar copias y restauración
• Crear procedimientos de despliegue
• Documentar actualizaciones
• Documentar reversión
• Documentar monitorización y health checks
• Documentar logs y diagnóstico
• Preparar un runbook de recuperación
• Documentar la reconstrucción completa del host
• Mantener un registro de cambios útil
• Revisar y validar la documentación
• Ejemplo de estructura documental
• Errores frecuentes
• Lista de comprobación
• Preguntas frecuentes
• Conclusión

Qué debe conseguir la documentación Docker

La documentación debe reducir incertidumbre. Una persona autorizada debería poder responder sin investigar durante horas:

• qué proyectos están activos;
• qué función cumple cada uno;
• dónde está su definición;
• qué imagen utiliza;
• qué redes necesita;
• qué puertos publica;
• dónde residen sus datos;
• qué credenciales consume;
• de qué otros servicios depende;
• cómo se comprueba su estado;
• cómo se despliega;
• cómo se actualiza;
• cómo se copia;
• cómo se restaura;
• cómo se retira.

Si la respuesta a estas preguntas depende de inspeccionar contenedores en ejecución, la plataforma contiene conocimiento operativo que aún no está documentado.

Documentar para operar, no para archivar

La documentación útil debe apoyar tareas reales: una incidencia, una actualización, una migración, una restauración o un relevo técnico. Un documento extenso que nadie consulta aporta menos valor que una ficha breve, exacta y actualizada.

Separar inventario, arquitectura y procedimientos

Mezclar todos los datos en un único documento dificulta localizar información. Conviene separar al menos tres niveles.

Inventario

Responde qué existe y cuál es su estado general.

Arquitectura

Explica relaciones, dependencias, redes, datos y componentes compartidos.

Procedimientos

Describen cómo realizar una acción concreta.

Por ejemplo:

Inventario
└── proyecto: gestor-documental

Arquitectura
└── depende de proxy, base de datos y almacenamiento

Procedimientos
├── desplegar
├── actualizar
├── copiar
├── restaurar
└── retirar

Esta separación permite mantener cada parte con un nivel de detalle adecuado.

Definir una fuente de verdad documental

Una infraestructura se vuelve difícil de administrar cuando existen varias copias de la documentación y nadie sabe cuál es la vigente.

Elegir una ubicación oficial

Puede ser un repositorio Git, una base documental interna o una combinación controlada. Lo importante es que exista una referencia clara.

Documentación junto al proyecto

La información específica de una aplicación puede mantenerse cerca de su definición:

proyecto/
├── compose.yml
├── README.md
└── docs/

Documentación global fuera de los proyectos

El mapa de arquitectura, inventario de host y procedimientos globales pueden mantenerse en una ubicación común.

No depender solo del servidor productivo

Si la documentación únicamente existe en el host que puede fallar, desaparecerá justo cuando más se necesite.

Documentar el host Docker

Antes de describir proyectos, conviene registrar la base donde se ejecutan.

• hostname;
• función;
• entorno;
• ubicación o proveedor;
• sistema operativo;
• versión de Docker;
• método de instalación;
• configuración relevante del daemon;
• almacenamiento disponible;
• interfaces y redes;
• usuarios autorizados;
• método de acceso;
• monitorización;
• copias;
• responsable técnico;
• fecha de revisión.

Esta ficha no debe duplicar toda la documentación Linux. Debe contener únicamente lo necesario para entender el papel del host dentro de la plataforma Docker.

Crear un inventario de proyectos

El inventario de proyectos debe ser la referencia principal para saber qué servicios Docker existen.

Estados útiles

• activo;
• pruebas;
• en migración;
• pendiente de retirada;
• retirado.

El inventario debe representar servicios, no una fotografía de contenedores. Un proyecto puede recrear sus contenedores sin cambiar su identidad.

Qué debe contener la ficha de cada proyecto

La ficha debe permitir comprender la aplicación sin abrir todos sus archivos.

• nombre;
• finalidad;
• responsable;
• criticidad;
• entorno;
• ruta de despliegue;
• repositorio;
• archivo Compose;
• servicios incluidos;
• imágenes;
• redes;
• puertos;
• volúmenes;
• datos persistentes;
• variables;
• secretos requeridos;
• dependencias externas;
• monitorización;
• copias;
• procedimiento de recuperación;
• fecha de última revisión.

Esta ficha puede vivir dentro del README.md si el proyecto es sencillo.

Documentar archivos Compose y variantes

Debe quedar claro qué archivo se utiliza realmente.

Registrar

• nombre del archivo principal;
• archivos adicionales;
• variables requeridas;
• entorno al que pertenecen;
• comandos habituales;
• origen del repositorio.

Evitar ambigüedad

Si existen:

compose.yml
compose.prod.yml
compose.test.yml

la documentación debe explicar cómo se combinan y cuál corresponde a producción.

El archivo no explica el contexto

Compose describe servicios, pero no necesariamente por qué se utiliza una red externa, qué datos son críticos o cuál es la secuencia de restauración. Esa información debe añadirse.

Documentar servicios y contenedores

Los contenedores son instancias; los servicios son funciones.

Para cada servicio conviene registrar:

• función;
• imagen;
• dependencias;
• puertos internos;
• redes;
• volúmenes;
• health check;
• política de reinicio;
• logs;
• recursos especiales;
• privilegios excepcionales.

No documentar nombres efímeros

Un identificador de contenedor cambia al recrearse. La documentación debe referirse al servicio lógico.

Registrar imágenes y procedencia

Una plataforma debe saber de dónde proviene cada imagen.

• repositorio;
• nombre;
• tag;
• digest cuando se utilice;
• proveedor;
• licencia si procede;
• documentación oficial;
• método de actualización;
• si es propia o de terceros.

Imágenes propias

Debe registrarse dónde está el Dockerfile, qué proceso las construye y dónde se publican.

Imágenes de terceros

Conviene registrar por qué se eligieron y qué criterio se utiliza para aceptar nuevas versiones.

La gestión detallada de imágenes corresponde a otro artículo del clúster; aquí el objetivo es asegurar trazabilidad documental.

Documentar redes y comunicaciones

Una lista de redes no es suficiente. Hay que explicar su finalidad.

Registrar conexiones externas

Si un contenedor necesita acceder a una API, base de datos externa o almacenamiento remoto, debe quedar indicado.

Mapas simples

Un esquema puede ser suficiente:

Internet
  ↓
proxy
  ↓
red-entrada
  ├── portal-web
  └── documentos-web

Documentar volúmenes y datos persistentes

Los volúmenes merecen una ficha porque pueden contener la parte más valiosa de la plataforma.

Para cada volumen debe conocerse:

• proyecto;
• servicio;
• contenido;
• criticidad;
• tamaño aproximado;
• crecimiento;
• propietario;
• método de copia;
• método de restauración;
• si puede regenerarse.

Named volume o bind mount

La documentación debe distinguirlos porque su localización y gestión son diferentes.

Volumen huérfano

Antes de eliminar un volumen sin contenedor, el inventario debe permitir saber si pertenece a un proyecto retirado o contiene datos pendientes de conservar.

Registrar puertos y exposición

Los puertos ayudan a comprender qué servicios son accesibles y desde dónde.

• puerto interno;
• puerto publicado;
• interfaz;
• protocolo;
• origen permitido;
• servicio;
• motivo de exposición.

Distinguir interno y externo

Un puerto utilizado dentro de una red Docker no implica exposición al host.

Registrar excepciones

Un puerto abierto temporalmente para diagnóstico debe tener fecha de retirada.

Documentar variables de entorno

La documentación debe describir qué variables requiere el proyecto sin exponer valores sensibles.

Una tabla puede incluir:

• nombre;
• finalidad;
• obligatoria u opcional;
• tipo;
• valor de ejemplo no sensible;
• origen;
• si requiere reinicio.

Plantilla

Un archivo .env.example ayuda a mantener esta información junto al proyecto.

No duplicar información

Si la plantilla ya es clara, el README puede enlazarla en lugar de reproducir todos los valores.

Registrar secretos sin exponerlos

La documentación debe saber que el secreto existe, pero no contenerlo.

Para cada secreto conviene registrar:

• nombre lógico;
• servicio que lo utiliza;
• tipo;
• ubicación segura;
• responsable;
• procedimiento de rotación;
• fecha de revisión.

Ejemplo

DB_PASSWORD
Tipo: credencial de base de datos
Usado por: portal-app
Custodia: gestor de secretos
Rotación: procedimiento DB-ROT-01

No debe incluirse la contraseña.

Mapear dependencias entre proyectos

Una plataforma puede parecer bien documentada proyecto por proyecto y seguir siendo peligrosa si no se conocen las relaciones.

Debe registrarse:

• qué proyecto depende de cuál;
• qué servicio compartido utiliza;
• qué protocolo emplea;
• qué ocurre si la dependencia falla;
• si existe alternativa temporal;
• orden de recuperación.

Mapa de dependencia

portal
├── proxy
├── db-portal
├── SMTP
└── almacenamiento

automatizacion
├── proxy
├── db-automatizacion
└── API externa

Este mapa es especialmente útil durante incidencias.

Documentar servicios compartidos

Proxy, monitorización, motores de base de datos o almacenamiento común pueden convertirse en puntos de fallo relevantes.

Para cada uno debe documentarse:

• función;
• proyectos dependientes;
• criticidad;
• capacidad;
• copia;
• recuperación;
• actualización;
• responsable.

El impacto cambia con el tiempo

Un proxy utilizado por dos servicios puede convertirse en componente crítico cuando publica veinte. La documentación debe reflejar esa evolución.

Documentar propiedad y criticidad de los datos

No todos los datos tienen el mismo valor.

Conviene clasificar:

• datos empresariales;
• bases de datos;
• uploads;
• configuración;
• logs;
• cachés;
• temporales;
• artefactos regenerables.

Propietario

Debe saberse qué proyecto es fuente de verdad.

Retención

Debe indicarse cuánto tiempo se conserva cada tipo de información.

Recuperación

La ficha debe aclarar qué datos son imprescindibles para reconstruir el servicio.

Documentar copias y restauración

Una copia no está documentada si solo se conoce el comando que la genera.

Para cada proyecto debe indicarse:

• qué se copia;
• qué se excluye;
• frecuencia;
• retención;
• destino;
• cifrado;
• responsable;
• última prueba de restauración;
• tiempo aproximado de recuperación.

Bases de datos

Debe documentarse si se utiliza exportación lógica, snapshot, copia física o método específico.

Volúmenes

No debe asumirse que todos se copian igual.

Configuración

Puede estar protegida mediante control de versiones, pero los valores locales y secretos necesitan mecanismos adicionales.

Crear procedimientos de despliegue

El runbook de despliegue debe permitir que otra persona reproduzca el proceso.

1. Obtener la versión correcta del proyecto.
2. Preparar archivos locales.
3. Recuperar secretos autorizados.
4. Validar variables.
5. Obtener o construir imágenes.
6. Levantar servicios.
7. Comprobar logs.
8. Ejecutar pruebas funcionales.
9. Registrar versión y fecha.

Incluir precondiciones

Debe indicarse si requiere red externa, DNS, certificados o volúmenes existentes.

Incluir validación

El procedimiento termina cuando se demuestra que la función funciona, no cuando el contenedor aparece como running.

Documentar actualizaciones

El procedimiento debe describir:

• cómo se conoce una nueva versión;
• qué documentación se revisa;
• qué copia previa se realiza;
• qué imagen se descarga;
• si hay migraciones;
• qué pruebas se ejecutan;
• cómo se registra el cambio.

La estrategia completa de actualización tendrá un artículo específico. En la documentación basta con que el proceso sea localizable y repetible.

Documentar reversión

Un rollback debe ser un procedimiento, no una expectativa.

Conviene indicar:

• versión anterior;
• imagen;
• compatibilidad de datos;
• backup requerido;
• pasos de reversión;
• validación;
• condiciones en las que no es seguro revertir.

Migraciones de base de datos

Son una de las razones por las que volver a una imagen anterior puede no ser suficiente.

Documentar monitorización y health checks

Debe saberse qué señales indican que el servicio funciona.

• URL de health check;
• comando de comprobación;
• métrica;
• umbral;
• alerta;
• destinatario;
• acción recomendada.

Contenedor no equivale a servicio

El estado Docker debe complementarse con una comprobación funcional.

Alertas compartidas

Conviene distinguir fallos de proyecto, de servicio común y de host.

Documentar logs y diagnóstico

Durante una incidencia debe saberse dónde mirar primero.

Para cada servicio conviene indicar:

• ubicación de logs;
• comando de consulta;
• retención;
• rotación;
• campos importantes;
• errores habituales;
• correlación con otros servicios.

Diagnóstico inicial

Un pequeño runbook puede incluir:

1. comprobar contenedor
2. revisar health check
3. revisar logs
4. comprobar dependencia
5. revisar espacio
6. revisar red
7. validar funcionalidad

Preparar un runbook de recuperación

La recuperación debe estar escrita antes de necesitarla.

Para cada proyecto debe describirse:

• qué recursos necesita;
• qué backup utilizar;
• orden de restauración;
• cómo recuperar secretos;
• cómo desplegar;
• cómo validar datos;
• cómo comprobar servicio;
• qué usuarios deben ser informados.

Prioridad

Si existen varios proyectos, la documentación debe indicar cuáles se recuperan primero.

Prueba

Un runbook no está validado hasta que se ha utilizado en una restauración real o simulada.

Documentar la reconstrucción completa del host

La plataforma debe poder recrearse aunque el servidor original desaparezca.

Un procedimiento general puede incluir:

1. Preparar un nuevo host.
2. Instalar sistema operativo.
3. Configurar red y acceso.
4. Instalar Docker.
5. Restaurar configuración global.
6. Crear redes compartidas.
7. Desplegar servicios comunes.
8. Restaurar datos.
9. Desplegar proyectos.
10. Recuperar secretos.
11. Configurar DNS o entrada.
12. Validar proyecto por proyecto.

Dependencias externas

La reconstrucción debe contemplar certificados, dominios, almacenamiento, APIs y servicios externos.

Mantener un registro de cambios útil

No es necesario registrar cada comando. Deben registrarse los cambios que alteran el estado o la arquitectura.

Ejemplos:

• nueva versión;
• nuevo volumen;
• cambio de red;
• rotación de credencial;
• migración de base de datos;
• nuevo servicio;
• retirada de proyecto;
• cambio de backup;
• cambio de proxy;
• movimiento a otro host.

Campos recomendados

• fecha;
• proyecto;
• cambio;
• motivo;
• responsable;
• validación;
• incidencia asociada cuando exista.

Revisar y validar la documentación

La documentación se degrada si no forma parte de la operación.

Revisión después de cambios

Cualquier modificación de arquitectura debe actualizar la documentación asociada.

Revisión periódica

Trimestral o semestralmente puede compararse documentación con:

• proyectos activos;
• imágenes;
• redes;
• volúmenes;
• puertos;
• copias;
• alertas;
• responsables.

Validación por otra persona

La mejor prueba consiste en pedir a otra persona autorizada que localice un proyecto, lo despliegue en pruebas o siga un procedimiento de recuperación.

Documentación obsoleta es peor que ausencia

Un documento incorrecto puede llevar a ejecutar una acción peligrosa con confianza.

Ejemplo de estructura documental

documentacion-docker/
├── README.md
├── hosts/
│   └── docker-prod-01.md
├── inventario/
│   └── proyectos.md
├── arquitectura/
│   ├── redes.md
│   ├── dependencias.md
│   └── servicios-compartidos.md
├── proyectos/
│   ├── proxy.md
│   ├── portal.md
│   └── monitorizacion.md
├── procedimientos/
│   ├── desplegar.md
│   ├── actualizar.md
│   ├── backup.md
│   ├── restaurar.md
│   └── reconstruir-host.md
└── cambios/
    └── historial.md

No es una estructura obligatoria. Su valor es separar información global, fichas de proyecto y procedimientos.

Documentación local

Cada proyecto puede mantener además:

proyecto/
├── compose.yml
├── .env.example
├── README.md
└── docs/

La documentación global enlaza a la local en lugar de duplicarla.

Errores frecuentes

Considerar docker ps como inventario

Muestra instancias activas, no finalidad, datos, dependencias ni recuperación.

Confiar únicamente en Compose

Describe despliegue, pero no todo el contexto operativo.

Documentar IDs de contenedor

Cambian al recrearse y no representan identidades estables.

Guardar contraseñas en README

La documentación debe indicar ubicación, no valor.

No documentar volúmenes

Puede convertir limpieza o migración en riesgo de pérdida.

No distinguir puerto interno y publicado

Produce errores al analizar exposición.

No registrar redes externas

El proyecto puede no reconstruirse correctamente.

No documentar servicios compartidos

Oculta puntos comunes de fallo.

Documentar solo el estado normal

También hacen falta procedimientos de incidencia y recuperación.

Crear manuales enormes

La información importante se pierde entre detalles que podrían deducirse.

Duplicar documentación

Varias copias terminan divergiendo.

Actualizar la infraestructura y dejar el documento para después

Ese “después” suele convertirse en desactualización permanente.

No probar restauraciones

Una documentación de recuperación no validada sigue siendo una hipótesis.

Guardar toda la documentación en producción

Puede desaparecer durante el mismo fallo que se intenta resolver.

Lista de comprobación

• ¿Existe una fuente oficial de documentación?
• ¿La documentación está disponible fuera del host productivo?
• ¿El host Docker tiene ficha propia?
• ¿Existe inventario de proyectos?
• ¿Cada proyecto tiene finalidad y responsable?
• ¿La criticidad está registrada?
• ¿Se conoce la ruta de despliegue?
• ¿Se conoce el repositorio?
• ¿Está identificado el Compose activo?
• ¿Se documentan variantes de entorno?
• ¿Se registran servicios lógicos?
• ¿Se conoce la procedencia de las imágenes?
• ¿Las redes tienen una finalidad documentada?
• ¿Se conocen los proyectos conectados a redes compartidas?
• ¿Los volúmenes están inventariados?
• ¿Se conoce qué datos contiene cada volumen?
• ¿Los puertos publicados están justificados?
• ¿Las variables están descritas?
• ¿Existe una plantilla de variables?
• ¿Los secretos están referenciados sin exponerlos?
• ¿Las dependencias entre proyectos están mapeadas?
• ¿Los servicios compartidos tienen ficha propia?
• ¿Se conoce la propiedad de los datos?
• ¿Las copias están documentadas?
• ¿La restauración está documentada?
• ¿Existe procedimiento de despliegue?
• ¿Existe procedimiento de actualización?
• ¿Existe procedimiento de rollback?
• ¿Los health checks están registrados?
• ¿Los logs son localizables?
• ¿Existe un runbook de recuperación?
• ¿Puede reconstruirse el host completo?
• ¿Se mantiene historial de cambios?
• ¿La documentación se revisa periódicamente?
• ¿Otra persona ha validado al menos un procedimiento?

Preguntas frecuentes

Conclusión

Documentar una infraestructura basada en Docker significa convertir una plataforma dinámica en un sistema comprensible, mantenible y recuperable.

La documentación debe empezar por un inventario de proyectos y continuar con imágenes, redes, volúmenes, puertos, variables, secretos y dependencias. Cada elemento debe describirse por su función y ciclo de vida, no como una simple salida de comandos.

Docker aporta reproducibilidad, pero la reproducibilidad técnica no sustituye el contexto operativo. Un archivo Compose puede reconstruir contenedores, pero no explica por sí solo qué datos restaurar, qué credenciales recuperar, qué servicio levantar primero o cómo comprobar que la aplicación funciona correctamente.

Los procedimientos son una parte central del sistema documental. Despliegue, actualización, reversión, backup, restauración y reconstrucción deben poder seguirse de forma repetible y validarse mediante pruebas.

La documentación también debe mantenerse fuera del mismo punto de fallo que describe. Si toda la información vive únicamente en producción, puede desaparecer durante la incidencia.

Una plataforma Docker bien documentada permite que otra persona pueda entenderla, operar sobre ella y recuperarla sin depender de memoria personal. Esa capacidad es una de las mejores señales de que la infraestructura ha dejado de ser una colección de contenedores y se ha convertido en un sistema técnico sostenible.