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. Flux aplica YAML plano u overlays de Kustomize y detecta cuál usa una carpeta. Esta guía muestra cómo estructurar un repositorio para varios entornos con Kustomize, cómo informar a Flux de cada uno 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.

La documentación de Flux describe tres estrategias de repositorio habituales:

• Monorepo. Todos los clústeres, aplicaciones e infraestructura en un repositorio. Lo más fácil para empezar y el que se usa aquí.
• Repositorio por entorno. Por ejemplo, uno para staging y otro para producción, con reglas de acceso separadas.
• Repositorio por equipo o por aplicación. Aislamiento fuerte, con un repositorio de plataforma que registra el repositorio de cada equipo.

Un monorepo típico se ve así:

fleet-infra/
├── clusters/
│   ├── dev/                 # Kustomizations de Flux para el clúster dev
│   └── production/          # Kustomizations de Flux para el clúster de producción
├── infrastructure/          # ingress controller, cert-manager, monitorización
└── apps/
    ├── base/webapp/         # manifiestos compartidos
    ├── dev/                 # overlay para dev
    └── production/          # overlay para producción

Construye una base y overlays de Kustomize

apps/base/webapp/kustomization.yaml lista los recursos compartidos:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

En apps/base/webapp/deployment.yaml, haz que el contenedor lea su configuración desde un ConfigMap que cada overlay generará (omite el campo namespace de la base, ya que lo definen los overlays):

          envFrom:
            - configMapRef:
                name: webapp-config

apps/dev/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: webapp-dev
resources:
  - namespace.yaml
  - ../base/webapp
replicas:
  - name: webapp
    count: 2
configMapGenerator:
  - name: webapp-config
    literals:
      - HEADER=Hello from dev

con un namespace.yaml que crea webapp-dev. apps/production/kustomization.yaml es igual, con namespace: webapp-prod, count: 4, su propio manifiesto de namespace y su propio valor de HEADER. Puedes comprobar lo que renderiza un overlay antes de hacer commit:

kustomize build apps/dev
# o, sin instalar kustomize por separado:
kubectl kustomize apps/dev

Apunta una Kustomization de Flux a cada overlay

Flux detecta el kustomization.yaml de la ruta y lo construye por ti. En la carpeta de cada clúster, añade una Kustomization de Flux por entorno. clusters/dev/apps.yaml:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: flux-system
  path: ./apps/dev
  prune: true
  wait: true
  timeout: 3m

Para el clúster de producción, clusters/production/apps.yaml usa path: ./apps/production. Como cada clúster se sometió a bootstrap con su propio --path, cada clúster solo ve su propia carpeta.

Haz deliberada la producción

A diferencia de las herramientas con un botón de sincronización manual, Flux aplica automáticamente, así que controlas producción a través de Git. Un patrón sólido es dejar que dev siga una rama y que producción siga etiquetas de release. En el source del clúster de producción:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: fleet-releases
  namespace: flux-system
spec:
  interval: 5m
  url: https://github.com/your-org/fleet-infra
  ref:
    semver: ">=1.0.0"

Producción entonces solo cambia cuando etiquetas una release. La aprobación de pull requests sobre la rama principal es el otro control común.

Gestiona los cambios de configuración a propósito

Cambia el valor de HEADER en un entorno y mira qué ocurre. 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, y con prune: true Flux lo elimina por ti. Ese comportamiento es exactamente lo que quieres: los cambios de configuración reinician los Pods.

Los ConfigMaps normales escritos a mano son distintos. Si editas un ConfigMap que un Deployment lee mediante envFrom, la especificación del Deployment no cambia, así que los Pods en ejecución conservan los valores antiguos. Usa configMapGenerator para todo lo que deba reiniciar cargas de trabajo cuando cambie. Los charts de Helm tienen una técnica equivalente, que cubre la guía de Helm.

Sustituye valores por clúster

A veces un valor difiere por clúster pero no quieres un overlay entero para él, por ejemplo un nombre de dominio. Las Kustomizations de Flux pueden sustituir variables tras la construcción:

spec:
  postBuild:
    substitute:
      cluster_domain: dev.example.com
    substituteFrom:
      - kind: ConfigMap
        name: cluster-vars

Todo ${cluster_domain} de tus manifiestos se reemplaza en el momento de aplicar. Úsalo con moderación, ya que los overlays son más fáciles de revisar.

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 nginx=nginx:1.26 ejecutado en apps/dev), deja que Flux lo aplique y verifica. Luego haz el mismo cambio en apps/production, mediante un pull request que requiera aprobación. Un pipeline de CI puede automatizar el commit de dev, y un revisor controla el de producción. La automatización de imágenes de Flux también puede hacer por ti el paso de dev, que cubre la guía de automatización de imágenes.