GitOps es un modelo de operación donde el estado deseado del sistema se declara en un repositorio versionado y un agente que corre dentro del entorno lo obtiene solo y lo reconcilia de forma continua con lo que está corriendo. La especificación de OpenGitOps lo resume en cuatro principios: declarativo, versionado e inmutable, obtenido automáticamente y reconciliado de forma continua. Argo CD, según su documentación, es «una herramienta declarativa de entrega continua GitOps para Kubernetes»: compara lo que hay en el clúster contra lo que dice el repositorio, marca las diferencias y puede corregirlas. La ganancia central: el pipeline deja de necesitar credenciales del clúster, y la deriva se vuelve visible.
Ver índice de contenidos
Los cuatro principios
El grupo de trabajo de GitOps de la CNCF publicó la especificación OpenGitOps, cuyos principios en su versión 1.0.0 son estos cuatro. Están citados textualmente porque cada uno descarta una implementación incompleta:
- Declarativo«Un sistema gestionado por GitOps debe tener su estado deseado expresado de forma declarativa.»
- Versionado e inmutable«El estado deseado se almacena de una manera que impone inmutabilidad, versionado y retiene un historial completo de versiones.»
- Obtenido automáticamente«Agentes de software obtienen automáticamente las declaraciones de estado deseado desde el origen.»
- Reconciliado de forma continua«Agentes de software observan continuamente el estado real del sistema e intentan aplicar el estado deseado.»
Los dos primeros son los que casi todo el mundo ya cumple sin proponérselo: hay YAML y están en Git. Los que hacen la diferencia son el tercero y el cuarto. Sin agente que obtenga y reconcilie, hay control de versiones, no GitOps, y esa distinción no es semántica: define quién tiene las credenciales del clúster y si la deriva se detecta o no.
Empujar contra reconciliar
En el modelo tradicional de empuje, el pipeline de integración continua guarda credenciales del clúster y ejecuta el despliegue desde afuera. Funciona, y tiene dos problemas que se pagan tarde. El primero es de seguridad: un secreto con permisos de escritura sobre producción vive en el sistema de integración continua, que es un objetivo muy visitado. El segundo es de conocimiento: el pipeline sabe lo que quiso aplicar, no lo que quedó corriendo.
En el modelo de reconciliación, la dirección se invierte. El pipeline construye la imagen y actualiza el repositorio de configuración; ahí termina su trabajo. Dentro del clúster, un agente obtiene ese estado deseado, lo compara con el real y aplica la diferencia, una y otra vez. Las credenciales del clúster nunca salen del clúster, y la pregunta «¿lo que está corriendo es lo que dice el repositorio?» tiene por primera vez una respuesta automática.
Qué es Argo CD
La documentación oficial lo define en una línea: «Argo CD es una herramienta declarativa de entrega continua GitOps para Kubernetes». Y explica su premisa: «las definiciones, configuraciones y entornos de las aplicaciones deben ser declarativos y estar versionados», y «el despliegue y la gestión del ciclo de vida de las aplicaciones debe ser automatizado, auditable y fácil de entender».
Funciona «como un controlador de Kubernetes que monitorea continuamente las aplicaciones en ejecución y compara el estado vivo actual contra el estado objetivo deseado». Sus tres componentes principales, según el manual de operación:
| Componente | Qué hace |
|---|---|
| Servidor de API | Expone la interfaz gRPC y REST que usan la consola web y la línea de comandos, gestiona credenciales de repositorios y clústeres, aplica autenticación y autorización, y recibe los avisos de los servicios de Git |
| Servidor de repositorio | Mantiene una copia local de los repositorios y genera los manifiestos a partir de la URL, la revisión, la ruta y las opciones de plantilla |
| Controlador de aplicaciones | Compara el estado vivo contra el objetivo, marca la diferencia, puede corregirla y ejecuta los enganches de PreSync, Sync y PostSync |
Que el servidor de repositorio genere los manifiestos importa en la práctica: Argo CD admite Kustomize, Helm, Jsonnet y YAML plano, así que el repositorio puede contener plantillas y no solo archivos finales. La consecuencia útil es que lo declarado sigue siendo legible por una persona.
El manifiesto Application
La unidad de trabajo de Argo CD es un recurso llamado Application, que declara de dónde sale la configuración y adónde va. Es la pieza que conviene entender antes que cualquier otra:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: facturacion-produccion
namespace: argocd
spec:
project: pagos
source: # de dónde sale el estado deseado
repoURL: https://git.ejemplo.org/config-produccion.git
targetRevision: v2.4.1 # una etiqueta, no una rama móvil
path: apps/facturacion
destination: # adónde se aplica
server: https://kubernetes.default.svc
namespace: facturacion
syncPolicy:
automated:
prune: true # borra lo que ya no está declarado
selfHeal: true # revierte los cambios manualesTres decisiones de ese archivo merecen atención. targetRevision apuntando a una etiqueta y no a una rama es lo que hace que el despliegue sea reproducible: una rama móvil convierte «el estado deseado» en un blanco que cambia solo. prune completa el modelo declarativo: sin él, borrar un recurso del repositorio no lo borra del clúster y el repositorio deja de describir la realidad. Y selfHeal es el cuarto principio hecho configuración: los cambios hechos a mano en el clúster se revierten.
Con selfHeal activo, cualquier cambio manual desaparece en el próximo ciclo, incluidos los arreglos de urgencia a las tres de la mañana. Eso es deseable, pero exige que el camino rápido para un arreglo urgente sea modificar el repositorio y que ese camino esté probado. Si no lo está, el equipo va a pelear contra el agente en el peor momento posible.
Sincronía, salud y deriva
Argo CD maneja dos estados distintos que se confunden todo el tiempo, y separarlos es lo que permite diagnosticar rápido:
- Estado de sincronización. ¿Lo que corre coincide con lo declarado? Si no, la aplicación queda marcada como
OutOfSync. Es una comparación entre repositorio y clúster. - Estado de salud. ¿Lo que corre funciona? Una aplicación puede estar perfectamente sincronizada y en mal estado, porque el manifiesto correcto describe un contenedor que no arranca.
La deriva de configuración es la diferencia entre el repositorio y la realidad. Antes de la reconciliación continua era invisible: aparecía por un cambio manual de urgencia, por otro operador que tocaba el mismo recurso o por un despliegue a medio aplicar, y nadie se enteraba hasta el incidente siguiente. El aporte de este modelo no es evitarla —siempre va a haber alguien con acceso al clúster— sino volverla visible en segundos y revertirla sin intervención.
Hay un matiz que ahorra frustración: la deriva legítima existe. Un escalador automático que ajusta la cantidad de réplicas está modificando el clúster por diseño, y declarar esa cantidad en el repositorio hace que los dos peleen. La solución es no declarar en el repositorio los campos que otro controlador administra.
Cómo organizar los repositorios
La documentación de Argo CD recomienda separar el repositorio del código del de la configuración, y la recomendación tiene tres razones concretas: evita que cada cambio de configuración dispare la compilación completa, mantiene el historial del código libre de confirmaciones de despliegue, y permite dar permisos distintos —quien puede tocar el manifiesto de producción no es necesariamente quien escribe código.
Con eso, el flujo completo queda así:
- Cambio en el códigoConfirmación en el repositorio de la aplicación, con sus pruebas.
- El pipeline construye y publicaCompila, prueba y sube la imagen al registro con una etiqueta inmutable.
- Se actualiza la configuraciónUna confirmación en el repositorio de configuración apunta a la nueva etiqueta.
- El agente reconciliaArgo CD detecta la diferencia y la aplica. Nadie tocó el clúster desde afuera.
- La promoción es otra confirmaciónPasar de pruebas a producción es cambiar la etiqueta en el directorio de producción, con revisión de por medio.
El paso cinco es el que más se subestima. Cuando la promoción entre entornos es una confirmación revisada en un repositorio, se obtiene gratis lo que antes requería un proceso: quién aprobó qué, cuándo y con qué contenido exacto, sin depender de que alguien lo anote.
El problema de los secretos
Este es el punto donde GitOps choca con la realidad, y conviene decirlo sin rodeos: un objeto Secret de Kubernetes está codificado en base64, no cifrado. Subirlo al repositorio equivale a publicarlo, y en un repositorio privado también, porque el historial de Git es para siempre y no se borra con una confirmación posterior.
Las tres salidas habituales, con su compromiso:
| Enfoque | Cómo funciona | Qué cuesta |
|---|---|---|
| Cifrado en el repositorio | El valor se cifra antes de subirlo y solo el clúster tiene la clave para descifrarlo | Hay que custodiar y rotar esa clave, que pasa a ser el secreto único |
| Referencia a un gestor externo | El repositorio guarda solo el nombre; un operador trae el valor desde el gestor de secretos | Suma una dependencia externa al arranque de las aplicaciones |
| Fuera del flujo de GitOps | Los secretos se administran por otro camino y el repositorio no los menciona | Esa parte del estado deja de estar declarada y auditada |
Cualquiera de las tres es defendible. La que no lo es —y aparece en incidentes reales con frecuencia incómoda— es subir el secreto tal cual «por ahora». Vale recordar el caso documentado de más de 10.000 imágenes de Docker Hub con credenciales filtradas: las credenciales que se meten en artefactos y repositorios se encuentran, y se encuentran a escala.
Qué gana y qué cuesta
Vale la pena ser honesto con las dos columnas, porque el tema se presenta casi siempre con una sola:
| Gana | Cuesta |
|---|---|
| Las credenciales del clúster no salen del clúster | Hay que operar y actualizar el agente, que es una pieza crítica más |
| La deriva se detecta y se revierte sola | Los arreglos manuales de urgencia dejan de funcionar como antes |
| Historial auditable de qué se desplegó y cuándo | Todo pasa por confirmaciones y revisiones: más ceremonia para cambios chicos |
| Reversión: volver atrás es volver a una revisión | Solo es cierto si la revisión anterior es realmente aplicable |
| El estado del sistema es legible sin entrar al clúster | Los secretos exigen una solución aparte, sin excepción |
Errores frecuentes
- Llamar GitOps a tener los YAML en Git. Sin agente que obtenga y reconcilie, faltan dos de los cuatro principios.
- Apuntar a una rama móvil. Si
targetRevisionsigue una rama, el estado deseado cambia sin que nadie despliegue nada. - No activar el borrado de lo no declarado. El repositorio deja de describir la realidad y se acumulan recursos que nadie recuerda.
- Declarar campos que otro controlador administra. El agente y el escalador automático se pelean, y el resultado parece un error intermitente.
- Un solo repositorio para código y configuración. Cada cambio de configuración dispara la compilación completa y los permisos se vuelven imposibles de separar.
- Dejar el acceso directo al clúster para todo el mundo. Si cualquiera puede aplicar cambios a mano, la reconciliación pelea contra el equipo todo el día.
- Suponer que la reversión es automática. Volver a la revisión anterior no revierte una migración de base de datos ya aplicada.
Preguntas frecuentes
¿Cuáles son los cuatro principios de GitOps?
Según la versión 1.0.0 publicada por OpenGitOps: el estado deseado se expresa de forma declarativa; se almacena de un modo que garantiza inmutabilidad, versionado e historial completo; agentes de software lo obtienen automáticamente desde el origen; y esos agentes observan de forma continua el estado real e intentan aplicar el estado deseado. Los cuatro juntos son lo que distingue GitOps de «tenemos los YAML en Git»: sin el tercero y el cuarto hay versionado, no GitOps.
¿Qué diferencia hay entre empujar y reconciliar?
En el modelo de empuje, el pipeline tiene credenciales del clúster y ejecuta el despliegue desde afuera: sabe lo que quiso aplicar, no lo que quedó. En el modelo de reconciliación, un agente que vive dentro del clúster compara el estado real con el declarado en el repositorio y corrige la diferencia de forma continua. Las consecuencias prácticas son dos: las credenciales del clúster no salen de él, y la deriva se detecta y se revierte sola.
¿Qué es la deriva de configuración?
Es la diferencia entre lo que dice el repositorio y lo que está corriendo realmente. Aparece por cambios manuales de urgencia, por otro operador que modifica el mismo recurso o por un despliegue que quedó a mitad de camino. Sin reconciliación continua nadie se entera hasta que algo falla, y el arreglo manual desaparece en el próximo despliegue. Argo CD la vuelve visible marcando la aplicación como OutOfSync, y puede revertirla automáticamente si se activa la autocorrección.
¿Los secretos se guardan en el repositorio?
No. Un objeto Secret de Kubernetes está codificado en base64, que no es cifrado: cualquiera con acceso al repositorio lo lee en un paso. Las tres salidas habituales son cifrar el valor antes de subirlo con una herramienta que solo el clúster puede descifrar, guardar únicamente una referencia y que un operador traiga el valor desde un gestor externo, o mantener los secretos completamente fuera del flujo de GitOps. Lo que no es una opción es subirlos tal cual.
¿Conviene un repositorio para el código y otro para la configuración?
Sí, y es la práctica recomendada por la propia documentación de Argo CD. Separarlos evita que cada cambio de configuración dispare la compilación completa y que el historial del código se llene de confirmaciones de despliegue. Además hace posible dar permisos distintos: quien puede tocar el manifiesto de producción no es necesariamente quien puede escribir código. El repositorio de configuración pasa a ser el registro auditable de lo que se desplegó y cuándo.
¿GitOps sirve sin Kubernetes?
Los principios sí; las herramientas más conocidas están hechas para Kubernetes. Nada en los cuatro principios menciona contenedores ni orquestadores: hablan de estado deseado declarativo, almacenamiento versionado y agentes que reconcilian. Se puede aplicar la misma idea a infraestructura declarada con herramientas de infraestructura como código, siempre que haya un agente que compare y corrija. Lo que no cuenta como GitOps es un pipeline que aplica cambios y se olvida.
Fuentes
Documentación oficial y material de la comunidad consultados para esta guía. Fecha de consulta: 27 de julio de 2026.
Aportes de la comunidad Underc0de
- Cl0udswX, foro de Underc0de. Contenedores Docker for dummies, 26 de mayo de 2016. Punto de partida sobre contenedores, la pieza que Kubernetes orquesta.
- Underc0de, blog. Más de 10.000 imágenes de Docker Hub con credenciales filtradas, 11 de diciembre de 2025. El riesgo concreto de meter secretos en artefactos y repositorios.
Documentación oficial
- OpenGitOps, CNCF. GitOps Principles v1.0.0. Los cuatro principios, citados textualmente.
- Argo CD. Argo CD Documentation. Definición de la herramienta y su premisa declarativa, citadas textualmente.
- Argo CD. Architecture Overview. Los tres componentes y el funcionamiento del controlador.
- Kubernetes. Secrets. Documentación del objeto y su codificación en base64.