Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Multi-cluster and ApplicationSets

ApplicationSet Matrix, Merge, Templates and Progressive Sync

Combine generators with matrix and merge, template patches and conditionals, sync policy protections and the alpha rolling sync strategy for ApplicationSets.

The basic generators in ApplicationSet Generators cover single dimensions: one per cluster, or one per folder. Real fleets have two dimensions at once ("every app on every prod cluster"). This lesson covers combining generators, templating tricks, and controlling how changes roll out.

Matrix generator

A matrix takes exactly two child generators and builds their cross product. Each output set merges one parameter set from each child.

YAML
generators:
  - matrix:
      generators:
        - clusters:
            selector:
              matchLabels:
                env: prod
        - git:
            repoURL: https://git.example.com/platform/gitops.git
            revision: main
            directories:
              - path: addons/*

With 3 prod clusters and 4 addon folders you get 12 Applications. The template can use parameters from both sides (.name from the cluster and .path.basename from Git). The second generator may even use the first one's parameters, for example a Git path of {{ .metadata.labels.region }}/*.

Merge generator

A merge takes a base generator and overrides parameter sets from others when a merge key matches:

YAML
generators:
  - merge:
      mergeKeys: [name]
      generators:
        - clusters: {}
        - clusters:
            selector:
              matchLabels:
                env: prod
            values:
              replicas: "5"
        - list:
            elements:
              - name: prod-eu-1
                replicas: "8"

Every cluster appears (the first generator); prod clusters get replicas: 5; prod-eu-1 is bumped to 8. Merge is how you express "defaults, then group overrides, then per-item overrides" without duplicating anything.

flowchart TB
  A["clusters: all"] --> M["merge by name"]
  B["clusters: env=prod, replicas=5"] --> M
  C["list: prod-eu-1 replicas=8"] --> M
  M --> R["one parameter set per cluster, later generators win"]

Later generators override earlier ones for the same key value.

Template features

  • Patches: templatePatch is a YAML string patched onto the template, and it may contain Go template conditionals:
YAML
templatePatch: |
  {{- if eq .env "prod" }}
  spec:
    syncPolicy:
      automated: {}
  {{- end }}

Production gets auto-sync; other environments do not.

  • Per-element metadata: add labels, annotations and finalizers in template.metadata.
  • Sprig functions such as lower, replace, default, splitList help produce DNS-safe names. {{ .path.basename | lower | replace "_" "-" }}.
  • Fields from selectors: {{ index .metadata.labels "region" }} reads a label key that contains characters Go cannot use after a dot.
  • To emit literal double braces (for a Helm template inside a generated value), write them as a Go string: {{ "{{ .Values.x }}" }}.

Sync policy of the ApplicationSet

The ApplicationSet has its own syncPolicy, which controls what the controller may do to generated Applications:

Setting Effect
preserveResourcesOnDeletion: true Deleting the ApplicationSet (or an element) leaves the deployed workloads behind
applicationsSync: create-only Only create new Applications; never update or delete
applicationsSync: create-update Create and update; never delete
applicationsSync: create-delete Create and delete; never update
applicationsSync: sync Full reconciliation (default)

Pair these with RBAC and the controller flag that restricts policy overrides so that the production fleet can never be deleted by an accidental empty generator.

ignoreApplicationDifferences lets you declare fields (for example /spec/source/targetRevision) that humans or tools may change on a generated Application without the ApplicationSet reverting them.

Progressive syncs (rolling sync)

By default, a template change updates all generated Applications at once. The RollingSync strategy, an alpha feature that must be enabled on the ApplicationSet controller, updates them in steps:

YAML
strategy:
  type: RollingSync
  rollingSync:
    steps:
      - matchExpressions:
          - key: env
            operator: In
            values: [staging]
      - matchExpressions:
          - key: env
            operator: In
            values: [prod]
        maxUpdate: 25%

Staging is synced first. Only when its Applications are Healthy does the controller start prod, 25 percent at a time. Because it depends on application labels and the generated Applications must not have automated sync enabled (the controller triggers the syncs), plan the labels in the template. Check the release notes of your version, since alpha behavior can change.

Stand-in: matrix and merge

Python Stand-in: cross product and merge by key

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Debugging tips

  • kubectl describe applicationset <name> shows conditions such as ErrorOccurred and ParametersGenerated and the reason a template failed.
  • The ApplicationSet controller logs include the generated parameter sets at debug level.
  • Duplicate names across parameter sets cause an error; make names unique by including both dimensions.
  • Large matrices create many Applications at once. Mind controller capacity and API rate limits (High Availability and Performance).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A matrix of 3 clusters and 4 folders generates how many Applications?

    A matrix is the cross product: 3 times 4.
  2. 2. What does the merge generator do with a matching merge key?

    Sets with the same key value are combined; later generators win on conflicting parameters.
  3. 3. Which ApplicationSet syncPolicy prevents Applications from ever being deleted by the controller?

    create-update creates and updates but never deletes. (preserveResourcesOnDeletion only keeps the workloads, not the Application objects.)
  4. 4. What does RollingSync do?

    It is a progressive strategy: staging first, then prod in batches.

Summary

  • Matrix builds the cross product of two generators; merge layers parameter sets by key.
  • templatePatch and Sprig functions add conditionals and name cleanup.
  • Use applicationsSync and preserveResourcesOnDeletion to protect against accidental deletion.
  • RollingSync (alpha) rolls changes through environments in steps.

Next: The App of Apps Pattern