Módulo 7: Gitops Beyond Terraform

8. Proyecto: la decisión de herramienta de Andes Cargo

Descripción

Este proyecto no escribe una sola línea de YAML nueva. En cambio, convierte las siete lecciones anteriores de este módulo en el tipo de documento que un equipo de ingeniería real produce cuando toma una decisión de herramienta que otras personas van a heredar: un ADR (Architecture Decision Record, registro de decisión de arquitectura). Vas a escribir el ADR completo donde Andes Cargo justifica, por escrito, por qué eligió GitHub Actions sobre Jenkins y GitLab CI —con la evidencia de mercado real citada, no una opinión sin sustento— y qué cambiaría el día que la empresa despliegue su propia aplicación sobre un clúster de Kubernetes. Es un documento real y completo, del mismo tipo que se guarda en el repositorio de cualquier equipo serio, versionado junto al código que la decisión afecta.

Conexión con el módulo

Este proyecto es la síntesis del módulo completo, no una lección aislada. La evidencia de mercado que cita viene de la lección 2; la comparación de sintaxis, también. La sección sobre qué cambiaría con Kubernetes retoma, con precisión, las lecciones 3 y 4 (ArgoCD/Flux, push vs. pull). El ADR es, en sí mismo, el entregable ejecutado de este módulo —EJECUTADO (el documento), como lo etiqueta el diseño de esta guía—: no corre código, pero es un artefacto real, escrito completo, no descrito en abstracto. El Módulo 8, el capstone de toda la guía, no vuelve a escribir un ADR — retoma el pipeline técnico completo (ci.yml, apply.yml, drift.yml, el guardrail) para un recorrido end-to-end final.

Analogía: el diario de navegación de un capitán

Imagina un capitán de barco que, en algún punto de un viaje largo, decide cambiar de ruta —evitar una zona de tormentas, aunque signifique más días de viaje—. Un capitán descuidado simplemente cambia el rumbo y sigue navegando: el barco llega, tarde o temprano, pero nadie que suba a bordo después —un oficial nuevo, un inspector, el propio capitán dentro de seis meses, con la memoria ya borrosa— puede saber por qué se tomó esa decisión, ni si las condiciones que la motivaron siguen siendo válidas. Un capitán serio, en cambio, anota en el diario de navegación: la fecha, la posición exacta, qué información tenía disponible en ese momento (el reporte del clima, la carga a bordo, el combustible restante), qué decidió, y qué esperaba que pasara como consecuencia. Ese diario no cambia el rumbo del barco —el barco ya giró—, pero convierte una decisión que vivía solo en la cabeza del capitán en algo que cualquiera puede leer y entender, incluso años después.

Un ADR es, con precisión, el diario de navegación de una decisión técnica. No es el código que implementa la decisión —eso ya lo construiste, en los Módulos 2 a 6—, es el registro de por qué se tomó esa decisión, con qué información, y qué se esperaba a cambio. Para una empresa de logística como Andes Cargo, la metáfora ni siquiera es forzada: es, literalmente, el mismo tipo de documento que un capitán de carga real llevaría sobre decisiones de ruta.

Qué es un ADR, con precisión (el formato, no solo la idea)

Un ADR sigue un formato estándar, propuesto originalmente por Michael Nygard en 2011 y ampliamente adoptado desde entonces en la industria del software: un archivo de texto corto (una o dos páginas, según el formato original), versionado junto al código, con cinco secciones fijas:

Título — una frase nominal corta que identifica la decisión.
Estado — propuesto, aceptado, obsoleto, o reemplazado por [ADR-XXXX].
Contexto — las fuerzas en juego: técnicas, de negocio, del equipo — sin tomar partido todavía, solo describiendo la situación.
Decisión — la respuesta, en voz activa: "vamos a hacer X", no "se podría considerar X".
Consecuencias — el contexto resultante después de aplicar la decisión, todas las consecuencias, no solo las positivas.

La convención de dónde viven estos archivos, popularizada por herramientas como adr-tools, es una carpeta doc/adr/ en la raíz del repositorio, con archivos numerados secuencialmente: 0001-titulo-corto.md, 0002-siguiente-decision.md, y así — un historial de decisiones, no un documento único que se reescribe cada vez.

El ADR completo de Andes Cargo

Este es el documento tal como viviría en andes-cargo-infra/doc/adr/0001-choosing-cicd-tooling.md, si lo escribieras hoy, con las lecciones de este módulo como fuente directa:

# ADR-0001: Elegir GitHub Actions como herramienta de CI/CD para andes-cargo-infra

## Estado

Aceptado — agosto de 2026

## Contexto

andes-cargo-infra/ declara, en Terraform, la infraestructura completa de Andes Cargo sobre
AWS: el bucket andes-cargo-shipment-docs, la tabla Shipments, los roles
LambdaManifestProcessorRole y AppServerRole, y la función process-shipment-manifest. Hasta
ahora, cualquier cambio a esa infraestructura se aplicaba a mano, desde la laptop de quien
lo escribió, sin revisión sistemática ni registro de quién corrió qué comando. El equipo
necesita automatizar ese proceso: verificar cada cambio propuesto, dejarlo para revisión
antes de fusionar, y aplicar automáticamente solo lo que ya fue aprobado.

Evaluamos cuatro herramientas: GitHub Actions, GitLab CI, CircleCI y Jenkins. La auditoría
de mercado de este ecosistema (VALIDACION.md, jul-2026) es clara sobre la evidencia real del
stack español: Jenkins aparece en 5 de 13 ofertas relevadas, casi el doble que GitHub
Actions (~3 de 13) — IRIUM, Apptiva y MediaStream nombran Jenkins explícitamente, frente a
CookUnity y EarnIn, que nombran GitHub Actions.

Restricciones del equipo: sin presupuesto ni personal dedicado para mantener un servidor de
CI propio; el código ya vive en GitHub; se prioriza poder probar el pipeline completo en
local, sin gastar en runners hospedados, mientras el equipo aprende esta capa por primera
vez.

## Decisión

Vamos a usar GitHub Actions como la herramienta de CI/CD para andes-cargo-infra/, con tres
justificaciones concretas, ninguna de las cuales es "domina el mercado":

1. Fricción cero: la configuración vive en el mismo repositorio, en `.github/workflows/`,
   sin un servidor separado que instalar ni mantener — a diferencia de Jenkins, que en la
   inmensa mayoría de los casos reales requiere infraestructura propia.
2. Existe `act` (nektos/act): permite correr el mismo YAML localmente, en Docker, gratis, sin
   cuenta de GitHub ni minutos de runners hospedados — la pieza que hace posible que el
   equipo aprenda y pruebe el pipeline completo a costo $0 mientras se familiariza con esta
   capa por primera vez.
3. El repositorio ya vive en GitHub: no hay costo de migración a otra plataforma de control
   de versiones para adoptar su CI/CD nativo.

Reconocemos, explícitamente, que esta decisión no sigue la señal de mercado dominante:
Jenkins aparece con más frecuencia que GitHub Actions en las ofertas de trabajo del stack
español relevado. El equipo se compromete a mantener documentado, como referencia (ADR-0001,
Anexo: sintaxis equivalente de Jenkins), cómo se vería el mismo pipeline en Jenkinsfile, para
no perder esa referencia si un cliente o empleador futuro lo requiere.

## Consecuencias

Positivas:
- El pipeline completo (fmt/validate/plan en cada PR, apply en cada merge, detección de
  drift programada) se puede construir y probar íntegramente en local, sin gastar un solo
  dólar, antes de tocar una cuenta de AWS real.
- La curva de aprendizaje del equipo es más corta que la de Jenkins, porque no hay que
  aprender Groovy ni administrar un servidor además del propio pipeline.
- Integración nativa con Pull Requests de GitHub: comentarios de PR, checks requeridos, y
  branch protection (ADR futuro, ver Módulo 6 de la guía interna de referencia) funcionan
  sin configuración adicional de terceros.

Negativas / riesgos aceptados:
- El equipo queda, en la práctica, menos alineado con la herramienta que más aparece en las
  ofertas de trabajo del mercado español relevado (Jenkins, 5 de 13 contra ~3 de 13 para
  GitHub Actions) — un riesgo de empleabilidad que el equipo decide aceptar, mitigado
  parcialmente por mantener documentada la sintaxis equivalente de Jenkins como referencia.
- Dependencia de GitHub como plataforma: migrar el control de versiones a GitLab o Bitbucket
  en el futuro requeriría reescribir todo `.github/workflows/` en la sintaxis de la nueva
  plataforma — el patrón de fondo (plan/revisión/apply) transferiría, pero no un solo archivo
  de configuración.
- `act` tiene limitaciones documentadas (no implementa emisión de tokens OIDC; ignora
  `environment:` a efectos de protección) que exigen que ciertas piezas de seguridad se
  verifiquen contra una cuenta de GitHub real antes de considerarse completamente probadas,
  no solo simuladas en local.

## Qué cambiaría si Andes Cargo tuviera un clúster de Kubernetes

Esta decisión cubre, exclusivamente, CI/CD de infraestructura declarada vía Terraform contra
servicios de AWS administrados por API (S3, DynamoDB, IAM, Lambda). El día que Andes Cargo
despliegue su propia aplicación —por ejemplo, una API de rastreo de envíos con réplicas
corriendo detrás de un balanceador de carga— sobre un clúster EKS, la herramienta correcta
para ESE despliegue específico ya no sería, necesariamente, GitHub Actions empujando un
`kubectl apply` desde un pipeline externo (push-based). La opción más alineada con las
prácticas estándar de la industria para Kubernetes sería adoptar ArgoCD o Flux: un operador
GitOps pull-based que corre dentro del propio clúster, elimina la necesidad de credenciales
de escritura viajando desde un sistema externo, y reconcilia el estado del clúster contra
Git de forma continua (incluyendo autocorrección, no solo detección).

Este ADR no decide esa migración por adelantado — se limita a documentar que, si ese día
llega, la decisión de herramienta para el despliegue de aplicación sobre Kubernetes merece
su propio ADR (ADR-000N: Elegir ArgoCD/Flux para GitOps de aplicación sobre EKS), evaluado
con la misma honestidad de mercado y de alcance que este documento.

## Alternativas consideradas y descartadas

- **GitLab CI**: descartada porque el código no vive en GitLab; adoptarla implicaría migrar
  de plataforma de control de versiones sin una razón técnica que lo justifique hoy.
- **CircleCI**: descartada porque no aparece nombrada en la evidencia directa de la auditoría
  de mercado de este ecosistema, y no ofrece una ventaja clara sobre GitHub Actions para un
  equipo que ya vive en GitHub.
- **Jenkins**: descartada, a pesar de ser la herramienta con mayor presencia en el stack
  español relevado, por el costo de mantener un servidor propio con el tamaño de equipo
  actual, y por no tener un equivalente directo a `act` para pruebas locales gratuitas
  durante la etapa de aprendizaje del equipo.

Qué hace que este ADR sea bueno, no solo largo

Fíjate en tres decisiones de escritura del documento de arriba, cada una deliberada:

La sección "Consecuencias" incluye riesgos reales, no solo beneficios. Un ADR que solo lista ventajas no es un registro honesto de una decisión — es propaganda de la decisión ya tomada. La fila sobre alineación con el mercado de trabajo español es, a propósito, incómoda: el equipo eligió una herramienta que aparece con menos frecuencia que la alternativa dominante, y el ADR lo dice sin suavizarlo, con el mismo dato exacto (5 de 13 contra ~3 de 13) que ya conoces de las lecciones 1 y 2 de este módulo.

La sección "Qué cambiaría con Kubernetes" no decide una migración que todavía no hace falta. Es tentador, al escribir un ADR, resolver de una vez todos los futuros posibles — este documento resiste esa tentación a propósito: documenta la frontera exacta de su propio alcance (CI/CD de infraestructura vía Terraform, no de aplicación vía Kubernetes) y deja explícito que, si esa situación llega, merece su propio ADR, no una cláusula improvisada dentro de este.

"Alternativas consideradas y descartadas" nombra por qué se descartó cada una, con una razón específica. No dice "elegimos GitHub Actions porque es mejor" — dice, para cada alternativa, la razón puntual de por qué no encajaba con las restricciones reales del equipo en este momento. Eso es lo que separa un ADR útil de una nota vaga: alguien que lea este documento en seis meses, o en otro equipo, puede evaluar si esas razones específicas siguen siendo válidas, sin tener que adivinar qué se consideró y qué no.

Errores comunes

Escribir un ADR después de la decisión, como justificación retroactiva vacía (el más común en la práctica real). Qué pasa: un equipo toma una decisión de forma informal, y alguien escribe el ADR semanas después, ya sin recordar con precisión qué alternativas se consideraron de verdad. Por qué pasa: escribir el ADR se siente como un trámite burocrático posterior, no como parte del proceso de decidir. Cómo detectarlo: si tu "Contexto" y "Alternativas consideradas" son vagos, sin números ni fuentes concretas. Cómo corregirlo: el ADR de esta lección funciona porque cita evidencia específica (5 de 13, la fuente exacta de VALIDACION.md) en el momento de la decisión, no una reconstrucción aproximada después. Si vas a escribir un ADR real algún día, hazlo mientras la decisión está fresca, con las fuentes a mano.

Confundir "Consecuencias" con "Beneficios" (de formato, ya señalado arriba). Qué pasa: alguien escribe la sección de consecuencias listando solo lo positivo, como si fuera una lista de argumentos a favor de la decisión ya tomada. Por qué pasa: después de defender una decisión en "Decisión", es natural seguir en modo defensivo en la sección siguiente. Cómo detectarlo: si tu sección de "Consecuencias" no tiene ningún ítem que un crítico honesto de la decisión podría señalar como un costo real. Cómo corregirlo: Nygard es explícito en esto — "todas las consecuencias deben listarse aquí, no solo las positivas". Un ADR sin riesgos ni costos reconocidos no es un registro de decisión, es marketing de la decisión.

Creer que un ADR reemplaza al código o a la documentación técnica (de alcance). Qué pasa: alguien piensa que, con el ADR escrito, ya no hace falta un README.md de pipeline (el que vas a escribir en el capstone del Módulo 8) ni comentarios en el propio YAML. Por qué pasa: ambos documentos hablan de "por qué" existe el pipeline. Cómo detectarlo: si buscas en un ADR instrucciones de "cómo correr act" o "qué hacer si apply.yml falla". Cómo corregirlo: un ADR documenta por qué se tomó una decisión, en un momento específico, con la información disponible en ese momento — no es un manual de operación. El README.md de pipeline del Módulo 8 (capstone) es el documento que sí cumple ese rol distinto: instrucciones prácticas, no historial de decisión.

Ejercicios

Ejercicio 1 — Identifica las cinco secciones sin mirar el ADR. De memoria, nombra las cinco secciones del formato estándar de un ADR, en el orden correcto, y qué pregunta responde cada una.

Ver solución

1. Título — ¿qué decisión es esta, en pocas palabras? 2. Estado — ¿esta decisión está propuesta, aceptada, obsoleta, o reemplazada por otra? 3. Contexto — ¿qué situación, con qué restricciones, llevó a necesitar esta decisión? 4. Decisión — ¿qué se decidió, exactamente, en voz activa? 5. Consecuencias — ¿qué resulta de haber tomado esta decisión, lo bueno y lo malo por igual?

Ejercicio 2 — Encuentra el riesgo reconocido más incómodo del ADR de Andes Cargo. Sin volver a leer el documento completo, ¿cuál es el riesgo que el ADR de esta lección reconoce explícitamente, que un documento menos honesto podría haber omitido?

Ver solución

Que la elección de GitHub Actions deja al equipo menos alineado con la herramienta que más aparece en las ofertas del mercado español relevado — Jenkins, en 5 de 13 ofertas contra ~3 de 13 para GitHub Actions. Es un riesgo real de empleabilidad para el propio equipo, no solo una limitación técnica menor, y el ADR lo nombra sin suavizarlo, con el mismo dato exacto citado en las lecciones 1 y 2 de este módulo, en vez de omitirlo o diluirlo en una frase vaga como "podría haber cierto desalineamiento con el mercado".

Ejercicio 3 — Escribe el título del próximo ADR de Andes Cargo. Según la sección "Qué cambiaría si Andes Cargo tuviera un clúster de Kubernetes" de este ADR, ¿qué título y número tendría el próximo ADR que la empresa necesitaría escribir si esa situación llegara a ocurrir?

Ver solución

ADR-0002: Elegir ArgoCD/Flux para GitOps de aplicación sobre EKS (el número exacto podría variar según cuántos ADR existan para entonces, pero el ADR de esta lección ya sugiere el título y el contenido central: una decisión GitOps pull-based, evaluada con la misma honestidad de mercado y de alcance que este documento, específicamente para el despliegue de una aplicación con réplicas corriendo — no para la infraestructura declarada vía Terraform que este ADR-0001 ya cubre).

Resumen y siguiente paso

En este proyecto escribiste el ADR completo de Andes Cargo: el documento real donde el equipo justifica, por escrito, su elección de GitHub Actions sobre Jenkins, GitLab CI y CircleCI, con la evidencia de mercado exacta citada (5 de 13 contra ~3 de 13), las tres razones concretas de la decisión, los riesgos reconocidos sin suavizar, y una sección honesta sobre qué cambiaría el día que exista un clúster de Kubernetes. Confirmaste, escribiéndolo tú mismo, qué hace que un ADR sea un registro de decisión útil —consecuencias reales, alternativas descartadas con razones específicas, alcance explícito— en vez de una justificación vacía escrita después de los hechos.

Antes de avanzar deberías poder: nombrar las cinco secciones del formato ADR y qué responde cada una; explicar por qué la sección de "Consecuencias" de un buen ADR incluye riesgos, no solo beneficios; y escribir, de memoria, el título del próximo ADR que Andes Cargo necesitaría si adoptara Kubernetes.

Con este proyecto se cierra el Módulo 7 completo: conociste tres herramientas de CI que resuelven el mismo problema con otra sintaxis (lección 2), dos mecanismos de GitOps genuinamente distintos (lecciones 3-4), un territorio de despliegue de aplicación que nunca visitaste (lección 5), la frontera exacta entre CI/CD de infraestructura y de aplicación (lección 6), la corriste con tus propias manos (lección 7), y la convertiste en un documento de decisión real (este proyecto). El Módulo 8 —el capstone final de toda la guía— retoma el pipeline técnico completo de Andes Cargo, no este ADR, para un recorrido end-to-end con un cambio real y un cambio rechazado.

Recursos

Michael Nygard — Documenting Architecture Decisions — el artículo original que definió el formato ADR de cinco secciones usado en esta lección.
npryce/adr-tools — GitHub — herramienta de línea de comandos para gestionar ADRs, fuente de la convención de carpeta doc/adr/ con archivos numerados.
src/paths/aws-cloud-ecosystem/VALIDACION.md (NIEVA, auditoría de mercado, jul-2026) — fuente exacta de toda la evidencia citada en el ADR de esta lección.
Módulo 7, lecciones 2 a 4 de esta guía — la fuente directa del contenido técnico del ADR: comparación de herramientas, ArgoCD/Flux, push vs. pull.

← Anterior7. Manos a la obra: un pipeline mínimo de aplicación, solo para contrastar Siguiente →1. Introducción al capstone: el pipeline completo, de punta a punta