Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 37 ยท Multi-cluster and ApplicationSets

The App of Apps Pattern

Bootstrap whole environments with one root Application that deploys other Applications: layout, finalizers, sync waves, comparison with ApplicationSets.

An Application's manifests can be anything, including other Application resources. The app of apps pattern uses this: a single root Application points to a folder of child Application manifests. Syncing the root creates the children, and each child then deploys its own workloads. One kubectl apply bootstraps an entire cluster.

flowchart TB
  R["root Application"] --> C1["Application: ingress"]
  R --> C2["Application: monitoring"]
  R --> C3["Application: shop"]
  C1 --> W1["ingress workloads"]
  C2 --> W2["monitoring workloads"]
  C3 --> W3["shop workloads"]

The root deploys Application objects into the argocd namespace; they deploy the real workloads.

Repository layout

TEXT
gitops/
  bootstrap/
    root.yaml              # applied once by hand
  apps/                    # what the root watches
    ingress.yaml
    monitoring.yaml
    shop.yaml
  workloads/
    ingress/...
    monitoring/...
    shop/...

The root Application

YAML
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: root
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: platform
  source:
    repoURL: https://git.example.com/platform/gitops.git
    targetRevision: main
    path: apps
    directory:
      recurse: true
  destination:
    name: in-cluster
    namespace: argocd        # child Applications live here
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

The destination namespace is the one where Argo CD reads Application resources (usually argocd). Each child file in apps/ is a normal Application:

YAML
# apps/monitoring.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: monitoring
  namespace: argocd
  annotations:
    argocd.argoproj.io/sync-wave: "1"
spec:
  project: platform
  source:
    repoURL: https://git.example.com/platform/gitops.git
    targetRevision: main
    path: workloads/monitoring
  destination:
    name: in-cluster
    namespace: monitoring
  syncPolicy:
    automated: {}
    syncOptions: [CreateNamespace=true]

Bootstrap with kubectl apply -n argocd -f bootstrap/root.yaml. After that, adding an app means adding a file and merging a pull request.

Ordering with sync waves

Within the root's sync, the sync-wave annotation on child Applications orders their creation: wave 0 first (CRDs and platform), then 1 (monitoring), then 2 (workloads). Argo CD waits for each wave's resources to be healthy before the next. For Application resources, Argo CD's health check reports healthy only when the child itself is healthy, which makes the wave ordering meaningful. Without waves, children start in parallel, which is fine for independent apps.

Finalizers and deletion

The finalizer resources-finalizer.argocd.argoproj.io makes Argo CD cascade-delete the workloads when the Application is deleted. Place it deliberately:

  • On the children, so deleting a child removes its workloads.
  • On the root, so deleting the root removes the children, and through them everything. This is powerful and dangerous; many teams omit it from the root and require deliberate deletions.

Without the finalizer, deleting an Application leaves its resources in the cluster, orphaned.

Projects and permissions

The root can use a project that is allowed to create Application resources in the argocd namespace. Children should use narrower projects, for example platform and team-shop. Anyone who can change apps/ can create Applications, so protect that folder with code owners and branch rules. A child could otherwise name the default project and bypass restrictions, so enable project policies for the root's project.

App of apps versus ApplicationSet

App of apps ApplicationSet
Child definition Hand-written manifests Generated from a template
Flexibility Each child can differ completely Children share one shape
Duplication Repeats boilerplate Minimal
Ordering Sync waves Rolling sync (alpha) or none
Best for A small number of distinct platform components Many similar apps or clusters

They combine well: the root app of apps deploys ApplicationSets as children, and the sets generate the repetitive Applications.

Pitfalls

  • Recursion mistakes: a root that includes itself in its own path creates a loop. Keep root.yaml outside apps/.
  • Prune surprises: removing a file from apps/ with prune: true deletes the child Application, and with its finalizer all of its workloads. Review such pull requests carefully.
  • Too many levels: root, then team apps, then apps is already three layers. Keep it shallow so errors are traceable.

Stand-in: planning deletion impact

Python Stand-in: what does deleting an app remove?

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the root Application in app of apps deploy?

    Its manifests are Application objects, which then deploy the real workloads.
  2. 2. How can child Applications be created in a specific order?

    Waves order resources in a sync, and Applications report health, so later waves wait.
  3. 3. What does the resources-finalizer.argocd.argoproj.io finalizer do?

    It enables cascading deletion; without it the workloads are orphaned.
  4. 4. When is an ApplicationSet usually better than app of apps?

    Templates remove the boilerplate when children are similar.

Summary

  • A root Application whose path holds Application manifests bootstraps everything from one apply.
  • Use sync waves for ordering and finalizers for deliberate cascade deletion.
  • Protect the apps/ folder and restrict projects, since writing there creates Applications.
  • Combine with ApplicationSets: use app of apps for distinct components, sets for repetition.

Next: RBAC Policies