Las aplicaciones reales se ejecutan en varios entornos que difieren en pequeños detalles: número de réplicas, nombres de host, valores de configuración. Argo CD puede desplegar desde YAML plano, charts de Helm o Kustomize, y detecta cuál usa una carpeta. Esta guía muestra cómo estructurar un repositorio para varios entornos con overlays de Kustomize y con archivos de valores de Helm, y cubre un problema que atrapa a mucha gente con los cambios de configuración. Se apoya en el ejemplo webapp de las guías anteriores.

Elige una estructura: carpetas, no ramas

Puedes modelar los entornos como ramas de larga duración (dev, staging, main), pero eso convierte la promoción en un ejercicio de merge y permite que los entornos se desvíen entre sí. Una sola rama con una carpeta por entorno es más fácil de razonar: todos los entornos se ven lado a lado y un cambio en uno es un diff normal.

Kustomize está pensado para esto: una base compartida más un pequeño overlay por entorno que cambia solo lo que difiere.

Crea una base y overlays de Kustomize

webapp-config/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml

base/kustomization.yaml lista los recursos compartidos:

resources:
  - deployment.yaml
  - service.yaml

En base/deployment.yaml, haz que el contenedor lea su configuración desde un ConfigMap que cada overlay generará:

          envFrom:
            - configMapRef:
                name: webapp-config

overlays/dev/kustomization.yaml:

resources:
  - ../../base
namespace: webapp-dev
replicas:
  - name: webapp
    count: 2
configMapGenerator:
  - name: webapp-config
    literals:
      - HEADER=Hello from dev

overlays/prod/kustomization.yaml es igual, con namespace: webapp-prod, count: 4 y su propio valor de HEADER.

Apunta una Application a cada overlay

Argo CD detecta un kustomization.yaml en la ruta y lo construye por ti. Crea una Application por entorno:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: webapp-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-org/webapp-config.git
    targetRevision: HEAD
    path: overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: webapp-dev
  syncPolicy:
    syncOptions:
      - CreateNamespace=true
    automated:
      prune: true

Para webapp-prod, cambia el nombre, la ruta (overlays/prod) y el namespace, y considera omitir automated para que una persona apruebe las sincronizaciones de producción.

Con Helm, la forma es la misma, pero el origen es un chart y seleccionas el archivo de valores de un entorno:

  source:
    repoURL: https://github.com/your-org/webapp-config.git
    targetRevision: HEAD
    path: charts/webapp
    helm:
      valueFiles:
        - values-dev.yaml

Las rutas de valueFiles son relativas a la carpeta del chart, y los archivos posteriores sobrescriben a los anteriores.

Gestiona los cambios de configuración a propósito

Cambia el valor de HEADER en un entorno y compara qué hace cada herramienta:

• Kustomize agrega un hash del contenido a los nombres de los ConfigMaps generados. Un valor nuevo produce un ConfigMap nuevo (webapp-config-<hash>) y actualiza la referencia del Deployment, lo que desencadena un rollout de los Pods. El ConfigMap anterior queda huérfano, por lo que la aplicación aparece como OutOfSync hasta que se elimine (prune). Con prune: true activado, esto se limpia automáticamente.
• Helm actualiza el ConfigMap existente en el mismo lugar. La especificación del Deployment no cambia, así que los Pods en ejecución conservan los valores antiguos y nada le indica a Argo CD ni a Kubernetes que los reinicie.

La solución estándar para Helm es poner un checksum del ConfigMap en la plantilla del Pod, de modo que un cambio de configuración cambie la plantilla y reinicie los Pods. En templates/deployment.yaml:

  template:
    metadata:
      annotations:
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}

Reiniciar el Deployment a mano también funciona una vez, pero no queda registrado en Git, lo que anula el propósito.

Promueve cambios entre entornos

Con esta estructura, la promoción es una secuencia de commits normales. Cambia primero el overlay de dev (por ejemplo, una actualización de imagen con kustomize edit set image webapp=nginx:1.26 ejecutado en overlays/dev), deja que la sincronización automatizada lo aplique y verifica. Luego haz el mismo cambio en overlays/prod y sincroniza, manualmente si has mantenido producción restringida. Un pipeline de CI puede automatizar el commit en dev, y un pull request o una aprobación puede controlar el de producción. Para operar muchos clústeres o entornos desde un solo lugar, mira los ApplicationSets de Argo CD, que generan recursos Application a partir de una plantilla.