Manage Environments with the App-of-Apps Pattern

Define a root Application that references child Applications, keep per-environment values in Git, and let sync waves order dependencies.

~45 mingitopsargocdkubernetes

Task

Use the Argo CD app-of-apps pattern to deploy and version many applications from one root.

When to use this

Each application is registered by hand in the UI, so environments drift, adding a service means manual clicks, and there is no single source of truth.

Prerequisites

Argo CD installed
A Git repository with manifests

Steps

1. Create a root Application pointing at a directory of child Application manifests.

Expected output: Registering a service becomes a Git commit.

2. Keep child Applications with per-environment overlays.

Expected output: Environments are reproducible from Git.

3. Use sync waves and health checks to order dependencies.

Expected output: Databases deploy before apps that need them.

4. Verify that changing Git changes the cluster and pruning removes deleted apps.

argocd app list -o name

Expected output: Git is the single source of truth.

Troubleshooting

Problem

Deleted app not pruned

Solution

Enable pruning with care and review the diff; pruning can delete workloads unexpectedly.

Problem

Sync wave misordering

Solution

Annotate sync-wave numbers explicitly and keep dependencies one wave apart.

Limitations

App-of-apps centralizes control, so a mistake in the root can affect every environment at once.
It requires discipline in repository layout to remain readable as the number of apps grows.

Context

Use the Argo CD app-of-apps pattern to deploy and version many applications from one root. Each application is registered by hand in the UI, so environments drift, adding a service means manual clicks, and there is no single source of truth.

Steps

Create a root Application pointing at a directory of child Application manifests. Expected: Registering a service becomes a Git commit.
Keep child Applications with per-environment overlays. Expected: Environments are reproducible from Git.
Use sync waves and health checks to order dependencies. Expected: Databases deploy before apps that need them.
Verify that changing Git changes the cluster and pruning removes deleted apps. Expected: Git is the single source of truth.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata: { name: root, namespace: argocd }
spec:
  source: { repoURL: https://github.com/acme/envs, path: apps, targetRevision: main }
  destination: { server: https://kubernetes.default.svc, namespace: argocd }
  syncPolicy: { automated: { prune: true, selfHeal: true } }

Verify

Registering a service becomes a Git commit.
Environments are reproducible from Git.
Databases deploy before apps that need them.
Git is the single source of truth.

Limits

App-of-apps centralizes control, so a mistake in the root can affect every environment at once.
It requires discipline in repository layout to remain readable as the number of apps grows.