# GitOps con Kubernetes y Argo CD

**Categoría:** DevOps y cloud · **Nivel:** Intermedio · **Lectura:** 13 min
**Publicada:** 2026-07-27 · **Actualizada:** 2026-07-27 · **Autoría:** Underc0de
**Versión HTML (canónica):** https://underc0de.org/guias/devops-cloud/gitops-con-kubernetes-y-argo-cd/

## Respuesta rápida

**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». La ganancia central: el pipeline deja de necesitar credenciales del clúster, y la **deriva** se vuelve visible.

## Los cuatro principios

Especificación **OpenGitOps**, versión **1.0.0**, citada textualmente:

1. **Declarativo.** «Un sistema gestionado por GitOps debe tener su estado deseado expresado de forma declarativa.»
2. **Versionado e inmutable.** «El estado deseado se almacena de una manera que impone inmutabilidad, versionado y retiene un historial completo de versiones.»
3. **Obtenido automáticamente.** «Agentes de software obtienen automáticamente las declaraciones de estado deseado desde el origen.»
4. **Reconciliado de forma continua.** «Agentes de software observan continuamente el estado real del sistema e intentan aplicar el estado deseado.»

Los dos primeros los cumple cualquiera que tenga YAML 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**.

## Empujar contra reconciliar

En el modelo de **empuje**, el pipeline guarda credenciales del clúster y ejecuta el despliegue desde afuera. Dos problemas que se pagan tarde: un secreto con permisos de escritura sobre producción vive en el sistema de integración continua, y el pipeline sabe **lo que quiso aplicar**, no lo que quedó corriendo.

En el modelo de **reconciliación**, 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 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

> «Argo CD es una herramienta declarativa de entrega continua GitOps para Kubernetes.»

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:

| Componente | Qué hace |
|---|---|
| Servidor de API | Expone la interfaz gRPC y REST, gestiona credenciales de repositorios y clústeres, aplica autenticación y autorización, recibe avisos 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 `PreSync`, `Sync` y `PostSync` |

Argo CD admite Kustomize, Helm, Jsonnet y YAML plano, así que el repositorio puede contener plantillas y no solo archivos finales.

## El manifiesto Application

```yaml
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 manuales
```

**`targetRevision`** apuntando a una etiqueta y no a una rama es lo que hace el despliegue reproducible. **`prune`** completa el modelo declarativo: sin él, borrar un recurso del repositorio no lo borra del clúster. Y **`selfHeal`** es el cuarto principio hecho configuración.

> **Antes de activar la autocorrección:** con `selfHeal` activo, cualquier cambio manual desaparece en el próximo ciclo, incluidos los arreglos de urgencia. Eso exige que el camino rápido para un arreglo urgente sea *modificar el repositorio* y que ese camino esté probado.

## Sincronía, salud y deriva

- **Estado de sincronización.** ¿Lo que corre coincide con lo declarado? Si no, la aplicación queda marcada como `OutOfSync`.
- **Estado de salud.** ¿Lo que corre funciona? Una aplicación puede estar sincronizada y en mal estado.

La **deriva de configuración** es la diferencia entre el repositorio y la realidad. 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**.

Un matiz que ahorra frustración: la deriva legítima existe. Un escalador automático que ajusta réplicas modifica el clúster por diseño, y declarar esa cantidad en el repositorio hace que los dos peleen. No declares 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**: 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.

1. **Cambio en el código.** Confirmación en el repositorio de la aplicación, con sus pruebas.
2. **El pipeline construye y publica.** Sube la imagen al registro con una etiqueta inmutable.
3. **Se actualiza la configuración.** Una confirmación en el repositorio de configuración apunta a la nueva etiqueta.
4. **El agente reconcilia.** Argo CD detecta la diferencia y la aplica. Nadie tocó el clúster desde afuera.
5. **La promoción es otra confirmación.** Pasar de pruebas a producción es cambiar la etiqueta, con revisión de por medio.

El paso cinco da gratis lo que antes requería un proceso: **quién aprobó qué, cuándo y con qué contenido exacto**.

## El problema de los secretos

**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.

| 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 | 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 | Suma una dependencia externa al arranque de las aplicaciones |
| Fuera del flujo de GitOps | Los secretos se administran por otro camino | 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— es subir el secreto tal cual «por ahora»: ver el caso de [más de 10.000 imágenes de Docker Hub con credenciales filtradas](https://blog.underc0de.org/mas-de-10-000-imagenes-de-docker-hub-detectaron-credenciales-filtradas/).

## Qué gana y qué cuesta

| Gana | Cuesta |
|---|---|
| Las credenciales del clúster no salen del clúster | Hay que operar y actualizar el agente, 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 | 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.** Faltan dos de los cuatro principios.
- **Apuntar a una rama móvil.** El estado deseado cambia sin que nadie despliegue nada.
- **No activar el borrado de lo no declarado.** El repositorio deja de describir la realidad.
- **Declarar campos que otro controlador administra.** El agente y el escalador automático se pelean.
- **Un solo repositorio para código y configuración.** Los permisos se vuelven imposibles de separar.
- **Dejar acceso directo al clúster para todo el mundo.** 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?**
Declarativo; versionado e inmutable; obtenido automáticamente por agentes de software; y reconciliado de forma continua. Los cuatro juntos son lo que distingue GitOps de «tenemos los YAML en Git».

**¿Qué diferencia hay entre empujar y reconciliar?**
En el empuje, el pipeline tiene credenciales del clúster y aplica desde afuera: sabe lo que quiso aplicar, no lo que quedó. En la reconciliación, un agente dentro del clúster compara y corrige de forma continua. Las credenciales no salen del clúster y la deriva se detecta sola.

**¿Qué es la deriva de configuración?**
Es la diferencia entre lo que dice el repositorio y lo que está corriendo. Argo CD la vuelve visible marcando la aplicación como `OutOfSync`, y puede revertirla si se activa la autocorrección.

**¿Los secretos se guardan en el repositorio?**
No. Un `Secret` de Kubernetes está codificado en base64, que no es cifrado. Hay que cifrarlo antes de subirlo, guardar solo una referencia a un gestor externo, o dejarlos fuera del flujo.

**¿Conviene un repositorio para el código y otro para la configuración?**
Sí, y es la práctica recomendada por la documentación de Argo CD. Separa disparadores de compilación, historial y permisos.

**¿GitOps sirve sin Kubernetes?**
Los principios sí; las herramientas más conocidas están hechas para Kubernetes. Lo que no cuenta como GitOps es un pipeline que aplica cambios y se olvida.

## Fuentes

Fecha de consulta: 27 de julio de 2026.

**Aportes de la comunidad Underc0de**

1. Cl0udswX, foro de Underc0de. [Contenedores Docker for dummies](https://underc0de.org/foro/gnulinux/contenedores-docker-for-dummies/), 26 de mayo de 2016.
2. Underc0de, blog. [Más de 10.000 imágenes de Docker Hub con credenciales filtradas](https://blog.underc0de.org/mas-de-10-000-imagenes-de-docker-hub-detectaron-credenciales-filtradas/), 11 de diciembre de 2025.

**Documentación oficial**

3. OpenGitOps, CNCF. [GitOps Principles v1.0.0](https://opengitops.dev/).
4. Argo CD. [Argo CD Documentation](https://argo-cd.readthedocs.io/en/stable/).
5. Argo CD. [Architecture Overview](https://argo-cd.readthedocs.io/en/stable/operator-manual/architecture/).
6. Kubernetes. [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/).

## Guías relacionadas

- [Platform Engineering e Internal Developer Platforms](../platform-engineering-e-internal-developer-platforms/index.md)
- [Observabilidad con OpenTelemetry, Prometheus y Grafana](../observabilidad-con-opentelemetry-prometheus-y-grafana/index.md)
- [Seguridad de la cadena de suministro de software](../seguridad-de-la-cadena-de-suministro-de-software/index.md)
- [Índice de DevOps y cloud](../index.md)