Managing Multi-Cluster Kubernetes Deployments with ArgoCD ApplicationSets

Running applications across several Kubernetes clusters in production can become difficult for development and operations teams. It may slow delivery, increase complexity, and create additional operational risk. Common methods such as manual rollouts, custom deployment scripts, or basic CI/CD pipelines often become insufficient once multiple clusters need to be managed. These approaches can result in configuration drift, inconsistent deployments, and higher maintenance effort.

This guide explains how ArgoCD ApplicationSets can turn multi-cluster Kubernetes deployment management from a complex and error-prone task into a structured, automated workflow. You will see how this approach can reduce deployment time by 83% while keeping configurations consistent across all clusters.

Key Takeaways

• Reduce deployment time by 83%: ArgoCD ApplicationSets can shorten multi-cluster deployment cycles from more than 30 minutes to around 5 minutes.
• Remove manual errors: A declarative GitOps workflow helps eliminate human mistakes during deployments across several clusters.
• Scale operations efficiently: Multiple clusters can be managed without increasing operational complexity at the same rate.
• Maintain environment consistency: Centralized management helps ensure identical configuration standards across all clusters.
• Enable developer self-service: Platform teams can offer standardized deployment options to development teams.
• Simplify disaster recovery: A unified overview and automated rollback options make recovery easier across all clusters.

Why ArgoCD ApplicationSets Improve Multi-Cluster Management

Traditional approaches to multi-cluster deployment often create considerable operational overhead and introduce several possible failure points. Manual workflows require teams to manage individual deployment scripts for each cluster. This can lead to configuration drift and inconsistent environments. Custom automation can also become difficult to standardize, maintain, and scale as the infrastructure grows.

ApplicationSets address these challenges by offering declarative and automated management that scales across any number of clusters. Instead of managing every cluster separately, ApplicationSets use one configuration to generate and control deployments across all clusters at the same time.

Key Benefits of ApplicationSets

• Centralized Configuration Management: Rather than maintaining separate deployment definitions for each cluster, ApplicationSets use one template that adapts automatically to different cluster requirements through parameter substitution. This helps avoid configuration drift and keeps environments consistent.
• Automated Scaling: Adding a new cluster to the deployment workflow only requires an update to the ApplicationSet configuration. The system then automatically creates the required ArgoCD Applications for the new cluster without manual steps.
• Reduced Operational Overhead: Platform teams can manage hundreds of clusters with the same effort that was previously needed for only a small number of clusters. This allows organizations to scale their infrastructure without growing the operations team at the same pace.
• Improved Reliability: ApplicationSets include health monitoring and automated remediation options. If a deployment fails on one cluster, the remaining clusters can continue running normally, while the system provides detailed status information for troubleshooting.
• Developer Self-Service: Development teams can deploy applications across multiple clusters by using standardized and approved configurations, without requiring platform team involvement for every deployment.
• Simplified Disaster Recovery: Because management is unified, rolling back deployments across all clusters or recovering from failures becomes a single-command operation instead of a complicated and error-prone manual process.

Step-by-Step Implementation Guide

This implementation uses a centralized management model. In this setup, ArgoCD runs on a central cluster and manages deployments across several remote Kubernetes clusters:

Prerequisites

Before setting up ArgoCD ApplicationSets, make sure the following requirements are met:

• Multiple Kubernetes clusters: At least two clusters are required. This example uses region-a, region-b, and region-c.
• kubectl installed and configured: The CLI tool must be installed and configured with access to all target clusters.
• Cluster connectivity: The kubectl configuration should contain context entries for all clusters.
• Admin access: You need sufficient permissions to install ArgoCD and manage cluster resources.

Step 1: Install and Configure ArgoCD

Start by deploying ArgoCD on the central management cluster:

# Create namespace
kubectl create namespace argocd

# Install ArgoCD
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Wait for deployment
kubectl wait --for=condition=available --timeout=300s deployment/argocd-server -n argocd

Access the ArgoCD user interface:

# Get initial admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

# Port forward to access UI
kubectl port-forward svc/argocd-server -n argocd 8080:443

# Or expose via LoadBalancer/Ingress
kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'

Install and Configure the ArgoCD CLI

Install and configure the ArgoCD CLI:

# macOS
brew install argocd

# Login via CLI
argocd login localhost:8080 --username admin --password <initial-password>

# Change admin password
argocd account update-password

Step 2: Connect Remote Clusters

Add the target clusters to ArgoCD:

# List available contexts
kubectl config get-contexts

# Add each remote cluster
argocd cluster add <region-a-cluster> --name region-a
argocd cluster add <region-b-cluster> --name region-b
argocd cluster add <region-c-cluster> --name region-c

# Verify clusters
argocd cluster list

Step 3: Create ApplicationSets for Automated Deployment

ApplicationSets use generators to automatically create several ArgoCD Applications across your clusters.

Generators in ApplicationSets

ApplicationSet generators are the central mechanism that decides which applications should be created and which parameters should be passed to each one. Generators can be understood as templates that create a list of parameter sets. Each parameter set then produces one ArgoCD Application.

Generator → Parameter Sets → Applications

A generator takes a configuration and produces parameter sets. Each parameter set is used to render the ApplicationSet template, which creates individual ArgoCD Applications.

• The generator configuration defines where parameters come from, such as clusters, Git directories, lists, or other sources.
• The generator creates a list of parameter sets, with each set containing key-value pairs.
• Each parameter set renders the ApplicationSet template by using Go template syntax such as .
• Each rendered template becomes a separate ArgoCD Application.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
 name: sample-app-set
 namespace: argocd
spec:
 generators:
 - list:
     elements:
     - cluster: region-a
       name: region-a
       server: < region-a cluster >
       region: region-a
       replicas: "1"
       resources: "small"
     - cluster: region-b
       name: region-b
       server: < region-b cluster >
       region: region-b
       replicas: "2"
       resources: "medium"
     - cluster: region-c
       name: region-c
       server: < region-c cluster >
       region: region-c
       replicas: "3"
       resources: "large"
 template:
   metadata:
     name: '-sample-app'
     labels:
       region: ''
   spec:
     project: default
     source:
       repoURL: https://github.com/argoproj/argocd-example-apps
       targetRevision: HEAD
       path: guestbook
     destination:
       server: ''
       namespace: sample-app
     syncPolicy:
       automated:
         prune: true
         selfHeal: true
       syncOptions:
       - CreateNamespace=true

Key Concepts

• generators: Defines which clusters should be targeted.
• template: Provides the template used to create individual applications.
• parameters: Values that are substituted into the template.

# Get detailed information
kubectl describe applicationset sample-app-set -n argocd

The status output shows three important conditions:

Healthy ApplicationSet Status

• ErrorOccurred: False – No processing errors were detected.
• ParametersGenerated: True – Parameters were successfully created for all target clusters.
• ResourcesUpToDate: True – The ApplicationSet is current, and the applications have been generated.

If this status appears, the ApplicationSet is functioning correctly.

# Watch applications being created 
kubectl get applications -n argocd 

ArgoCD ApplicationSet sync status

# Check sync status with ArgoCD CLI
argocd app list

# Get detailed app information
argocd app get region-a-sample-app

How to Troubleshoot Common Issues in ApplicationSets

When using ArgoCD ApplicationSets, the following common situations may occur:

Monitor Synchronization

# Check sync status
argocd app list | grep sample-app

If applications are shown as OutOfSync, they can be synchronized manually:

argocd app sync dev-sample-app
argocd app sync staging-sample-app
argocd app sync production-sample-app

Verify Deployments in Target Clusters

For each cluster, verify the deployed resources. You need to switch the kubectl context for each cluster.

# Dev cluster
kubectl config use-context dev-cluster-context
kubectl get all -n sample-app

# Staging cluster 
kubectl config use-context staging-cluster-context
kubectl get all -n sample-app

# Production cluster
kubectl config use-context production-cluster-context
kubectl get all -n sample-app

ApplicationSet Does Not Create Applications

# Check ApplicationSet status first
kubectl describe applicationset sample-app-set -n argocd

# Look for status conditions:
# - ErrorOccurred: Should be False
# - ParametersGenerated: Should be True 
# - ResourcesUpToDate: Should be True

Check the logs of the ApplicationSet controller:

kubectl logs -n argocd deployment/argocd-applicationset-controller

Verify the cluster connection:

argocd cluster list

Applications Remain Stuck in OutOfSync

# Check application details
argocd app get <app-name>

# Force sync
argocd app sync <app-name> --force

Permission Issues

# Check RBAC permissions
kubectl describe clusterrole argocd-application-controller

# Verify service account
kubectl get serviceaccount argocd-application-controller -n argocd

Common Status Meanings

• ErrorOccurred: True = There is a problem with the ApplicationSet configuration.
• ParametersGenerated: False = Parameters could not be generated. Cluster connectivity should be checked.
• ResourcesUpToDate: False = The ApplicationSet needs to reconcile. This is usually temporary.

Frequently Asked Questions

What is the difference between ArgoCD Applications and ApplicationSets?

ArgoCD Applications manage individual deployments to specific clusters. ApplicationSets, on the other hand, are templates that automatically create several Applications across different clusters. ApplicationSets use generators to create parameter sets and then render Application templates for each target cluster. This makes bulk deployment management possible.

How many clusters can ArgoCD ApplicationSets manage?

ArgoCD ApplicationSet does not define a fixed maximum number of clusters that can be managed. In practice, scalability depends on several factors, including:

Argo CD instance configuration: Argo CD components such as the application controller need to be tuned correctly so they can efficiently handle many applications and clusters.

Resource availability: The infrastructure that hosts Argo CD must provide enough CPU and memory resources to manage many clusters and applications.

Number of applications per cluster: More applications in each cluster increase the load on Argo CD and may affect performance.

Network latency and reliability: Communication between the Argo CD instance and the managed clusters can become a bottleneck when many clusters are involved or when environments have high latency.

For very large deployments with hundreds or thousands of clusters, it is often recommended to use multiple Argo CD instances. Each instance can manage a subset of clusters, which distributes the load and improves performance and resilience. This also limits the blast radius if one Argo CD instance experiences an outage.

Can ApplicationSets be used with different Kubernetes distributions?

Yes. ApplicationSets work with any CNCF-certified Kubernetes distribution, including EKS, GKE, AKS, OpenShift, and self-managed clusters. The main requirement is that ArgoCD can authenticate with and connect to the API server of each cluster.

What happens if one cluster fails during deployment?

ApplicationSets deploy independently to each cluster. If one cluster fails, the other clusters can continue deploying normally. ArgoCD provides detailed status information for each cluster, so individual cluster issues can be investigated without affecting the remaining clusters.

How do ApplicationSets handle secrets and configuration differences between clusters?

ApplicationSets support parameter substitution in templates. This allows cluster-specific values such as resource limits, replica counts, or environment-specific settings to be passed into the generated Applications. For secrets, ArgoCD secret management features or external secret operators can be used to manage cluster-specific sensitive data.

Conclusion

ArgoCD ApplicationSets improve multi-cluster Kubernetes deployment management by turning complex manual processes into streamlined and automated workflows. The results are clear: deployment times can be reduced from more than 30 minutes to around 5 minutes, operational effort can shift from requiring 3 to 4 engineers toward self-service capabilities, and environment consistency can be maintained across all clusters.

By using the declarative GitOps approach shown in this guide, platform engineering teams can provide developer self-service while retaining control and observability. The unified management interface speeds up incident response and supports scalable operations that can grow with the infrastructure without increasing complexity at the same rate.

ApplicationSets turn multi-cluster management from a manual and error-prone burden into a reliable automated system that improves both developer experience and operational efficiency.