Multi-Cluster GitOps

Managing fleet repositories, cluster selectors, Argo CD ApplicationSets, and Flux Kustomizations.

8 min readCI/CD & GitOpsPlatform

Fleet Management

Managing Kubernetes across multiple clusters requires a consistent deployment model. GitOps provides this — each cluster pulls its desired state from Git. The challenge is defining which applications deploy to which clusters, and managing configuration differences between clusters.

Fleet management patterns include hub-spoke (one central repo, many clusters), per-cluster repos, and hybrid approaches. The right pattern depends on team size, cluster count, and organizational structure.

Repository Strategies

Strategy	Pros	Cons
Monorepo	Single source of truth, atomic changes	Tight coupling, blast radius
Per-cluster repo	Isolation, independent teams	Duplication, cross-cluster changes
App-per-repo	Clear ownership, independent CI	Many repos, complex promotion
Hybrid	Flexible, scales well	Complex structure

Monorepo structure for fleet management


fleet/
  clusters/
    us-east-1/
      kustomization.yaml
      values.yaml
    us-west-2/
      kustomization.yaml
      values.yaml
    eu-west-1/
      kustomization.yaml
      values.yaml
  apps/
    myapp/
      base/
        kustomization.yaml
        deployment.yaml
      overlays/
        us-east-1/
          kustomization.yaml
        us-west-2/
          kustomization.yaml
    other-app/
      base/
        kustomization.yaml
  infrastructure/
    cert-manager/
    ingress-nginx/
    monitoring/

The monorepo organizes clusters and apps in separate directories. Each cluster has its own values. App overlays customize per cluster. This structure allows atomic changes across clusters.

ArgoCD ApplicationSets

ApplicationSet with git directory generator


apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapp
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://github.com/myorg/fleet-repo.git
        revision: main
        directories:
          - path: clusters/*
    - clusters:
        selector:
          matchLabels:
            environment: production
  template:
    metadata:
      name: "myapp-{{path.basename}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/myorg/fleet-repo.git
        targetRevision: main
        path: "apps/myapp/overlays/{{path.basename}}"
      destination:
        server: "{{server}}"
        namespace: production
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

The git directory generator creates an Application for each cluster directory. The clusters generator selects clusters by label. The template uses generator-specific variables like path.basename and server.

Flux Fleet Management

Flux Kustomization for fleet deployment


apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: myapp-production
  namespace: flux-system
spec:
  interval: 5m
  path: ./apps/myapp/overlays/production
  prune: true
  sourceRef:
    kind: GitRepository
    name: fleet-repo
  dependsOn:
    - name: infrastructure
  patches:
    - target:
        kind: ConfigMap
        name: myapp-config
      patch: |
        apiVersion: v1
        kind: ConfigMap
        metadata:
          name: myapp-config
          namespace: production
        data:
          CLUSTER: production
          REGION: us-east-1

Each cluster has its own Kustomization resources pointing to the fleet repository. The patches field allows per-cluster customization. dependsOn ensures infrastructure is deployed before applications.

Cluster Selectors

Cluster labels for targeting


apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: region-specific-app
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            region: us-east-1
            tier: production
        values:
          replicas: "6"
          cpu_limit: "2"
    - matrix:
        generators:
          - clusters:
              selector:
                matchLabels:
                  region: us-east-1
          - git:
              repoURL: https://github.com/myorg/fleet-repo.git
              revision: main
              directories:
                - path: apps/*
  template:
    metadata:
      name: "{{path.basename}}-{{name}}"
    spec:
      destination:
        server: "{{server}}"
        namespace: "{{path.basename}}"
      source:
        repoURL: https://github.com/myorg/fleet-repo.git
        path: "{{path}}"
        targetRevision: main
        helm:
          valueFiles:
            - values-{{name}}.yaml

Cluster labels enable targeted deployments. The matrix generator combines cluster information with application directories, creating Applications for every app on every matching cluster.

Scaling Patterns

ApplicationSets for dynamic generation — automatically create Applications as clusters or apps are added.
Fleet repositories — centralize all cluster configurations in one repository for atomic changes.
Cluster labels — use metadata labels to target deployments by region, tier, or team.
Progressive sync — sync clusters in order (dev first, then staging, then production) to catch issues early.
Multi-tenancy — use namespaces and RBAC to isolate tenant workloads in shared clusters.

Use progressive sync for fleet rollouts

ArgoCD ApplicationSets support progressive sync — deploying to one cluster at a time with pauses between. This prevents a bad change from affecting all clusters simultaneously. Configure it with the progressiveRolloutSteps field.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 5 · Platform

GitOps Operations