Using Argo CD ApplicationSet to Manage Multiple Guestbook Instances

Problem: Managing many similar Argo CD Applications

When you need to run the same workload—such as a guestbook app—in several namespaces or clusters, creating a separate Application manifest for each instance leads to repetitive YAML. Updating a common setting (e.g., replica count) requires editing every file, increasing the chance of drift.

Thesis: ApplicationSet provides a single source of truth while generating multiple Applications

Argo CD’s ApplicationSet controller watches a custom resource that defines a template and a generator. The generator (list, cluster, git, matrix, etc.) produces parameters that are injected into the template, resulting in one Application per generated item. This approach keeps shared configuration in one place and lets you vary per‑instance fields such as namespace or replica count.

How ApplicationSet works

• Template: A standard Argo CD Application manifest where placeholders like {{replicaCount}} or {{namespace}} are used.
• Generator: Supplies a list of key‑value pairs. The List generator lets you explicitly define each set of values.
• Controller: The ApplicationSet controller creates, updates, and deletes the generated Application objects to match the generator output.

Worked example: Two guestbook instances with different replica counts

Assume you have a guestbook Helm chart in a Git repository at guestbook/chart. You want two instances: guestbook-dev with 1 replica and guestbook-staging with 3 replicas, each in its own namespace.

1. Ensure Argo CD version

ApplicationSet graduated to stable in Argo CD v2.2. Verify your server:

# Run on a machine with kubectl configured for the cluster
kubectl -n argocd get deployment argocd-controller -o jsonpath='{.spec.template.spec.containers[?(@.name=="argocd-repo-server")].image}'

The image tag should be v2.2.0 or newer.

2. Install the ApplicationSet CRD (if not already present)

Apply the official manifest (requires cluster‑admin privileges):

kubectl apply -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/applicationset/install.yaml

3. Create the ApplicationSet

Save the following as guestbook-applicationset.yaml and apply it (requires permission to create applicationsets.argoproj.io in the target namespace, e.g., argocd):

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook-set
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - name: guestbook-dev
            namespace: dev
            replicaCount: 1
          - name: guestbook-staging
            namespace: staging
            replicaCount: 3
  template:
    metadata:
      name: "{{name}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/example/guestbook-repo.git
        targetRevision: HEAD
        path: guestbook/chart
        helm:
          releaseName: "{{name}}"
          parameters:
            - name: replicaCount
              value: "{{replicaCount}}"
      destination:
        server: https://kubernetes.default.svc
        namespace: "{{namespace}}"
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

Apply:

kubectl apply -f guestbook-applicationset.yaml

4. Verify generated Applications

Check that two Application objects appear:

kubectl -n argocd get applications -l argocd.argoproj.io/application-set=guestbook-set

You should see resources named guestbook-dev and guestbook-staging. Inspect one:

argocd app get guestbook-dev

Confirm that the Helm replicaCount parameter is set to 1 (for dev) or 3 (for staging) and that the destination namespace matches.

5. Update a common setting

Change the template to add a common label, commit the change to the ApplicationSet, and apply:

# edit guestbook-applicationset.yaml, add under spec.template.metadata:
#   labels:
#     app.kubernetes.io/part-of: guestbook
kubectl apply -f guestbook-applicationset.yaml

The controller will update both generated Applications to include the new label.

Trade‑off and limitation

ApplicationSet adds an extra controller layer. If the generator produces many items (hundreds or thousands), the controller’s reconciliation loop can increase API load. Moreover, debugging a misbehaving generated Application requires checking both the ApplicationSet status (kubectl get applicationset guestbook-set -o yaml) and the individual Application objects, which adds a step compared to reviewing a static Application manifest.

Actionable closing

Use ApplicationSet when you need to manage many similar workloads that differ only in a few parameters (namespace, replica count, cluster selector, etc.). Before adopting it in production:

1. Confirm you are running Argo CD v2.2 or newer.
2. Test the generator and template in a disposable cluster (e.g., kind) to verify the expected number of Applications are created.
3. Monitor the ApplicationSet controller’s metrics (argocd_applicationset_*) for reconciliation duration and error rates.
4. Document the generator logic so teammates understand how new instances are added.

By centralizing the template and letting the generator handle variation, you reduce YAML duplication while retaining the ability to tune each instance individually.