StackPractices
intermediate Por Mathias Paulenko

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.

Bucle GitOps con ArgoCD: CI empuja manifiestos a Git, ArgoCD consulta el repo, compara estado deseado vs live y sincroniza al cluster.

Principios de GitOps

  1. Declarativo: el estado del sistema se describe declarativamente en Git — manifiestos, values de Helm, overlays de Kustomize, no scripts imperativos
  2. Versionado: Git proporciona versionado, historia y rollback — git revert es la vía de rollback
  3. Pulled: ArgoCD pull los cambios desde Git (sin push desde CI — las credenciales del cluster nunca salen del cluster)
  4. Reconciliado continuamente: ArgoCD detecta drift y lo corrige — los edits manuales con kubectl se 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:

ArgoCDFlux
UI + RBAC + SSO incluidosCLI-first, UI vía terceros (Weave GitOps, Headlamp)
Application CRD + ApplicationSetCRDs Kustomization/HelmRelease de FluxCD
Multi-cluster de serieCluster API o wiring propio para multi-cluster
Notifications controller incluidoAlerting 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 repo
  • cluster — una Application por cada cluster registrado en ArgoCD
  • pullRequest — entornos de preview: una Application por PR abierto
  • matrix — 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 — revisa argocd app get my-app para el recurso colgado y sus eventos.
  • OutOfSync que no se cura: algo fuera del tracking de ArgoCD (un kubectl manual, un campo mutado por webhook, un admission controller inyectando sidecars) — diff con argocd app diff my-app; si el delta es un campo gestionado por controlador, añádelo a ignoreDifferences en 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 -1 o 0, CRs después) para que la API exista antes de usarse.
  • Refresh vs hard refresh: argocd app get my-app --refresh re-consulta el repo; --hard-refresh limpia la caché de manifiestos también — úsalo cuando “nada cambió” pero sabes que sí.
  • El sync funciona pero los recursos se recrean: prune: true borra recursos huérfanos cada sync — revisa argocd app resources my-app para ver qué se está podando y añade tracking (label app.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-cm admin.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, destinations y clusterResourceWhitelist restringidos; nunca dejes que apps de dev lleguen a namespaces prod
  • 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-degraded y OutOfSync que persiste más de unos minutos
  • Backups del estado de ArgoCD — argocd-util export regularmente; 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 latest en 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

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.