ArgoCD[1] ha pasado en pocos años de proyecto interesante a práctica de despliegue estándar para Kubernetes. GitOps (donde el repositorio Git es la única fuente de verdad del estado deseado del cluster) ha demostrado funcionar mejor que las pipelines push tradicionales para muchos equipos. Esta guía cubre los principios, lo que ArgoCD hace bien, los errores que se ven en producción y la comparativa con Flux.

Puntos clave

  • GitOps no es solo "desplegar desde Git": su esencia es la reconciliación continua que corrige el drift automáticamente.

  • ArgoCD destaca por su UI rica, multi-tenancy maduro y soporte amplio de Helm, Kustomize y YAML plano.

  • El patrón app-of-apps permite gestionar el cluster entero de forma declarativa.

  • Los secretos nunca van en el repositorio de configuración: usa Sealed Secrets o External Secrets Operator.

  • El sync mode correcto para producción al inicio es manual; escala hacia auto-sync conforme crece la confianza.

Los cuatro principios reales de GitOps

El grupo de trabajo OpenGitOps[2] formalizó en 2021 los cuatro principios de GitOps bajo la CNCF:

  • Declarativo: el sistema entero se describe declarativamente (YAML de Kubernetes, manifiestos Helm/Kustomize), no como secuencia de comandos.

  • Versionado e inmutable: el estado deseado vive en Git. Cada cambio es un commit auditable.

  • Pulled automáticamente: agentes en el cluster tiran del repositorio y aplican cambios. No hay push externo desde CI.

  • Reconciliación continua: el agente compara estado real vs deseado constantemente y corrige el drift.

La implicación más importante es la cuarta. Si alguien edita un recurso a mano (kubectl edit), ArgoCD lo revierte al estado del Git. Esa diferencia con las pipelines tradicionales es el valor central.

Por qué ArgoCD ha ganado adopción

Aceptado como proyecto incubado por la CNCF en 2020 y graduado en 2022, ArgoCD es la opción más popular porque combina varias ventajas:

  • UI excelente: vista visual de aplicaciones, sus recursos, estado de salud y diff entre Git y cluster.

  • Multi-tenancy serio: soporta múltiples equipos con permisos granulares vía RBAC + projects.

  • Sync policies flexibles: manual, auto, con prune, con self-heal; cada combinación sirve para escenarios distintos.

  • Soporte amplio de herramientas: Helm, Kustomize, YAML plano y Jsonnet coexisten en el mismo cluster.

  • App-of-apps pattern: una app de ArgoCD que despliega otras apps, útil para gestionar el cluster entero declarativamente.

  • Sync waves y hooks: control sobre orden de despliegue cuando importa (CRDs antes que recursos que los usan).

Logotipo de GitHub Actions, la plataforma de CI que habitualmente alimenta los pipelines que actualizan el repositorio de configuración de ArgoCDLogotipo de GitHub Actions, la plataforma de CI que habitualmente alimenta los pipelines que actualizan el repositorio de configuración de ArgoCD (Imagen: Mohamed Hassan, CC BY-SA 4.0, vía Wikimedia Commons)

Estructura típica del repositorio

config-repo/
├── applications/
│   ├── prod/
│   │   ├── app-a.yaml      # ArgoCD Application apuntando a manifests
│   │   └── app-b.yaml
│   └── staging/
│       └── ...
├── manifests/
│   ├── app-a/
│   │   ├── base/           # Kustomize base
│   │   └── overlays/
│   │       ├── prod/
│   │       └── staging/
│   └── app-b/
│       └── helm/           # Chart o values de Helm
└── argocd-bootstrap/       # Configuración del propio ArgoCD

Patrones que funcionan bien:

  • Separar app code de configuración: cambios de configuración no requieren rebuild de imagen.

  • Directorios por entorno (overlays Kustomize) en lugar de branches, lo que facilita ver diferencias.

  • Image automation con commits automatizados: ArgoCD Image Updater detecta nuevas imágenes y commitea al config repo.

Sync policies: cuándo usar cada una

  • Manual sync: alguien pulsa "Sync" tras cambios en Git. Recomendado en producción inicialmente.

  • Auto-sync sin prune: aplica cambios pero no borra recursos que desaparecen del Git. Conservador.

  • Auto-sync con prune: aplica todos los cambios y borra lo que ya no está en Git. Peligroso si alguien borra algo accidentalmente.

  • Self-heal: además de aplicar Git, revierte cualquier cambio manual. GitOps estricto real.

Recomendación progresiva: manual en producción al principio, auto-sync sin prune en staging, self-heal en dev. Migrar producción a auto-sync controlado conforme crece la confianza del equipo.

Errores comunes en producción

Los errores que más se ven en proyectos reales:

  • Self-heal sin disciplina de equipo: si alguien cambia algo a mano para depurar y ArgoCD lo revierte al minuto, hay frustración. Política clara: cambios manuales solo en emergencias documentadas.

  • Secretos en Git: nunca. Usa Sealed Secrets, External Secrets Operator o similar.

  • Repositorios de configuración monstruosos: un único repo con 200 apps es lento de sincronizar. Divide por dominio o equipo.

  • Sync waves mal usadas: demasiadas dependencias entre waves complica los despliegues. Mantén el grafo simple.

  • CRDs como app normal: las CRDs deben estar antes que los recursos que las usan. Usa sync waves o una app separada de bootstrap.

  • Sin backups de la configuración de ArgoCD: ArgoCD mismo debe estar en Git (app-of-apps). Si el cluster muere, recuperas haciendo argocd app create apuntando al config repo.

  • Cluster admin para todos: configura proyectos ArgoCD con permisos limitados por equipo y namespace.

Logotipo de Prometheus, la herramienta de métricas que complementa ArgoCD en la observabilidad del stack de despliegueLogotipo de Prometheus, la herramienta de métricas que complementa ArgoCD en la observabilidad del stack de despliegue (Imagen: Alexander Schwartz (ahus1), Apache License 2.0, vía Wikimedia Commons)

Comparativa con Flux

Flux[3] es la otra herramienta GitOps madura. Las diferencias prácticas más relevantes:

  • UI: ArgoCD tiene UI rica nativa; Flux la tiene más limitada (mejorando con Weave GitOps).

  • Multi-tenancy: ArgoCD usa projects; Flux usa namespaces nativos de Kubernetes.

  • Filosofía: ArgoCD se siente más "aplicación"; Flux se siente más "controllers en el cluster".

  • Image automation: Flux la tiene nativa; ArgoCD requiere el componente Image Updater.

  • Multi-cluster: ArgoCD soporta gestionar múltiples clusters desde una instancia; Flux asume una instancia por cluster.

Lee la comparativa completa Flux vs ArgoCD para un análisis más detallado. Ambos son graduados de la CNCF y elecciones sólidas; la diferencia está en qué encaja mejor con tu equipo.

Conclusión

ArgoCD ha consolidado GitOps como práctica de despliegue madura para Kubernetes. Bien implementado (con disciplina de equipo, secretos gestionados aparte y sync policies adecuadas) mejora la confiabilidad de los despliegues, el audit trail y la velocidad de recuperación. Mal implementado (con secretos en Git, configuración monstruosa y sin backups) solo añade otra capa de complejidad. La diferencia está en los detalles operativos, no en la herramienta.

Fuentes:

  1. ArgoCD — Documentación oficial[1]
  2. FluxCD — Documentación oficial[3]
  3. OpenGitOps — Los cuatro principios de GitOps (v1.0)[2]
  4. CNCF — ArgoCD y Argo Workflows alcanzan el estatus de graduado[4]

Preguntas frecuentes

¿Qué sync policy de ArgoCD debo usar en producción al empezar?

Manual: alguien pulsa Sync tras los cambios en Git. La recomendación progresiva es manual en producción al principio, auto-sync sin prune en staging (aplica cambios pero no borra recursos que desaparecen del Git) y self-heal en dev, que además revierte cualquier cambio manual. El auto-sync con prune es peligroso si alguien borra algo por accidente. Migra producción a auto-sync controlado conforme crece la confianza del equipo.

¿Qué pasa si alguien edita un recurso a mano con kubectl edit en un cluster gestionado por ArgoCD?

Con self-heal activado, ArgoCD detecta el drift en la reconciliación continua y revierte el recurso al estado declarado en Git, en cuestión de un minuto. Es el valor central de GitOps frente a las pipelines push, pero sin disciplina de equipo genera frustración cuando alguien cambia algo para depurar y desaparece. La política debe ser clara: cambios manuales solo en emergencias documentadas.

¿Cómo gestiono los secretos si toda la configuración vive en Git?

Los secretos nunca van en el repositorio de configuración. Usa Sealed Secrets o External Secrets Operator para que el cluster los obtenga cifrados o desde un almacén externo. Otros errores frecuentes en producción son un único repo monstruoso con 200 apps, lento de sincronizar y mejor dividido por dominio o equipo, no tener el propio ArgoCD en Git mediante el patrón app-of-apps, y dar cluster admin a todos en lugar de proyectos con permisos por equipo y namespace.

Fuentes

  1. ArgoCD
  2. grupo de trabajo OpenGitOps
  3. Flux
  4. CNCF — ArgoCD y Argo Workflows alcanzan el estatus de graduado