Módulo 5: Gitops With Argocd
1. Introducción al módulo: la otra mitad de GitOps
Descripción
El Módulo 4 dejó a andes-cargo-status-api con una puerta HTTP real (Ingress) y un guardrail de red real (NetworkPolicy), las dos verificadas juntas en el proyecto anterior. Pero hay algo que no cambió desde el Módulo 2, y que este módulo va a cambiar de raíz: cada uno de los nueve manifiestos que existen hoy —namespace.yaml, deployment.yaml, service.yaml, configmap.yaml, secret.yaml, hpa.yaml, ingress.yaml y las dos NetworkPolicy— llegó al clúster porque tú corriste kubectl apply -f con tus propias manos, en tu propia terminal. Eso significa que andes-cargo-cluster, hoy, solo sabe lo que tú le dijiste directamente — no existe ningún lugar fuera de tu terminal donde alguien pueda ver "esto es lo que el clúster debería tener", y nada vigila que el clúster siga pareciéndose a esa intención con el tiempo. Este módulo resuelve exactamente eso: un repositorio Git real como única fuente de verdad, y un operador que vive dentro del clúster, comparándolo contra ese repositorio sin que nadie tenga que ejecutar nada a mano.
Conexión con el módulo
Esta guía no inventa el vocabulario de esta idea — lo hereda, con cita textual, de una guía hermana que ya lo dejó nombrado a propósito.
El hilo que cicd-and-gitops-on-aws-guide dejó abierto
cicd-and-gitops-on-aws-guide, en su Módulo 7 ("GitOps más allá de Terraform"), construyó un pipeline completo de infraestructura push-based: un git push a main dispara apply.yml, un job de GitHub Actions corre terraform apply, y el cambio llega a AWS porque un sistema externo a AWS —el runner de CI— empuja las credenciales hacia afuera para escribir ahí. Esa misma guía, en las lecciones 3 y 4 de ese módulo, nombró —sin instalar nada, con una frontera dura explicada— el mecanismo opuesto:
"En el modelo de Kubernetes con ArgoCD o Flux, un operador que corre dentro del clúster observa el repositorio Git constantemente y jala los cambios hacia adentro cuando los detecta — esto se llama pull-based."
Y, con más precisión todavía, en su lección 3:
"ArgoCD y Flux necesitan un clúster de Kubernetes real (...) para instalarse y correr — no son un binario que corre sobre tu HCL de Terraform, son controladores (...). Construir esto en profundidad —instalar un clúster, instalar ArgoCD dentro, conectar un repositorio, ver la primera sincronización— es exactamente el contenido de
kubernetes-and-eks-in-production-guide."
Esa cita te señala a ti, ahora mismo, en esta lección. cicd-and-gitops-on-aws-guide te dio el YAML de Application de ArgoCD verificado contra documentación oficial, pero nunca aplicado contra un clúster real —no podía, act simula runners de GitHub Actions, no clústeres de Kubernetes—. Este módulo toma ese mismo recurso, el mismo syncPolicy.automated con prune: true y selfHeal: true que esa guía solo pudo mostrar en papel, y lo instala, lo conecta a un repositorio Git real, y observa —con evidencia literal, no prometida— cómo converge un clúster de verdad.
Qué vas a construir, en una frase
Un repositorio Git real (servido por Gitea, corriendo dentro de tu propio clúster kind, sin ninguna cuenta de GitHub ni SaaS de por medio) que contiene los nueve manifiestos de Andes Cargo; un operador (ArgoCD, también corriendo dentro del clúster) que compara ese repositorio contra el estado real cada pocos segundos y corrige cualquier diferencia sin que nadie ejecute kubectl apply; y, como prueba final, un cambio real —subir de 3 a 5 las réplicas de andes-cargo-status-api— que vas a subir a Git con git push y ver aparecer en el clúster sin tocar kubectl para nada que no sea observar.
DE ESTO (Módulos 1-4) A ESTO (Módulo 5)
Tú, en tu terminal Un repositorio Git (Gitea, dentro del clúster)
│ │
│ kubectl apply -f deployment.yaml │ git push
│ kubectl apply -f service.yaml │
│ kubectl apply -f ingress.yaml ▼
│ ... (cada cambio, a mano) ┌───────────────┐
▼ │ ArgoCD │ compara cada
andes-cargo-cluster │ (Application) │ pocos segundos
(estado = lo último └───────┬───────┘
que aplicaste tú) │ corrige la diferencia
▼
andes-cargo-cluster
(estado = lo que Git dice,
siempre, sin intervención)Analogía: el mayordomo que revisa la lista, no el mensajero que toca la puerta
Piensa en los Módulos 1-4 como un dueño de casa que, cada vez que quiere cambiar algo —pintar una pared, mover un mueble—, tiene que hacerlo personalmente, con sus propias manos, en el momento exacto en que lo decide. Funciona, pero exige que el dueño esté presente cada vez. Este módulo introduce un mayordomo que vive dentro de la casa: cada pocos minutos, revisa una lista de pendientes que el dueño escribió en un cuaderno (el repositorio Git) y, si encuentra algo en la lista que la casa todavía no tiene —o algo que la casa tiene pero la lista ya no pide—, lo corrige él mismo, sin esperar a que el dueño se lo repita en persona. El dueño nunca deja de decidir qué va en la lista —Git sigue siendo la única fuente de verdad—; lo que cambia es que ya no tiene que estar físicamente presente, ejecutando cada cambio con sus propias manos, para que la casa refleje sus decisiones.
Mapa de este módulo
| # | Lección | Qué resuelve |
|---|---|---|
| 2 | GitOps pull-based: un operador que hace watch, no un pipeline que empuja | La diferencia técnica exacta con apply.yml de cicd-and-gitops-on-aws-guide: ahí un job de CI corre el cambio; aquí un Pod dentro del clúster lo busca solo |
| 3 | Manos a la obra: Gitea en el clúster | El repositorio Git real, corriendo dentro de andes-cargo-cluster, sin GitHub |
| 4 | Manos a la obra: instalando ArgoCD | El operador, corriendo dentro del clúster, con acceso a su UI |
| 5 | Anatomía de una Application de ArgoCD | source, destination, syncPolicy — sincronización manual frente a automática |
| 6 | Manos a la obra: sincronizando andes-cargo-status-api desde Git | La primera convergencia real, verificada con argocd app get |
| 7 | Estrategias de despliegue: rolling, blue/green y canary | RollingUpdate, ya configurado desde el Módulo 2, frente a lo que un clúster necesitaría agregar para blue/green o canary |
| 8 | Proyecto: un cambio en Git, reflejado solo | replicas: 3 → 5, subido con git push, sin un solo kubectl apply — el clúster converge por su cuenta |
Al cerrar este módulo, andes-cargo-cluster va a tener una fuente de verdad externa y verificable (un repositorio Git real, no tu historial de comandos), y un operador que la hace cumplir todo el tiempo — la pieza que, hasta hoy, ningún módulo anterior de esta guía construyó.
Errores comunes
Pensar que este módulo reemplaza kubectl (de expectativa, el más común al empezar GitOps). Qué pasa: alguien asume que, después de este módulo, kubectl apply deja de tener sentido para siempre. Por qué pasa: la promesa central del módulo —"nadie ejecuta kubectl apply a mano"— suena, mal leída, como "kubectl ya no se usa". Cómo detectarlo: si crees que vas a dejar de necesitar kubectl get/describe/logs en el resto de esta guía. Cómo corregirlo: lo que este módulo elimina es kubectl apply/create/delete como el mecanismo para cambiar el estado del clúster — kubectl sigue siendo, y va a seguir siendo durante el resto de esta guía, la herramienta para observar ese estado (get, describe, logs, top). ArgoCD no reemplaza kubectl: reemplaza el hábito de usarlo para escribir.
Creer que ArgoCD necesita GitHub o algún SaaS externo (de suposición, sin fundamento técnico). Qué pasa: alguien, al escuchar "repositorio Git", asume automáticamente una cuenta de GitHub, GitLab o Bitbucket. Por qué pasa: en la práctica de la industria, la mayoría de los repositorios Git que la gente usa a diario viven en un servicio de este tipo. Cómo detectarlo: si buscas dónde crear una cuenta antes de la lección 3. Cómo corregirlo: ArgoCD habla el protocolo Git estándar contra cualquier servidor que lo implemente — esta guía usa Gitea, un servidor Git open-source, corriendo dentro del propio clúster kind, con $0 y sin ninguna cuenta externa. La lección 3 lo construye de punta a punta.
Confundir "pull-based" con "más lento porque hay que esperar" como una desventaja sin matices (de simplificación, retomado de la lección 4 de cicd-and-gitops-on-aws-guide que ya lo advirtió). Qué pasa: alguien, al enterarse de que ArgoCD compara "cada pocos segundos" en vez de reaccionar al instante como un push, concluye que pull es estrictamente peor. Cómo detectarlo: si tu conclusión es "esto es más lento, por lo tanto peor". Cómo corregirlo: la lección 2 de este módulo retoma la tabla de implicaciones de seguridad que cicd-and-gitops-on-aws-guide ya construyó — la latencia de pull es real, pero se intercambia por eliminar una categoría entera de riesgo (nunca hay credenciales de escritura viajando hacia el clúster desde afuera). Ninguno de los dos mecanismos "gana" en abstracto.
Ejercicios
Ejercicio 1 — Cita la fuente de este módulo, de memoria. Sin volver a leer la sección correspondiente, escribe la frase textual de cicd-and-gitops-on-aws-guide que distingue push-based de pull-based, y nombra las dos herramientas que esa guía citó como implementaciones reales de pull.
Ver solución
"En el modelo de Kubernetes con ArgoCD o Flux, un operador que corre dentro del clúster observa el repositorio Git constantemente y jala los cambios hacia adentro cuando los detecta — esto se llama pull-based." Las dos herramientas: ArgoCD y Flux. Esta guía construye la primera de las dos; Flux se nombra por contraste en la lección 2, sin instalarse — el mismo patrón de honestidad que usó cicd-and-gitops-on-aws-guide con ambas.
Ejercicio 2 — Explica la analogía del mayordomo a un colega que nunca usó GitOps. En dos o tres frases, sin usar la palabra "GitOps", explica la diferencia entre lo que hiciste en los Módulos 1-4 y lo que este módulo va a construir.
Ver solución
Una explicación razonable: "Hasta ahora, cada vez que quería cambiar algo del clúster, tenía que escribir el comando exacto y ejecutarlo yo mismo, en el momento exacto en que lo decidía. A partir de este módulo, voy a escribir la decisión en un repositorio Git, y un programa que vive dentro del clúster va a revisar ese repositorio por su cuenta, todo el tiempo, y aplicar el cambio él mismo — sin que yo tenga que estar presente ejecutando nada en el momento en que el cambio ocurre."
Ejercicio 3 — Predice qué pasa si alguien borra un Pod a mano después de este módulo. Con lo que ya sabes de selfHeal (nombrado en la cita de cicd-and-gitops-on-aws-guide de esta lección, aunque todavía no lo hayas visto en acción), predice: si alguien corre kubectl delete pod contra un Pod de andes-cargo-status-api después de que ArgoCD esté sincronizando este namespace con selfHeal: true, ¿qué esperarías que pase?
Ver solución
El ReplicaSet del Deployment va a recrear el Pod de inmediato —ese es el comportamiento normal de un Deployment, ya visto desde el Módulo 2, sin relación con ArgoCD—. Lo que selfHeal: true agrega es una capa adicional: si en cambio alguien modificara directamente un campo del Deployment (por ejemplo, con kubectl scale o kubectl edit), ArgoCD detectaría esa diferencia contra lo que Git declara y la revertiría también, sin esperar a que nadie corrija el error a mano. La lección 5 de este módulo lo confirma con evidencia real, ejecutada.
Resumen y siguiente paso
Esta lección conectó este módulo con el hilo que cicd-and-gitops-on-aws-guide dejó abierto a propósito: el mecanismo pull-based de GitOps, nombrado con precisión en esa guía pero nunca construido porque exigía un clúster de Kubernetes real —exactamente lo que esta guía tiene desde el Módulo 1—. Viste el mapa completo de las ocho lecciones y la promesa final: un cambio subido a Git con git push, reflejado solo en el clúster, sin un solo kubectl apply.
Antes de avanzar deberías poder: citar la distinción push vs. pull de memoria; explicar por qué ArgoCD no necesita GitHub; y nombrar las tres piezas nuevas que este módulo va a instalar (Gitea, ArgoCD, y el objeto Application que los conecta).
Siguiente lección: GitOps pull-based, el mecanismo exacto. Ahí vas a ver, lado a lado, el diagrama que compara apply.yml (el pipeline que empuja) contra el operador que este módulo va a instalar (el que jala) — el mismo par de diagramas que cicd-and-gitops-on-aws-guide construyó en papel, ahora con el segundo a punto de dejar de ser papel.
Recursos
cicd-and-gitops-on-aws-guide(NIEVA), Módulo 7, lecciones 3 y 4 — la fuente textual completa de la distinción push/pull y del YAML deApplicationque este módulo instala de verdad.- Argo CD — Documentation — documentación oficial de la herramienta que este módulo instala y opera de punta a punta.
- Gitea — Documentation — documentación oficial del servidor Git que sirve de repositorio para todo este módulo.
kubernetes-and-eks-in-production-guide(NIEVA), Módulo 4, lección 8 — el estado exacto del que parte este módulo:andes-cargo-status-apiconIngressyNetworkPolicyreales, nueve manifiestos aplicados a mano.