21. Documentación de despliegue: ambientes, versiones, dependencias y automatización

21.1 Introducción

El despliegue es el proceso mediante el cual una versión del software se publica en un ambiente para que pueda ser usada, probada u operada. Puede tratarse de un ambiente de desarrollo, pruebas, preproducción o producción. Documentar este proceso es fundamental para reducir errores y repetir entregas de forma confiable.

Una aplicación puede estar correctamente construida y aun así fallar por un despliegue incorrecto: versión equivocada, migración no ejecutada, variable faltante, dependencia incompatible, orden incorrecto de pasos o validación omitida.

En este tema veremos cómo documentar ambientes, versiones, dependencias, automatización, pasos de despliegue, validaciones, reversión y coordinación de releases.

21.2 Qué es documentación de despliegue

La documentación de despliegue describe cómo llevar una versión del sistema a un ambiente determinado. Indica qué se despliega, dónde, con qué configuración, bajo qué condiciones, en qué orden y cómo verificar que el resultado fue correcto.

A diferencia de la instalación, que explica cómo preparar el sistema, el despliegue se concentra en publicar cambios. Puede incluir construcción de artefactos, ejecución de pipelines, actualización de servicios, migraciones, reinicios, pruebas posteriores y comunicación a usuarios.

21.3 Elementos de un despliegue documentado

La imagen muestra los elementos principales de la documentación de despliegue: ambientes, versiones, artefactos, dependencias, configuración, automatización, migraciones, validaciones, monitoreo y reversión.

21.4 Ambientes

Un ambiente es un entorno donde el sistema se ejecuta. Puede ser desarrollo, pruebas, integración, preproducción o producción. Cada ambiente puede tener datos, configuración, permisos, servicios externos y objetivos distintos.

La documentación debe explicar qué ambientes existen, para qué se usan, quién tiene acceso, cómo se actualizan y qué diferencias importantes hay entre ellos. Esto evita confundir pruebas con producción o usar configuraciones incorrectas.

21.5 Versiones y releases

La documentación de despliegue debe indicar qué versión se publica. Puede ser una etiqueta, número de versión, commit, build, paquete, imagen de contenedor o release. Sin identificación clara, es difícil saber qué código está ejecutándose.

También conviene documentar contenido de la release: funcionalidades nuevas, correcciones, cambios de configuración, migraciones, riesgos conocidos y pasos especiales.

21.6 Artefactos de despliegue

Un artefacto de despliegue es el elemento que se publica: archivo compilado, paquete, imagen de contenedor, script, plantilla de infraestructura o conjunto de archivos. La documentación debe indicar cómo se genera, dónde se almacena y cómo se identifica.

Si el artefacto se construye automáticamente, la guía debe explicar el pipeline o enlace correspondiente. Si se construye manualmente, deben documentarse pasos y verificaciones para evitar errores.

21.7 Dependencias

Antes de desplegar, puede ser necesario verificar dependencias: base de datos, colas, servicios externos, certificados, infraestructura, permisos, versiones de runtime, espacio en disco o conectividad.

La documentación debe indicar qué dependencias son necesarias y cómo comprobar que están disponibles. También debe explicar si el despliegue depende de otros despliegues previos.

21.8 Configuración por ambiente

Cada ambiente suele tener valores de configuración propios: URLs, credenciales, niveles de registro, banderas de funcionalidad, límites, conexiones y claves. La documentación de despliegue debe indicar qué configuración se requiere y dónde se administra.

Es importante evitar publicar secretos en la documentación. En su lugar, deben describirse nombres de variables, propósito, ubicación segura y responsables de administración.

21.9 Migraciones

Muchos despliegues requieren migraciones de base de datos o datos. La documentación debe indicar si existen migraciones, cuándo se ejecutan, en qué orden, si son reversibles, cuánto pueden tardar y qué respaldo se requiere antes de aplicarlas.

Las migraciones son una de las partes más delicadas del despliegue. Un cambio incompatible entre aplicación y base de datos puede interrumpir el servicio. Por eso, deben planificarse y verificarse con cuidado.

21.10 Automatización

Muchos equipos usan pipelines de integración y entrega continua para automatizar pruebas, construcción y despliegue. La documentación debe explicar qué pasos automatiza el pipeline, qué disparadores lo ejecutan, qué entradas requiere y cómo interpretar resultados.

Automatizar no elimina la necesidad de documentación. Al contrario, hace necesario documentar el proceso para saber qué ocurre, dónde revisar fallas y cómo actuar si se interrumpe.

21.11 Pasos de despliegue

Los pasos de despliegue deben estar ordenados y ser verificables. Deben indicar acciones previas, ejecución, validación y cierre. Si hay pasos manuales, deben ser explícitos y tener responsables.

Por ejemplo: confirmar versión, verificar dependencias, ejecutar respaldo, iniciar pipeline, aplicar migraciones, publicar aplicación, ejecutar pruebas de humo, revisar monitoreo y comunicar finalización.

21.12 Validaciones posteriores

Después del despliegue se debe comprobar que el sistema funciona. Las validaciones pueden incluir pruebas de humo, consulta de endpoints de salud, revisión de registros, métricas, errores, cola de mensajes, base de datos y funcionalidades críticas.

La documentación debe indicar qué validar, cómo hacerlo y qué resultado se espera. Sin validación, el equipo puede descubrir fallas recién cuando los usuarios las reportan.

21.13 Reversión o rollback

Todo despliegue importante debería tener un plan de reversión. El rollback indica cómo volver a un estado anterior si la versión falla. Puede implicar restaurar artefacto, revertir configuración, deshacer migraciones o activar una versión previa.

No todas las reversiónes son simples. Si hay cambios de datos o migraciones incompatibles, el rollback requiere planificación especial. La documentación debe aclarar limitaciones y riesgos.

21.14 Tabla de control de despliegue

21.15 Comunicación del despliegue

Algunos despliegues requieren comunicación: aviso a usuarios, soporte, operación, responsables de producto o equipos integrados. La documentación puede indicar a quién informar, cuándo, por qué canal y con qué información.

También conviene registrar ventanas de mantenimiento, impacto esperado, funcionalidades afectadas y contactos ante incidentes.

21.16 Errores frecuentes

Al documentar despliegues suelen aparecer estos errores:

• No indicar versión exacta o artefacto publicado.
• Mezclar instrucciones de distintos ambientes.
• Omitir migraciones o dependencias previas.
• No documentar validaciones posteriores.
• No tener plan de reversión.
• Depender de pasos manuales no escritos.
• No actualizar la guía cuando cambia el pipeline o la infraestructura.

21.17 Qué debes recordar de este tema

• La documentación de despliegue permite publicar versiones de forma controlada.
• Debe indicar ambiente, versión, artefacto, dependencias y configuración.
• Las migraciones requieren especial cuidado y documentación.
• La automatización necesita explicación y monitoreo.
• Todo despliegue debe tener validaciones posteriores.
• Un plan de rollback reduce riesgo ante fallas.
• La comunicación forma parte del despliegue cuando hay impacto en usuarios o equipos.

21.18 Conclusión

La documentación de despliegue convierte la publicación de software en un proceso repetible, verificable y menos riesgoso. Al definir ambientes, versiones, dependencias, automatización y reversión, el equipo puede entregar cambios con mayor control.

En el próximo tema estudiaremos la documentación de operación: monitoreo, respaldos, alertas y tareas frecuentes.