Promotion by ApplicationSet — programmatic generation of promotion targets

Promotion by ApplicationSet is the model in which the promotion targets are not declared by hand. Instead, an Argo CD Applicationset controller reads a generator (cluster list, Git directory, matrix of values) and emits one Argo CD Application per generated item. The promotion flow is the generator’s input; the Applications are derived output. Adding a new environment or a new cluster is a generator change, not an Application YAML change.

The promotion shape

The diagram shows a Git directory generator. The env repo has a directory per environment; the Applicationset template iterates over those directories and emits one Application per environment. The promotion is the act of changing a directory in the env repo — the Applicationset controller sees the change, regenerates the Application, and the controller reconciles.

flowchart LR
    E["env repo: overlays/dev"] --> AS1["ApplicationSet: cluster generator"]
    E2["env repo: overlays/staging"] --> AS1
    E3["env repo: overlays/prod"] --> AS1
    AS1 --> A1["Application: payment-api-dev"]
    AS1 --> A2["Application: payment-api-staging"]
    AS1 --> A3["Application: payment-api-prod"]
    A1 --> AD["Cluster: dev"]
    A2 --> AS["Cluster: staging"]
    A3 --> AP["Cluster: prod"]

The Applications are not maintained by hand. The operator maintains the directory tree in the env repo; the Applicationset controller maintains the Application list. The promotion is a Git operation (a directory or file change in the env repo) and the Applicationset does the rest.

The generator types

Three generators cover most promotion flows:

• Git directory generator. Iterates over directories in a Git repo. A new directory produces a new Application. Used for monorepo promotion where each service or each environment is a directory.
• Git file generator. Iterates over files matching a glob. A new file produces a new Application. Used for configuration-as-data where the file content is the Application spec.
• Matrix generator. Combines two generators: for every item in generator A and every item in generator B, emit a value pair. Used to fan a service across environments and clusters, producing service x environment x cluster Applications.

The matrix generator is the natural fit for promotion. Each service in a Git directory generator is paired with each environment in a list generator, and the Applicationset emits one Application per pair. Adding a cluster to the list adds N Applications for N services; the operator writes one line in a list, not N Application manifests.

Promotion through a generator

The promotion itself is a change in the generator’s input. A new digest in a directory, a new value in a list, a new directory in a Git tree. The Applicationset controller observes the change and regenerates the affected Application(s).

DIGEST="sha256:9a3f1c7e8b2a4f6d0e5b9c7a1d3f8e6b2c4a5d7e9f1b3c5a7d9e1f3b5c7a9d1e"
sed -i "s|@sha256:PLACEHOLDER|@sha256:$DIGEST|g" env-repo/overlays/prod/*.yaml
git -C env-repo commit -am "promote digest to prod"
git -C env-repo push origin main

The push to the env repo’s main triggers the Applicationset controller to re-read the prod directory and update the prod Application’s source.targetRevision or source.helm. parameters. The change is one Git commit; the Application update is derived.

argocd app set payment-api-prod --revision "$PROD_SHA"
argocd app sync payment-api-prod --revision "$PROD_SHA"

The argocd commands still apply: the Applicationset emits the Application, but the operator can still pin and sync by ref or digest when a manual promotion step is required.

The audit shape

The audit record is the Git history of the generator’s input. For a Git directory generator, that is the env repo’s commit log: every change in overlays/prod/ is a production promotion, every change in overlays/staging/ is a staging promotion. For a matrix generator with a list generator, that is the Git history of the list file: every line added is a new cluster, every line removed is a cluster retired. The ApplicationSet controller’s reconciliation log records which Applications were generated from which generator items at which times.

The rollback shape

The rollback is a Git revert of the generator input that introduced the bad change. For a Git directory generator, the revert restores the directory to its previous state, the Applicationset regenerates the Application, and the controller reconciles. For a matrix generator with a list generator, the revert restores the list, and the Applications that were generated from the removed list items are deleted. The audit trail is the Git log; the rollback is a Git operation.

Production discipline

The production rules for promotion by ApplicationSet:

1. The generator input is the source of truth. The Applications are derived; the generator input is canonical. Changes go into the generator; never edit a generated Application’s spec by hand.
2. PR review covers the generator input. A new cluster in a list, a new directory in a tree, a new digest in a directory — each is a promotion event and each requires review.
3. The Applicationset’s controller reconciliation is observable. The Applicationset status records which Applications were generated and whether the generator input is healthy. A broken generator is a promotion outage.

Cross-course references

• Git, CI/CD & GitOps — Part LXXVI-04 (Source hydrator and the mirror) covers the mirroring pattern that often accompanies an Applicationset.
• Git, CI/CD & GitOps — Part XLV-03 (Promotion across environments) is the conceptual foundation the Applicationset automates.
• Kubernetes for Production Sysadmins — Part XL (Multi- cluster) covers the cluster registry that an Applicationset cluster generator typically reads.

Quiz