Guía Completa de GitOps con ArgoCD
Despliega apps Kubernetes con GitOps y ArgoCD: instalación, ApplicationSets, estrategias de sync, Helm/Kustomize, RBAC y multi-cluster.
Introducción
GitOps usa Git como única fuente de verdad para infraestructura y despliegue de aplicaciones. ArgoCD es una herramienta de continuous delivery nativa de Kubernetes que implementa GitOps — vigila un repo Git y sincroniza el estado deseado a los clusters. Esta guía cubre instalación, configuración de aplicaciones, estrategias de sync, integración Helm/Kustomize, RBAC y gestión multi-cluster.
El modelo invierte el pipeline push clásico: en lugar de CI desplegando al cluster con kubectl apply, un controlador dentro del cluster pull del estado deseado desde Git y lo reconcilia continuamente. El trabajo de CI se reduce a “build image, update manifest, open PR” — el paso de deploy desaparece, junto con las credenciales que lo hacían posible.
Principios de GitOps
- Declarativo: el estado del sistema se describe declarativamente en Git — manifiestos, values de Helm, overlays de Kustomize, no scripts imperativos
- Versionado: Git proporciona versionado, historia y rollback —
git revertes la vía de rollback - Pulled: ArgoCD pull los cambios desde Git (sin push desde CI — las credenciales del cluster nunca salen del cluster)
- Reconciliado continuamente: ArgoCD detecta drift y lo corrige — los edits manuales con
kubectlse revierten cuando selfHeal está activo
Ese último punto es el que la gente subestima: GitOps no es solo “deploy on merge”. El controlador vigila el estado live también — alguien hace kubectl edit a un replica count a las 2am, ArgoCD ve el drift y lo revierte. Git sigue siendo la verdad.
ArgoCD vs Flux
Ambos son operadores GitOps de la CNCF, y la elección es real:
| ArgoCD | Flux |
|---|---|
| UI + RBAC + SSO incluidos | CLI-first, UI vía terceros (Weave GitOps, Headlamp) |
| Application CRD + ApplicationSet | CRDs Kustomization/HelmRelease de FluxCD |
| Multi-cluster de serie | Cluster API o wiring propio para multi-cluster |
| Notifications controller incluido | Alerting vía notification-controller (webhooks) |
| Huella más pesada (varios componentes) | Más ligero — corre como un set pequeño de controladores |
Los equipos con muchos namespaces y usuarios no expertos suelen elegir ArgoCD por la UI; los que dominan Kubernetes por dentro y quieren piezas mínimas se inclinan a Flux. Esta guía es el deep-dive de ArgoCD — para la decisión lado a lado en un flujo de producción, mira la guía de GitOps en producción.
Instalar ArgoCD
kubectl create namespace argocd
kubectl apply -n argocd \
-f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# Obtener la contraseña admin
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d
# Port-forward para acceder a la UI
kubectl port-forward svc/argocd-server -n argocd 8080:443
Para despliegues reales, salta el port-forward — pon argocd-server detrás de un ingress con TLS, habilita SSO (Dex/OIDC con GitHub o Google) en lugar de la cuenta admin, y usa el manifiesto de instalación HA (install.yaml tiene variante -ha) cuando ArgoCD es crítico. El secret admin inicial es una vía de bootstrap, no una estrategia de gestión de credenciales.
Aplicación Básica
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/example/my-app-deploy
targetRevision: main
path: manifests
destination:
server: https://kubernetes.default.svc
namespace: my-app
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
Lo que importa: source apunta al repo+path+revisión con el estado deseado, destination nombra el cluster+namespace donde desplegar, y syncPolicy.automated es donde vive el contrato GitOps — prune: true borra recursos que desaparecen de Git, selfHeal: true revierte edits fuera de banda, y syncOptions ajusta casos borde como autocrear el namespace destino. Para la vista de producción de este flujo (SOPS, progressive delivery, rollback), mira la guía de GitOps en producción.
ApplicationSet (Multi-Entorno)
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: my-app-multi-env
namespace: argocd
spec:
generators:
- list:
elements:
- env: dev
cluster: https://dev-cluster:6443
- env: staging
cluster: https://staging-cluster:6443
- env: prod
cluster: https://prod-cluster:6443
template:
metadata:
name: "my-app-{{env}}"
spec:
project: default
source:
repoURL: https://github.com/example/my-app-deploy
targetRevision: main
path: "manifests/{{env}}"
destination:
server: "{{cluster}}"
namespace: my-app
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
El generador list es la opción explícita — enumeras dev/staging/prod y el template estampa una Application por elemento. Los generadores son el poder real aquí:
list— conjunto fijo de envs/clusters (lo de arriba)git— descubre Applications desde directorios o archivos en un repocluster— una Application por cada cluster registrado en ArgoCDpullRequest— entornos de preview: una Application por PR abiertomatrix— producto cartesiano de dos generadores (env × región)
Para producción, el generador pullRequest es la gran ganancia — cada PR obtiene un namespace de preview con sus manifiestos desplegados, destruido al merge.
Git Generator (Auto-descubrir repos)
El generador git convierte la estructura de directorios en Applications — una carpeta por servicio o entorno en el deploy repo, y cada directorio nuevo se convierte en una Application nueva en el próximo reconcile. Añadir un servicio es añadir una carpeta, nada más. directories recorre carpetas; files lee un manifiesto por archivo (útil para repos de config por equipo).
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: auto-discover
namespace: argocd
spec:
generators:
- git:
repoURL: https://github.com/example/org-deployments
directories:
- path: "*/"
template:
metadata:
name: "{{path.basename}}"
spec:
project: default
source:
repoURL: https://github.com/example/org-deployments
targetRevision: main
path: "{{path}}"
destination:
server: https://kubernetes.default.svc
namespace: "{{path.basename}}"
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
Integración Helm
ArgoCD renderiza charts de Helm nativamente — sin Tiller, sin Helm CLI en el cluster. Los valueFiles superponen overrides base→entorno en orden; los parameters son overrides individuales que ganan a ambos. Mantén los values específicos de entorno en el deploy repo (no en los defaults del chart) para que la Application sea la única perilla que tocas por entorno.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app-helm
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/example/my-app-deploy
targetRevision: main
path: charts/my-app
helm:
valueFiles:
- values.yaml
- values-prod.yaml
parameters:
- name: image.tag
value: "v1.2.3"
- name: replicaCount
value: "3"
destination:
server: https://kubernetes.default.svc
namespace: my-app
syncPolicy:
automated:
prune: true
selfHeal: true
Integración Kustomize
El path apunta a un overlay — base/ contiene los manifiestos compartidos, overlays/dev y overlays/prod parchean replicas, recursos e image tags. kustomize.images en la Application es un override de última hora, principalmente para que CI actualice el tag. Base queda intacto; los overlays poseen los deltas por entorno.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app-kustomize
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/example/my-app-deploy
targetRevision: main
path: overlays/production
kustomize:
images:
- my-app:v1.2.3
commonLabels:
env: production
destination:
server: https://kubernetes.default.svc
namespace: my-app
syncPolicy:
automated:
prune: true
selfHeal: true
Estrategias de Sync
La política de sync decide cuándo el estado deseado se convierte en estado live. La regla práctica: automatizado con selfHeal para dev/staging, manual o con sync windows para producción — un manifiesto malo no debería llegar a prod sin supervisión.
Sync automatizado
syncPolicy:
automated:
prune: true # Borra recursos eliminados de Git
selfHeal: true # Revierte cambios manuales
Sync manual con hooks
syncPolicy:
syncOptions:
- CreateNamespace=true
- PrunePropagationPolicy=foreground
# Sync manual vía CLI: argocd app sync my-app
Sync waves (despliegue ordenado)
# En tus manifiestos, añade anotaciones:
metadata:
annotations:
argocd.argoproj.io/sync-wave: "0" # Corre primero
---
metadata:
annotations:
argocd.argoproj.io/sync-wave: "1" # Corre segundo
---
metadata:
annotations:
argocd.argoproj.io/sync-wave: "2" # Corre tercero
Las waves corren en orden ascendente y el sync espera a que cada wave reporte Healthy antes de empezar la siguiente — eso es lo que permite que los CRDs lleguen antes que los custom resources que los necesitan, o el ConfigMap antes del deployment que lo monta. Las waves negativas corren antes de 0 (úsalas para namespaces y CRDs).
Sync windows
Bloquea deploys fuera del horario laboral sin tocar la Application:
# En el spec del AppProject
syncWindows:
- kind: deny
schedule: '0 0 * * SAT,SUN' # sin deploys en finde
duration: 24h
applications: ['*']
- kind: allow
schedule: '0 9-17 * * MON-FRI'
duration: 8h
applications: ['*']
Hooks Pre/Post sync
apiVersion: batch/v1
kind: Job
metadata:
name: db-migration
annotations:
argocd.argoproj.io/hook: PreSync
argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
template:
spec:
containers:
- name: migration
image: my-app/migrate:v1.2.3
command: ["./migrate", "up"]
restartPolicy: Never
backoffLimit: 3
Los hooks corren en puntos del ciclo de vida: PreSync antes del sync principal (migraciones, cambios de esquema), PostSync después de que los recursos estén sanos (smoke tests), SyncFail en fallo (alertas, limpieza), Skip para excluir un recurso del sync por completo. hook-delete-policy controla cuándo se limpia el recurso del hook — HookSucceeded para jobs de una sola vez.
RBAC
El RBAC de ArgoCD es política Casbin en un ConfigMap — las reglas p conceden subject, resource, action, object, effect, g mapea usuarios/grupos a roles. Combínalo con AppProject para multi-tenancy real: el proyecto limita qué repos, clusters y namespaces pueden tocar las Applications dentro de él, y el RBAC decide quién puede hacer qué dentro de ese perímetro.
# argocd-rbac-cm
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-rbac-cm
namespace: argocd
data:
policy.default: role:readonly
policy.csv: |
p, role:dev-team, applications, sync, dev/*, allow
p, role:dev-team, applications, get, dev/*, allow
p, role:dev-team, applications, action/override, dev/*, deny
p, role:ops-team, applications, *, */*, allow
g, dev-team, role:dev-team
g, ops-team, role:ops-team
# AppProject — el perímetro alrededor de las apps de un equipo
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: dev
namespace: argocd
spec:
sourceRepos: ['https://github.com/example/*'] # solo estos repos
destinations:
- server: '*' # cualquier cluster
namespace: 'dev-*' # solo namespaces dev-*
clusterResourceWhitelist:
- group: ''
kind: Namespace # solo puede crear namespaces
Multi-Cluster Management
# Registrar un cluster en ArgoCD
argocd cluster add prod-cluster --label environment=production
# Listar clusters registrados
argocd cluster list
# Desplegar a un cluster específico
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app-prod
namespace: argocd
spec:
source:
repoURL: https://github.com/example/my-app-deploy
targetRevision: main
path: overlays/production
destination:
server: https://prod-cluster:6443 # o name: prod-cluster
namespace: my-app
Los clusters registrados viven como secrets etiquetados argocd.argoproj.io/secret-type: cluster en el namespace argocd — argocd cluster add solo escribe ese secret. Combinado con el generador cluster del ApplicationSet, añadir un cluster nuevo = añadir un secret, y cada Application del set despliega allí automáticamente.
CLI de ArgoCD
# Login
argocd login localhost:8080 --username admin --password <password>
# Gestión de aplicaciones
argocd app create my-app \
--repo https://github.com/example/my-app-deploy \
--path manifests \
--dest-server https://kubernetes.default.svc \
--dest-namespace my-app
argocd app sync my-app
argocd app get my-app
argocd app history my-app
argocd app rollback my-app <version>
argocd app delete my-app
# Diff entre Git y cluster
argocd app diff my-app
# Utilidades que te salvan en incidentes
argocd app wait my-app --health --timeout 120 # bloquear hasta Healthy en CI
argocd app sync my-app --dry-run # previsualizar el apply
argocd admin settings rbac can "get, applications" --policy-file argocd-rbac-cm # test RBAC localmente
argocd app diff antes del merge y argocd app sync --dry-run en CI son los dos comandos que previenen la mayoría de los incidentes GitOps — el diff muestra exactamente qué cambiaría en el cluster para un manifiesto dado.
Notificaciones
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-notifications-cm
namespace: argocd
data:
service.slack: |
token: $slack-token
trigger.on-deployed: |
- when: app.status.operationState.phase in ['Succeeded']
send: [app-deployed]
template.app-deployed: |
message: |
{{.app.metadata.name}} deployed to {{.app.status.sync.status}}
Las notificaciones corren en el notifications-controller: service.* define canales (slack, email, webhook, pagerduty), trigger.* las condiciones (sync-succeeded, sync-failed, health-degraded, created, deleted), template.* el payload con Go templating sobre el objeto Application. Suscríbete por Application o por ApplicationSet vía la anotación notifications.argoproj.io/subscribe.on-deployed.slack: my-channel — sin config por app.
Repository Layout
Dos layouts cubren a la mayoría de equipos. App-of-apps: un repo con una Application por entorno/servicio, y una Application raíz que apunta a la carpeta que las contiene — un bootstrap despliega todo el árbol:
deploy-repo/
├── apps/ # Manifiestos de Application (el "app of apps")
│ ├── dev.yaml # Application → overlays/dev
│ ├── staging.yaml
│ └── prod.yaml
├── base/ # Base Kustomize o manifiestos planos
└── overlays/
├── dev/ # Parches dev (1 réplica, límites pequeños)
├── staging/
└── prod/ # Parches prod (3 réplicas, límites completos)
Deploy repo separado vs mismo repo: mantener manifiestos en el repo de la app acopla la frecuencia de deploy a los merges de código (cada commit dispara un reconcile). Un deploy repo dedicado los desacopla — CI construye la imagen, actualiza el tag en el deploy repo, y ArgoCD lo recoge. Esa separación es lo que hace de la promoción multi-entorno una operación git en lugar de un redeploy.
Troubleshooting
- App atascada en
SyncWait: normalmente un hook que nunca completa (un Job que no llega a Succeeded) o un recurso cuya salud ArgoCD no puede evaluar — revisaargocd app get my-apppara el recurso colgado y sus eventos. OutOfSyncque no se cura: algo fuera del tracking de ArgoCD (unkubectlmanual, un campo mutado por webhook, un admission controller inyectando sidecars) — diff conargocd app diff my-app; si el delta es un campo gestionado por controlador, añádelo aignoreDifferencesen la Application.- Los recursos que dependen de CRDs fallan: el CRD y sus CRs aterrizan en el mismo sync pero la API aún no está registrada — usa sync waves (CRD en wave
-1o0, CRs después) para que la API exista antes de usarse. - Refresh vs hard refresh:
argocd app get my-app --refreshre-consulta el repo;--hard-refreshlimpia la caché de manifiestos también — úsalo cuando “nada cambió” pero sabes que sí. - El sync funciona pero los recursos se recrean:
prune: trueborra recursos huérfanos cada sync — revisaargocd app resources my-apppara ver qué se está podando y añade tracking (labelapp.kubernetes.io/instance) donde corresponde.
Checklist de Producción
Antes de llamar “listo para producción” a un setup ArgoCD:
- Instalación HA — usa la variante HA de
install.yaml(3 réplicas de cada componente, anti-affinity entre nodos) para que una caída de nodo no tumbe tu pipeline de entrega - Solo SSO — desactiva la cuenta admin (
argocd-cmadmin.enabled: "false"), rutea todo por Dex/OIDC; las cuentas locales son solo para break-glass - Proyectos por equipo — un AppProject por equipo o entorno, con
sourceRepos,destinationsyclusterResourceWhitelistrestringidos; nunca dejes que apps dedevlleguen a namespacesprod - Deploy repo separado — los manifiestos viven en su propio repo; CI actualiza tags allí, nunca en el código de la app
- Sync windows para prod — ventanas deny fuera del horario laboral; ventanas allow cuando hay humanos mirando
- Alertas de drift y fallo — notificaciones en
sync-failed,health-degradedy OutOfSync que persiste más de unos minutos - Backups del estado de ArgoCD —
argocd-util exportregularmente; las Applications y los proyectos también son estado - Controlador monitorizado — ArgoCD es infraestructura crítica: alerta sobre su propia salud, memoria y errores de fetch de Git, no solo sobre las apps que despliega
- Operador de secrets — Sealed Secrets, SOPS o External Secrets; secrets en texto plano en Git son una fuga esperando a ocurrir
Buenas Prácticas
- Guarda los manifiestos separados del código de la app — deploy repo o directorio separado
- Usa overlays de Kustomize — base + overlays por entorno
- Habilita selfHeal — revierte cambios manuales de kubectl automáticamente
- Usa sync waves — asegura que los CRDs se aplican antes de los recursos que los usan
- Usa AppProject para aislar — restringe qué repos, clusters y namespaces puede tocar cada equipo
- Fija la versión de ArgoCD — no uses
latesten producción - Usa SSO para ArgoCD — integra con GitHub, Google u OIDC
- Monitorea ArgoCD mismo — es infraestructura crítica
- Usa ApplicationSets para escalar — evita crear Applications individuales por cada microservicio
- Habilita notificaciones — alerta sobre fallos de sync y detección de drift
Errores Comunes
- Guardar manifiestos en el repo de la app — acopla la frecuencia de deploy a la frecuencia de releases de la app
- No usar selfHeal — los cambios manuales persisten y causan drift
- Dar acceso admin a todos los equipos — usa RBAC con mínimo privilegio
- No usar sync waves — los CRDs y operadores fallan si se aplican fuera de orden
- No probar el sync antes del merge — usa ArgoCD diff o
argocd app sync --dry-run - Usar sync automatizado en producción sin canary — considera sync manual para prod
- No monitorizar drift — habilita notificaciones para estado out-of-sync
- Olvidar prune — los recursos viejos persisten si
prune: false
See Also
- Documentación oficial de ArgoCD
- Documentación de ApplicationSet
- Guía Completa de GitOps en Producción — SOPS, progressive delivery, rollbacks
- Guía Completa de Kubernetes Ingress
- Companion de ArgoCD en GitHub — YAMLs de Application, ApplicationSet, AppProject, notificaciones
Preguntas frecuentes
¿En qué se diferencia GitOps de CI/CD?
CI construye y testea el código. GitOps se encarga del CD — despliegue a entornos. En GitOps, el despliegue se dispara por cambios en Git, no por CI empujando a un cluster. CI construye imágenes y actualiza manifiestos en Git; ArgoCD recoge el cambio de manifiesto y despliega.
¿Debo usar sync automatizado en producción?
Depende. El sync automatizado con selfHeal es genial para dev y staging. Para producción, considera sync manual con approval gates, o sync automatizado con progressive delivery (Argo Rollouts) para despliegues canary/blue-green.
¿Cómo manejo secrets en GitOps?
No guardes secrets en texto plano en Git. Usa Sealed Secrets, SOPS o External Secrets Operator. Estos cifran los secrets en Git y los descifran en el cluster. ArgoCD sincroniza la versión cifrada; el operador se encarga del descifrado.
¿Debo usar ApplicationSet o Applications individuales?
ApplicationSet en cuanto tengas más de un par de entornos o clusters — un template estampa N Applications desde un generador, así que añadir prod-eu o un equipo nuevo es una línea en el generador, no un nuevo archivo YAML. Las Applications individuales solo tienen sentido para casos puntuales.
¿Cómo hago rollback de un deploy malo?
argocd app rollback my-app <version> — el historial de la app registra cada sync, así que el rollback es un sync nuevo a un estado viejo (sigue siendo GitOps: queda registrado y es reversible). git revert también funciona y es la mejor respuesta a largo plazo ya que mantiene a Git honesto.
¿Puedo desplegar sin un commit de Git para arreglos rápidos?
Puedes — argocd app sync my-app --local manifests/ o un kubectl apply ad hoc — pero selfHeal lo revertirá en el próximo reconcile, que es exactamente el punto. Para emergencias reales: sync a una rama hotfix, o pausa el auto-sync, parchea, y commitea el arreglo correctamente. El cluster no es la fuente de verdad; trata los cambios fuera de banda como temporales.
Recursos Relacionados
Kubernetes Básico para Desarrolladores de Aplicaciones
Aprende los conceptos core de Kubernetes que todo desarrollador necesita: Pods, Services, Deployments, ConfigMaps y comandos básicos de kubectl.
GuideGuía de Pipelines CI/CD: Del Commit a Producción
Guía práctica para construir pipelines CI/CD con GitHub Actions, gates de testing, estrategias de despliegue y procedimientos de rollback.
GuideEstrategias de Despliegue: Blue-Green, Canary y Rolling
Guía práctica de estrategias de despliegue: rolling, blue-green, canary, shadow y feature flags. Minimiza el riesgo y el tiempo de rollback al liberar a producción.
GuideGuía Completa de Kubernetes Ingress
Configura y soluciona problemas de Kubernetes Ingress. Cubre controladores, TLS con cert-manager, enrutamiento por path, anotaciones y Gateway API.
GuideGuía completa de CI/CD con GitHub Actions
Construye pipelines CI/CD desde cero con GitHub Actions. Cubre workflows, runners, builds en matriz, caché, secretos, entornos, estrategias de despliegue y workflows reutilizables.
GuideGuía de Gestión de Configuración en Kubernetes
Gestión de configuración en Kubernetes: ConfigMaps, Secrets, External Secrets Operator, sealed secrets, inyección env, montajes y rotación.