ArgoCD ApplicationSets: multi-clúster con generators y sync waves
Si llevas tiempo operando Kubernetes con GitOps, probablemente ya conoces el poder de una Application en ArgoCD: un manifiesto que declara "este repositorio Git debe reflejarse en este clúster". El problema aparece cuando pasas de uno a diez, veinte o cien clústeres. Escribir una Application por cada combinación de entorno, región y aplicación se convierte en una pesadilla de mantenimiento. Ahí es donde entran los ApplicationSets, la primitiva que convierte una plantilla en N aplicaciones generadas dinámicamente.
Qué es un ApplicationSet y por qué importa
Un ApplicationSet es un controlador que vive dentro de ArgoCD y se encarga de generar objetos Application a partir de una plantilla más una fuente de datos. Esa fuente de datos se llama generator, y es la pieza clave: define de dónde salen las variables que rellenan la plantilla.
La ventaja frente a escribir Applications a mano no es solo el ahorro de YAML. Es la capacidad de que la topología de tus despliegues sea data-driven: si añades un clúster nuevo a una lista o un directorio nuevo a un repo, el ApplicationSet lo detecta y crea automáticamente la Application correspondiente. Sin intervención humana.
Los generators más útiles en producción
ArgoCD incluye varios generators de serie. Estos son los que verás una y otra vez en setups reales:
- List generator: una lista estática embebida en el propio ApplicationSet. Útil para entornos fijos (dev, staging, prod).
- Cluster generator: itera sobre todos los clústeres registrados en ArgoCD. Perfecto para desplegar un addon (por ejemplo,
metrics-server) en toda la flota. - Git generator: dos modalidades. Directories recorre carpetas de un repo, y Files lee ficheros JSON/YAML con parámetros. Es el que más flexibilidad ofrece.
- Matrix y Merge: combinan dos generators. Matrix hace producto cartesiano (clúster × aplicación), Merge fusiona por clave.
- Pull Request generator: crea Applications efímeras por cada PR abierto. Oro puro para entornos de preview.
Ejemplo: desplegar un addon en toda la flota
El caso clásico. Quieres instalar cert-manager en todos los clústeres etiquetados como env=production:
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: cert-manager-fleet
namespace: argocd
spec:
goTemplate: true
goTemplateOptions: ["missingkey=error"]
generators:
- clusters:
selector:
matchLabels:
env: production
template:
metadata:
name: 'cert-manager-{{.name}}'
spec:
project: infra
source:
repoURL: https://github.com/acme/gitops-addons
targetRevision: main
path: cert-manager
destination:
server: '{{.server}}'
namespace: cert-manager
syncPolicy:
automated:
prune: true
selfHeal: true
Con este manifiesto, cada vez que registres un clúster nuevo con la etiqueta adecuada, ArgoCD creará la Application y sincronizará el addon automáticamente. La etiqueta se añade con:
kubectl label secret cluster-paris-01 \
-n argocd argocd.argoproj.io/secret-type=cluster \
env=production --overwrite
Ejemplo: Git generator para microservicios
Supón que tu repo gitops-apps tiene una carpeta por servicio, cada una con un values.yaml. El Git directory generator recorre esas carpetas y genera una Application por servicio:
generators:
- git:
repoURL: https://github.com/acme/gitops-apps
revision: HEAD
directories:
- path: services/*
template:
metadata:
name: '{{.path.basename}}-prod'
spec:
source:
repoURL: https://github.com/acme/gitops-apps
path: '{{.path.path}}'
targetRevision: HEAD
El resultado es que añadir un directorio nuevo en Git implica una Application nueva en ArgoCD. Cero kubectl apply.
Sync waves: ordenar el caos
Generar Applications es solo la mitad del problema. La otra mitad es el orden. Cuando despliegas un stack completo —CRDs, operadores, base de datos, aplicación— no puedes lanzarlo todo a la vez. ArgoCD resuelve esto con sync waves, una anotación que agrupa recursos en fases ordenadas:
metadata:
annotations:
argocd.argoproj.io/sync-wave: "-5"
ArgoCD ejecuta primero las waves negativas más bajas, luego la 0 (por defecto), y así sucesivamente. Un patrón habitual:
- Wave
-5: namespaces y CRDs. - Wave
-3: operadores y controladores. - Wave
-1: secretos y configmaps. - Wave
0: workloads principales (Deployments, StatefulSets). - Wave
5: Jobs de migración o smoke tests.
Si necesitas esperar a que algo esté realmente sano antes de pasar a la siguiente wave, combinas sync waves con health checks y la anotación argocd.argoproj.io/hook cuando se trata de Jobs.
Sync waves dentro de ApplicationSets
Aquí está la parte interesante: las sync waves se aplican a nivel de recursos dentro de una Application, no entre Applications distintas. Si quieres ordenar entre aplicaciones generadas por un ApplicationSet, tienes dos opciones:
- Usar App-of-Apps con ApplicationSets anidados: el ApplicationSet A genera una Application que a su vez es un ApplicationSet B.
- Aprovechar syncPolicy con
preserveResourcesOnDeletiony orquestar el orden desde una Application raíz que referencia las demás.
En la práctica, la combinación más limpia es un ApplicationSet raíz que genera Applications por entorno, y dentro de cada una, sync waves que ordenan los manifiestos internos.
Patrones que funcionan en producción
Después de operar esto en varios equipos, hay tres patrones que se repiten:
- Un ApplicationSet por tipo de recurso, no uno gigante que hace de todo. Facilita el RBAC y el debugging.
- goTemplate: true siempre que puedas. Las plantillas Go son más expresivas que el modo fasttemplate antiguo y fallan ruidosamente con
missingkey=error. - Labels consistentes en los clústeres. El cluster generator depende por completo de ellas. Sin disciplina de etiquetado, el generator es inútil.
Errores comunes y cómo evitarlos
El error más frecuente es olvidar que un ApplicationSet borra Applications cuando un generator deja de producirlas. Si eliminas un directorio de Git, ArgoCD borra la Application y, con prune: true, también los recursos. Activa preserveResourcesOnDeletion si quieres evitar sorpresas.
Otro clásico: usar targetRevision: HEAD en producción. Es cómodo, pero rompe la reproducibilidad. Fija un tag o un commit SHA en entornos críticos.
Finalmente, cuidado con los bucles infinitos: si un ApplicationSet genera una Application que modifica el mismo repo que el generator observa, puedes entrar en un ciclo de reconciliación. Mantén separados los repos de "definición" y de "estado".
Conclusión
ApplicationSets con generators convierten ArgoCD de una herramienta de despliegue en una plataforma de orquestación multi-clúster. Combinados con sync waves, obtienes algo que antes requería scripts, pipelines y mucha fe: despliegues ordenados, repetibles y declarativos a escala. La curva de aprendizaje es real, pero el retorno —en horas de operación y en incidentes evitados— es enorme. Empieza con un cluster generator pequeño, añade un Git generator para tus servicios, y deja que las sync waves hagan el resto.