ArgoCD GitOps para Despliegues en Kubernetes

ArgoCD es una herramienta de entrega continua declarativa basada en GitOps para Kubernetes que mantiene el estado del clúster sincronizado permanentemente con las configuraciones almacenadas en Git. Si alguna vez has ejecutado manualmente kubectl apply tras cada cambio de código o has rastreado diferencias de configuración entre entornos, ArgoCD lo resuelve convirtiendo Git en la única fuente de verdad para cada recurso desplegado. Esta guía te lleva por la instalación de ArgoCD, la conexión de repositorios, la creación de recursos Application y la configuración de políticas de sincronización para despliegues de nivel productivo.

Requisitos Previos

• Un clúster Kubernetes en ejecución (v1.22+) con kubectl configurado
• Permisos de administrador del clúster para crear namespaces y CRDs
• Un repositorio Git con manifiestos de Kubernetes, charts de Helm o overlays de Kustomize
• CLI de ArgoCD (argocd) instalada localmente (opcional pero recomendada)
• Familiaridad básica con Deployments, Services y namespaces de Kubernetes

¿Qué es GitOps y por qué ArgoCD?

GitOps es un modelo operativo donde el estado deseado de la infraestructura y las aplicaciones se declara en Git. Un operador dentro del clúster compara continuamente el estado real con el deseado y reconcilia las diferencias. ArgoCD es el operador GitOps nativo de Kubernetes más adoptado, con estatus de proyecto graduado de la CNCF desde 2022.

Las ventajas principales sobre los pipelines de CI/CD tradicionales de tipo push:

Característica	ArgoCD (GitOps pull)	Jenkins / GitLab CI (push)
Almacenamiento de credenciales	Solo dentro del clúster	En secretos del sistema CI
Detección de deriva	Continua, automática	Solo en el momento del despliegue
Mecanismo de reversión	Revert de Git a cualquier commit	Volver a ejecutar el pipeline anterior
Registro de auditoría	Historial de Git	Logs de CI
Soporte multiclúster	Nativo, por Application	Configuración manual de pipeline
Autocorrección	Bucle de sincronización integrado	No disponible

El modelo pull es una mejora de seguridad significativa: tu pipeline de CI ya no necesita credenciales del clúster. ArgoCD corre dentro del clúster y obtiene cambios de Git, siempre en sentido saliente.

Instalar ArgoCD

Crea el namespace dedicado y aplica el manifiesto de instalación oficial:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Espera a que todos los pods alcancen el estado Running:

kubectl wait --for=condition=available deployment --all -n argocd --timeout=120s
kubectl get pods -n argocd

Acceder a la interfaz web

Por defecto, el servicio argocd-server es de tipo ClusterIP. Para acceso local usa port-forwarding:

kubectl port-forward svc/argocd-server -n argocd 8080:443

Recupera la contraseña de administrador generada automáticamente:

kubectl get secret argocd-initial-admin-secret -n argocd \
  -o jsonpath="{.data.password}" | base64 -d && echo

Inicia sesión con la CLI:

argocd login localhost:8080 --username admin --password <contraseña> --insecure

Para producción, configura un Ingress con TLS e integra SSO (Dex con GitHub/OIDC) en lugar de usar la cuenta de administrador.

Conectar un Repositorio Git

ArgoCD necesita acceso a tu repositorio Git para obtener manifiestos. Para repositorios públicos no se requieren credenciales. Para repositorios privados:

argocd repo add https://github.com/tu-org/tu-repo-k8s \
  --username git \
  --password <token>

Para SSH:

argocd repo add git@github.com:tu-org/tu-repo-k8s.git \
  --ssh-private-key-path ~/.ssh/id_rsa

También puedes gestionar repositorios de forma declarativa como Secrets de Kubernetes con la etiqueta argocd.argoproj.io/secret-type: repository si prefieres una gestión GitOps completa del propio ArgoCD.

Crear Aplicaciones en ArgoCD

Una Application es el recurso central de ArgoCD. Define qué desplegar, desde dónde, y en qué clúster y namespace.

Manifiesto de Application declarativo

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mi-web-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/tu-org/tu-repo-k8s
    targetRevision: main
    path: manifests/mi-web-app
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    syncOptions:
      - CreateNamespace=true

Aplícalo:

kubectl apply -f mi-web-app-application.yaml

Aplicaciones con Helm

ArgoCD admite Helm de forma nativa sin necesitar Helm instalado en los sistemas de CI:

source:
  repoURL: https://github.com/tu-org/tu-repo-k8s
  targetRevision: main
  path: charts/mi-web-app
  helm:
    valueFiles:
      - values-production.yaml
    parameters:
      - name: image.tag
        value: "v1.4.2"

Aplicaciones con Kustomize

source:
  repoURL: https://github.com/tu-org/tu-repo-k8s
  targetRevision: main
  path: kustomize/overlays/production

ArgoCD detecta automáticamente el archivo kustomization.yaml y ejecuta kustomize build de forma transparente.

Políticas de Sincronización y Autocorrección

La política de sincronización es la decisión de configuración más importante en ArgoCD.

Sincronización manual — ArgoCD detecta la deriva pero requiere que una persona (o un paso de CI) dispare la sincronización. Útil para entornos de producción donde se desea aprobación explícita antes de desplegar cambios.

Sincronización automática — ArgoCD sincroniza automáticamente al detectar diferencias entre Git y el clúster. Combínala con autocorrección y poda para automatización completa:

syncPolicy:
  automated:
    selfHeal: true   # revierte ediciones manuales con kubectl
    prune: true      # elimina recursos borrados de Git
  retry:
    limit: 5
    backoff:
      duration: 5s
      maxDuration: 3m
      factor: 2

selfHeal: true significa que si alguien edita un recurso manualmente con kubectl, ArgoCD lo revertirá en segundos. Esto refuerza la disciplina GitOps estricta.

prune: true significa que los recursos eliminados del repositorio Git también se eliminan del clúster. Sin poda, los recursos huérfanos se acumulan con el tiempo.

Escenario Real: Promoción Multi-Entorno

Tienes tres entornos — dev, staging y production — cada uno en un namespace separado, con overlays de Kustomize específicos por entorno. Tu pipeline de CI construye y publica una imagen Docker, luego actualiza la etiqueta de imagen en el archivo dev/kustomization.yaml y hace commit en Git.

repo/
  kustomize/
    base/           ← manifiestos compartidos
    overlays/
      dev/          ← App de ArgoCD para namespace dev
      staging/      ← App de ArgoCD para namespace staging
      production/   ← App de ArgoCD para namespace production (sync manual)

ArgoCD para dev usa automated: {} (despliegue automático en cada commit). ArgoCD para staging y production usa sincronización manual: un ingeniero revisa el diff en la interfaz y hace clic en sincronizar, o una aprobación de PR dispara una llamada argocd app sync en el pipeline de CI.

Este patrón mantiene la promoción controlada y auditable a través del historial de Git, no de los logs de compilación de Jenkins.

Errores Comunes y Casos Especiales

Problemas de orden con CRDs — Si tu app instala Custom Resource Definitions junto con recursos que las usan, ArgoCD puede fallar en la primera sincronización porque los CRDs aún no están establecidos. Usa sync waves con argocd.argoproj.io/sync-wave: "-1" en los manifiestos de CRD para asegurar que se apliquen primero.

Poda y Jobs — La poda de ArgoCD eliminará Jobs completados y sus Pods si se borran de Git. Usa argocd.argoproj.io/hook: PostSync y argocd.argoproj.io/hook-delete-policy: HookSucceeded para Jobs de migración de una sola ejecución.

Estrategia de etiquetas de imagen — Evita usar latest como etiqueta. ArgoCD compara manifiestos, no digests de imagen, por lo que una nueva publicación a latest no disparará sincronización. Usa etiquetas inmutables (SHA de git o semver). El proyecto ArgoCD Image Updater puede automatizar la actualización de etiquetas en Git.

RBAC y Projects — El proyecto default permite todos los repos y clústeres. Para configuraciones multiequipo, crea AppProjects con alcance limitado a repositorios fuente, namespaces destino y tipos de recursos permitidos.

Gestión de secretos — Nunca almacenes manifiestos de Secrets de Kubernetes con datos en texto plano en Git. Usa Sealed Secrets, External Secrets Operator o secretos cifrados con SOPS comprometidos en Git.

Tiempo de espera de sincronización — Los hooks de Helm de larga ejecución pueden superar el tiempo de espera de sincronización predeterminado (300s). Auméntalo con --timeout en la CLI o configura timeout.reconciliation en el ConfigMap argocd-cm.

Problemas Comunes

App atascada en Progressing — Revisa la salida de argocd app get <nombre> para recursos degradados. Normalmente es un rollout de Deployment fallido o un PVC pendiente. Ejecuta kubectl describe pod -n <namespace> en el Pod afectado.

ComparisonError o estado de salud Unknown — ArgoCD no puede obtener los manifiestos. Verifica la conectividad del repositorio con argocd repo list y comprueba las credenciales.

Bucle de autocorrección — Si ArgoCD sigue revirtiendo un recurso, un webhook de validación u operador está modificando el recurso después de que ArgoCD lo aplique. Usa ignoreDifferences en la spec de la Application para indicar a ArgoCD que ignore campos específicos.

La poda elimina recursos inesperados — Asegúrate de que todos los recursos que deseas que ArgoCD gestione tengan la etiqueta correcta app.kubernetes.io/instance.

Resumen

• ArgoCD implementa GitOps reconciliando continuamente el estado del clúster con el estado deseado definido en Git
• Se instala con un solo kubectl apply en el namespace argocd; accede mediante port-forward o Ingress
• Las Applications se definen de forma declarativa y admiten manifiestos raw, charts de Helm y Kustomize
• Usa sincronización automática con selfHeal y prune para dev/staging; sincronización manual para aprobaciones en producción
• Organiza configuraciones multi-entorno con overlays de Kustomize o archivos de valores de Helm por entorno
• Protege los secretos con Sealed Secrets o External Secrets Operator — nunca en texto plano en Git
• Usa sync waves para el orden de CRDs y ArgoCD Image Updater para la promoción automática de etiquetas
• Los Projects de RBAC limitan el acceso a repositorios y clústeres en despliegues multiequipo

Artículos Relacionados

• Git: Flujos Avanzados con Rebase, Bisect y Hooks
• Guía de Configuración de Pipelines CI/CD con GitLab
• Gestión de Secretos en Kubernetes con SOPS y age
• Primeros Pasos con GitHub Actions CI/CD
• Guía de Solución de Problemas de Pods en Kubernetes