Módulo 1: Why Cicd And Gitops
1. Introducción a la guía: de la terminal al pipeline
Descripción
Si completaste terraform-and-iac-guide, ya sabes declarar infraestructura. El proyecto andes-cargo-infra/ existe, con sus módulos s3-bucket e iam-role, y con los cuatro recursos canónicos de Andes Cargo —el bucket andes-cargo-shipment-docs, la tabla Shipments, los roles LambdaManifestProcessorRole y AppServerRole, y la función process-shipment-manifest— declarados en HCL. Sabes leer un plan, sabes por qué el state es la fuente de verdad, y corriste terraform apply más veces de las que puedas contar. Hay una frase exacta que abrió esa guía, y que esta guía cumple: "primero entiendes qué hace cada comando, después lo automatizas". Ya entendiste qué hace apply. Esta guía te enseña a dejar de escribirlo tú.
Esta guía —CI/CD y GitOps sobre AWS— no declara un solo recurso de negocio nuevo. No hay una quinta pieza de Andes Cargo. Lo que cambia, otra vez, es el método: en vez de que una persona teclee terraform apply desde su laptop, un pipeline lo va a hacer por ella —después de que otra persona revisó el cambio, y solo cuando ese cambio llegó a la rama main por un pull request, no por accidente. Al terminar esta guía vas a tener un repositorio real donde un git push dispara automáticamente fmt, validate y plan; donde el plan es lo que se revisa antes de fusionar; y donde el apply corre solo, sin que nadie lo teclee, exactamente sobre el plan que se aprobó.
Conexión con el módulo
Este Módulo 1 tiene el mismo trabajo que tuvo el primer módulo de terraform-and-iac-guide: tender el puente. Las lecciones 2 a 5 nombran, con precisión, el problema real del apply manual (no en abstracto — en los términos exactos de lo que ya viviste), definen qué es CI frente a CD-entrega frente a CD-despliegue, qué es GitOps, y por qué esta guía elige GitHub Actions entre varias alternativas de mercado reales. Las lecciones 6 y 7 son manos a la obra puras: instalas act —la herramienta que va a correr cada workflow de esta guía en Docker, en tu máquina, gratis— y corres tu primer workflow de punta a punta. La lección 8, el proyecto de este módulo, prepara andes-cargo-infra/ para recibir su primer pipeline real: lo inicializa como repositorio Git si hace falta, crea .github/workflows/, y deja LocalStack corriendo. Con eso, entras al Módulo 2 con todo el terreno preparado para escribir el primer workflow que de verdad toca Andes Cargo.
Qué asume esta guía (y qué no vuelve a explicar)
Esta guía no es un punto de entrada a Terraform ni a AWS. Asume, sin volver a explicarlo, todo lo que construiste en terraform-and-iac-guide (y, de forma transitiva, en aws-core-services-guide):
- Sabes qué es HCL, qué hace
resource/variable/output/locals, y cómo se ve el proyectoandes-cargo-infra/por dentro — porque lo escribiste, módulo por módulo, hasta su capstone. - Sabes qué es el
statede Terraform, por qué es la fuente de verdad, y qué pasa si dosapplylo tocan al mismo tiempo. - Sabes qué es LocalStack, cómo levantarlo con Docker, y por qué el account ID
000000000000aparece en cada ARN de tu laboratorio. - Sabes moverte con Git a nivel de uso:
init,add,commit,branch,merge,revert— degit-github-guide, vinculada, no re-enseñada aquí.
Si algo de esa lista no te suena firme, esa es la señal de volver a la guía correspondiente antes de seguir — ninguna lección de aquí en adelante vuelve a explicar qué es un resource de Terraform o cómo se resuelve un conflicto de merge, solo cómo automatizarlos dentro de un pipeline.
Lo que esta guía sí enseña, y que ninguna de las anteriores cubrió a propósito: integración continua (CI) frente a entrega continua y despliegue continuo (las dos caras de "CD"); GitOps como principio; la anatomía completa de un workflow de GitHub Actions; el patrón estándar de HashiCorp/GitHub para IaC en CI/CD; manejo de secretos y federación OIDC; ambientes y aprobaciones; detección de drift programada; el patrón de rollback de infraestructura; y branch protection.
El mapa completo: los 8 módulos de esta guía
CI/CD Y GITOPS SOBRE AWS — LOS 8 MÓDULOS
M1 Por qué CI/CD y GitOps ← estás aquí: instalar act, primer workflow
M2 Anatomía de un workflow sintaxis YAML completa, act -e, secretos
M3 El pipeline de IaC fmt/validate/plan en cada PR (mitad de CI)
M4 Secretos, ambientes e identidad GitHub Secrets, OIDC (nombrado), dev/prod
M5 Apply en merge apply.yml encadenado, concurrencia, drift
M6 Rollback y redes de seguridad git revert, branch protection, guardrail
M7 GitOps más allá de Terraform Jenkins/GitLab CI, ArgoCD/Flux (nombrados)
M8 Capstone: el pipeline completo un cambio real y un cambio rechazado| # | Módulo | Qué construye | Pieza del pipeline de Andes Cargo |
|---|---|---|---|
| 1 | Por qué CI/CD y GitOps | act instalado, primer workflow corrido de punta a punta | (preparación — .github/workflows/ vacío, cero YAML de negocio) |
| 2 | Anatomía de un workflow | on/jobs/steps/runs-on/uses, simular eventos y secretos con act | hello-andes-cargo.yml, la primera Action real conectando al runner |
| 3 | El pipeline de IaC | fmt/validate/plan como pasos de CI, el plan como evidencia de revisión | ci.yml completo |
| 4 | Secretos, ambientes e identidad | GitHub Secrets, OIDC nombrado, dev/prod como Environments | El plan de secretos/ambientes de Andes Cargo |
| 5 | Apply en merge | apply.yml disparado por push a main, needs, concurrency, schedule | apply.yml + drift.yml |
| 6 | Rollback y redes de seguridad | git revert sobre HCL, branch protection, un guardrail real sobre el plan | El guardrail que protege la tabla Shipments |
| 7 | GitOps más allá de Terraform | Contraste con Jenkins/GitLab CI, push vs. pull, frontera con CI/CD de app | El ADR de herramienta de Andes Cargo |
| 8 | Capstone | El pipeline completo, probado con un cambio real y uno rechazado | andes-cargo-infra/ con .github/workflows/ como entregable de portfolio |
Fíjate en la progresión: primero aprendes por qué y con qué herramienta vas a probarlo gratis (M1-M2), después construyes la mitad de CI (M3), después quién puede aplicar qué y con qué llave (M4), recién ahí la mitad de CD (M5), y cierras con las redes de seguridad (M6) y el panorama más amplio (M7) antes del capstone (M8).
El mapa de este módulo: las 8 lecciones
| # | Lección | Qué practicas |
|---|---|---|
| 1 | Introducción (esta) | El mapa completo, qué se hereda de terraform-and-iac-guide, qué es genuinamente nuevo |
| 2 | El problema del apply manual | Recap honesto: ¿quién lo corrió? ¿con qué credenciales? ¿qué pasa si esa persona no está? |
| 3 | CI, CD y CD: tres cosas, una sigla | Integración continua vs. entrega continua vs. despliegue continuo |
| 4 | Qué es GitOps | Origen del término, Git como fuente de verdad, el principio, no la herramienta |
| 5 | GitHub Actions y sus alternativas | GitLab CI, CircleCI, Jenkins, con honestidad de mercado |
| 6 | Manos a la obra: instalando act | Ejecutado: act --version, .actrc, Docker verificado |
| 7 | Manos a la obra: tu primer workflow local | Ejecutado: un "hola mundo" corrido de punta a punta con act |
| 8 | Proyecto: arrancando el pipeline de Andes Cargo | Ejecutado: andes-cargo-infra/ como repo Git, .github/workflows/ creado, LocalStack arriba |
Lo único genuinamente nuevo: artefactos de la capa de pipeline
Esta guía no inventa un caso de negocio nuevo, y tampoco declara un solo recurso HCL de negocio nuevo. Los cuatro recursos que ya conoces de Andes Cargo siguen siendo, nombre por nombre, los mismos: el bucket andes-cargo-shipment-docs, la tabla Shipments, los roles LambdaManifestProcessorRole y AppServerRole, y la función process-shipment-manifest. Los envíos de ejemplo siguen siendo los mismos tres: 4471 Perú→Chile, 4472 Colombia→Ecuador, 4473 Chile→Perú. Misma cuenta 000000000000, misma región us-east-1.
Lo único nuevo son artefactos de la capa de pipeline, nunca de negocio, siempre en inglés:
.github/workflows/ci.yml(plan en PR, Módulo 3),apply.yml(apply en merge, Módulo 5),drift.yml(detección programada, Módulo 5)..actrcen la raíz del repositorio — la imagen de runner pineada, y más adelante un flag de red para hablar con LocalStack..github/act-events/pr-event.jsonypush-event.json— no son un estándar de GitHub, son propios de esta guía, para simular eventos conact -esin necesitar una cuenta real (Módulo 2)..secrets— gitignorado desde el momento exacto en que aparece (Módulo 2) — con las credenciales dummytest/testde LocalStack.- Un
README.mdde pipeline dentro deandes-cargo-infra/, el entregable de portfolio del capstone (Módulo 8).
Nada de esto reemplaza los cuatro nombres canónicos de Andes Cargo. Cuando el Módulo 3 corra terraform plan dentro de un workflow, el bucket que ese plan describe va a seguir llamándose andes-cargo-shipment-docs — ahora dentro de un step de YAML, no de una terminal.
Nota de arranque limpio: dos dependencias, no una
terraform-and-iac-guide ya te enseñó que el plan Hobby de LocalStack no persiste recursos entre reinicios del contenedor, y que esta guía no asume que tu sesión anterior sigue viva. Esta guía hereda esa misma precaución, con una capa extra: además de Docker corriendo LocalStack, ahora necesitas Docker corriendo también los contenedores efímeros que act crea para simular cada job de GitHub Actions. Son usos distintos del mismo Docker —LocalStack es un contenedor de larga vida que arrancas una vez y dejas corriendo; los contenedores de act son efímeros, uno nuevo por cada corrida de un job, que se destruyen solos al terminar—. La lección 6 de este módulo verifica ambos usos por separado, antes de mezclarlos.
El compromiso de $0, con una pieza más: act
Terraform contra LocalStack ya te costaba $0. GitHub Actions, corrido en los runners hospedados reales de GitHub, tiene minutos gratis limitados y después se cobra por minuto — pero esta guía no usa esos runners en ningún momento. act (nektos/act) ejecuta el mismo YAML que correría en github.com, en Docker, en tu máquina, sin tocar ningún runner hospedado ni requerir una cuenta de GitHub. Es $0 por la misma razón que LocalStack lo es: el trabajo real ocurre en un contenedor que tú controlas, no en la infraestructura de un proveedor que te factura por uso.
Vas a instalarlo en la lección 6 de este módulo y correr tu primer workflow con él en la lección 7 — con salida real, no una simulación en prosa.
Qué SÍ se ejecuta, y qué es representativo (la honestidad completa, desde el inicio)
Esta guía sostiene la misma regla dura que terraform-and-iac-guide: nada se simula en prosa; si un workflow aparece en una lección, corrió con act para escribirla. Hay exactamente cinco excepciones, cada una con una razón técnica investigada y verificada —no una limitación asumida—, y cada una etiquetada en el momento exacto en que aparece, nunca escondida:
| No se ejecuta aquí | Por qué (razón técnica exacta) | Dónde aparece, etiquetado |
|---|---|---|
| OIDC federado hacia AWS real | act no implementa emisión de tokens OIDC; tampoco hay una cuenta AWS real contra la cual federar | Módulo 4 |
| Environments con aprobación requerida | act ignora environment: a efectos de protección — corre el job igual, sin esperar aprobación (issue abierto de nektos/act) | Módulo 4 |
| Branch protection rules | Es configuración de repositorio, no un workflow — no hay YAML que act pueda ejecutar | Módulo 6 |
Comentar el plan en un PR real | Requiere un PR real con número asignado por GitHub | Módulo 3 (con su equivalente real ejecutable: $GITHUB_STEP_SUMMARY) |
| Runners hospedados / cuenta de GitHub real | Fuera del alcance $0 de esta guía por diseño | Módulo 8 |
Todo lo demás —incluidos los tres workflows completos de Andes Cargo (ci.yml, apply.yml, drift.yml) y el guardrail del Módulo 6— corre de verdad, con act, contra el mismo LocalStack que ya conoces.
Lo que NO vas a ver en esta guía
Para que sepas desde ya qué esperar: esta guía no construye el GitOps pull-based de Kubernetes con ArgoCD o Flux (eso es kubernetes-and-eks-in-production-guide — aquí se nombran, en el Módulo 7, por contraste), no construye OIDC de punta a punta contra una cuenta AWS real ni SAST/supply-chain (cloud-security-and-guardrails-guide), no enseña CI/CD de código de aplicación —tests, build, deploy de un artefacto— más allá de un contraste corto y deliberado (cicd-python-backend-guide, testing-in-cicd-guide), no construye estrategias de despliegue de aplicación como blue/green o canary (kubernetes-and-eks-in-production-guide, aws-serverless-and-containers-guide), y no cubre SRE del propio pipeline —SLO, on-call, postmortems— (sre-and-incident-response-guide). Todo apply de esta guía sigue corriendo contra LocalStack, con act, a propósito: primero entiendes el pipeline completo en un laboratorio $0 y reproducible, después —en otra guía— lo llevas contra una cuenta real.
Errores comunes
Asumir que este módulo va a declarar un recurso de Andes Cargo nuevo (de expectativa). Qué pasa: alguien que ya hizo terraform-and-iac-guide espera ver un quinto servicio de AWS, o una arquitectura más grande. Por qué pasa: es el patrón que siguieron otras guías del ecosistema, donde cada guía nueva sí ampliaba el caso de negocio. Cómo detectarlo: si buscas "¿qué recurso HCL nuevo vamos a escribir?" en vez de "¿cómo va a correr el mismo apply sin que yo lo teclee?". Cómo corregirlo: el valor de esta guía no está en un recurso nuevo — está, otra vez, en el método. Terminas con exactamente los mismos cuatro recursos de siempre, ahora aplicados por un pipeline.
Creer que act es "casi como" GitHub Actions, una aproximación (conceptual). Qué pasa: alguien asume que act es un simulador que interpreta el YAML de forma aproximada, y que lo que corre ahí no es "de verdad" un workflow de GitHub Actions. Por qué pasa: la palabra "local" suena, por default, a "simplificado". Cómo detectarlo: si crees que el .github/workflows/ci.yml que vas a escribir en esta guía necesitaría reescribirse para correr en un repositorio real de GitHub. Cómo corregirlo: no necesita cambiar una sola línea — act ejecuta el mismo YAML, con las mismas Actions reales del Marketplace, dentro de Docker. Lo que cambia no es el workflow, es quién dispara el evento (tú, a mano, en vez de GitHub) y dónde corre el contenedor (tu máquina, en vez de un runner hospedado).
Saltarse terraform-and-iac-guide porque "esto es solo YAML" (de flujo). Qué pasa: alguien sin experiencia previa en Terraform intenta empezar directamente aquí, y se encuentra con un step que corre terraform plan sin entender qué significa esa salida. Por qué pasa: un workflow de CI/CD es, en la superficie, "solo YAML" — pero ese YAML orquesta comandos de Terraform que esta guía da por sabidos. Cómo detectarlo: si una palabra como "state" o "provider" te resulta desconocida en el Módulo 3. Cómo corregirlo: vuelve a terraform-and-iac-guide. Esta guía enseña cuándo y quién corre terraform apply, no qué hace cada comando de Terraform.
Ejercicios
Ejercicio 1 — Traduce el cambio de método a tus palabras. Sin usar todavía los términos "CI", "CD" ni "GitOps" (los vas a formalizar en las lecciones 3 y 4), describe en dos o tres frases qué es, concretamente, lo que cambia entre terminar terraform-and-iac-guide y terminar esta guía.
Ver solución
Una respuesta completa suena, más o menos, así: "En terraform-and-iac-guide, yo era la única persona entre el código HCL y la infraestructura real: yo tecleaba terraform plan, yo lo leía, yo tecleaba apply. En esta guía, ese mismo plan y ese mismo apply los corre un pipeline automáticamente cuando hago un git push o cuando un cambio se fusiona a main — el código sigue siendo el mismo, la infraestructura resultante sigue siendo la misma, pero ya no soy yo, desde mi terminal, quien decide en el momento ejecutar el comando: el proceso queda definido de antemano, en un archivo versionado, no en mi memoria de qué comando tocaba correr." La pieza clave: el HCL no cambia — cambia quién y cuándo lo aplica.
Ejercicio 2 — Ubica las cinco excepciones representativas. Sin mirar hacia atrás en esta lección, nombra de memoria las cinco cosas que esta guía no ejecuta con act, y en qué módulo aparece cada una.
Ver solución
Módulo 3: comentar el plan directamente en un Pull Request real (se ejecuta el equivalente real disponible: $GITHUB_STEP_SUMMARY). Módulo 4: OIDC federado hacia AWS real, y Environments con aprobación requerida. Módulo 6: branch protection rules. Módulo 8: cualquier cosa que dependa de runners hospedados o una cuenta de GitHub real. Si recordaste las cinco y a cuál de "OIDC no implementado por act", "environment: ignorado por act", "es configuración de repositorio, no YAML", "necesita un PR real", y "fuera del alcance $0" corresponde cada una, ya tienes clara la honestidad de ejecución de esta guía.
Ejercicio 3 — El compromiso de $0, en la capa de CI/CD. Un colega que ya sabe cómo funciona el $0 de LocalStack te pregunta: "¿No necesito una cuenta de GitHub y minutos de Actions para aprender esto?". Respóndele en dos o tres frases, explicando por qué la respuesta es no.
Ver solución
Una respuesta completa suena, más o menos, así: "No — act ejecuta el mismo YAML de un workflow de GitHub Actions dentro de contenedores Docker en tu propia máquina, sin tocar ningún runner hospedado de GitHub ni requerir una cuenta. El único costo real es el mismo que ya tenías con LocalStack: Docker corriendo en tu computadora. Lo único que no puedo demostrarte con esta configuración son cinco cosas muy específicas —como la aprobación real de un Environment— que dependen, por diseño, de una cuenta de GitHub real; todas están nombradas y explicadas quí, ninguna se esconde."
Resumen y siguiente paso
En esta lección viste el mapa completo de los 8 módulos de esta guía, confirmaste qué se hereda sin repetirse de terraform-and-iac-guide (los cuatro recursos de Andes Cargo, el state, LocalStack, el compromiso de $0), y qué es genuinamente nuevo (CI/CD, GitOps, la anatomía de un workflow, secretos y OIDC nombrado, ambientes, rollback, branch protection). También viste, con una tabla completa, exactamente qué cinco cosas esta guía no ejecuta con act y por qué —la honestidad de ejecución declarada desde el primer módulo, no descubierta a mitad de camino.
Antes de avanzar deberías poder: nombrar los cuatro recursos heredados de Andes Cargo; explicar en una frase qué cambia entre terraform-and-iac-guide y esta guía (el método, no el resultado); y nombrar las cinco excepciones representativas y su razón técnica.
Lo que todavía falta es nombrar el problema con precisión. La lección 2 vuelve, con honestidad total, al momento exacto donde el apply manual empieza a doler de verdad — con una pregunta que terraform-and-iac-guide nunca te obligó a responder.
Recursos
- GitHub Docs — GitHub Actions — la documentación oficial de la herramienta que instalas y usas en toda esta guía.
- nektosact.com — User Guide — la documentación oficial de
act, la herramienta $0 que corre esos workflows en tu máquina. terraform-and-iac-guide(NIEVA) — el prerequisito completo de esta guía: HCL, el cicloinit/plan/apply/destroy, elstate, y el proyectoandes-cargo-infra/, todos asumidos y no re-explicados aquí.src/paths/aws-cloud-ecosystem/VALIDACION.md(NIEVA, auditoría de mercado, jul-2026) — la evidencia que motiva esta guía: CI/CD como el faltante más citado del ecosistema, 13 de 13 ofertas leídas.