Manage Multi-Cluster Deployments with ArgoCD

Deploying applications across multiple Kubernetes clusters in production environments presents significant challenges that can slow down development teams and increase operational risk. Traditional approaches like manual deployments, custom scripts, or standard CI/CD pipelines often fall short when managing multiple clusters, leading to configuration drift, deployment inconsistencies, and increased maintenance overhead.

This guide demonstrates how ArgoCD ApplicationSets transform multi-cluster Kubernetes deployment management from a complex, error-prone process into a streamlined, automated workflow. You’ll learn practical steps to reduce deployment times by 83% while ensuring consistency across all your clusters.

• Reduce deployment time by 83%: ArgoCD ApplicationSets cut multi-cluster deployment cycles from 30+ minutes to just 5 minutes
• Eliminate manual errors: Declarative GitOps approach removes human error from deployment processes across multiple clusters
• Scale operations efficiently: Manage unlimited clusters without proportional increase in operational complexity
• Ensure environment consistency: Guarantee identical configurations across all clusters through centralized management
• Enable developer self-service: Platform teams can provide standardized deployment capabilities to development teams
• Simplify disaster recovery: Unified view and automated rollback capabilities across all clusters

Traditional multi-cluster deployment approaches create significant operational overhead and introduce multiple points of failure. Manual processes require teams to maintain separate deployment scripts for each cluster, leading to configuration drift and inconsistent environments. Custom automation solutions often lack standardization, making them difficult to maintain and scale as your infrastructure grows.

ApplicationSets solve these core challenges by providing declarative, automated management that scales efficiently across any number of clusters. Unlike traditional approaches that require separate management for each cluster, ApplicationSets use a single configuration to generate and manage deployments across all your clusters simultaneously.

Key Benefits of ApplicationSets

Centralized Configuration Management: Instead of maintaining separate deployment configurations for each cluster, ApplicationSets use a single template that automatically adapts to different cluster requirements through parameter substitution. This eliminates configuration drift and ensures consistency across all environments.

Automated Scaling: Adding new clusters to your deployment pipeline requires only updating the ApplicationSet configuration. The system automatically generates the necessary ArgoCD Applications for the new cluster without manual intervention.

Reduced Operational Overhead: Platform teams can manage hundreds of clusters with the same effort previously required for a handful. This enables organizations to scale their infrastructure without proportionally increasing their operational team size.

Enhanced Reliability: ApplicationSets provide built-in health monitoring and automatic remediation. If a deployment fails on one cluster, other clusters continue operating normally, and the system provides detailed status reporting for troubleshooting.

Developer Self-Service: Development teams can deploy applications across multiple clusters using standardized, pre-approved configurations without requiring platform team intervention for each deployment.

Disaster Recovery Simplified: With unified management, rolling back deployments across all clusters or recovering from failures becomes a single-command operation rather than a complex, error-prone manual process.

The diagram below illustrates how ApplicationSets transform the multi-cluster management landscape:

This implementation follows a centralized management pattern where ArgoCD runs on a central cluster and manages deployments across multiple remote clusters:

Prerequisites

Before implementing ArgoCD ApplicationSets, ensure you have:

1. Multiple Kubernetes clusters: At least 2 clusters (we’ll use region-a, region-b, and region-c for this example)
2. kubectl installed and configured: CLI tool must be installed with access to all target clusters
3. Cluster connectivity: Your kubectl configuration should include context entries for all clusters
4. Admin access: Sufficient permissions to install ArgoCD and manage cluster resources

Step 1: Install and Configure ArgoCD

First, deploy ArgoCD on your 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 UI:

# 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:

# 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 your 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 multiple ArgoCD Applications across your clusters.

Generators in ApplicationSets

ApplicationSet generators are the core mechanism that determines what applications to create and what parameters to pass to each application. Think of generators as “templates” that produce a list of parameter sets, where each parameter set results in one ArgoCD Application.

Generator → Parameter Sets → Applications

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

• The generator configuration defines the source of parameters (clusters, Git directories, lists, etc.)
• The generator produces a list of parameter sets, each containing key-value pairs
• Each parameter set is used to render the ApplicationSet template using Go template syntax ({{parameter}})
• Each rendered template becomes an individual 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: '{{name}}-sample-app'
     labels:
       region: '{{region}}'
   spec:
     project: default
     source:
       repoURL: https://github.com/argoproj/argocd-example-apps
       targetRevision: HEAD
       path: guestbook
     destination:
       server: '{{server}}'
       namespace: sample-app
     syncPolicy:
       automated:
         prune: true
         selfHeal: true
       syncOptions:
       - CreateNamespace=true

Key Concepts:

• generators: Defines which clusters to target
• template: Template for creating individual applications
• parameters: Values that get substituted in the template

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

The status output shows three key conditions:

Healthy ApplicationSet Status:

• ErrorOccurred: False - No errors in processing
• ParametersGenerated: True - Successfully created parameters for all target clusters
• ResourcesUpToDate: True - ApplicationSet is current and applications are generated

If you see this status, your ApplicationSet is working correctly!

# Watch applications being created 
kubectl get applications -n argocd 

# Check sync status with ArgoCD CLI
argocd app list

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

When working with ArgoCD ApplicationSets, you may encounter these common scenarios:

Monitor Synchronization

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

If applications are OutOfSync, you can manually sync:

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, check the deployed resources (You’ll need to switch 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 Not Creating 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 ApplicationSet controller logs:

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

Verify cluster connectivity:

argocd cluster list

Applications Stuck 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’s an issue with the ApplicationSet configuration
• ParametersGenerated: False = Parameters couldn’t be generated (check cluster connectivity)
• ResourcesUpToDate: False = ApplicationSet needs to reconcile (usually temporary)

1. What is the difference between ArgoCD Applications and ApplicationSets?

ArgoCD Applications manage individual deployments to specific clusters, while ApplicationSets are templates that automatically generate multiple Applications across different clusters. ApplicationSets use generators to create parameter sets, then render Application templates for each target cluster, enabling bulk deployment management.

2. How many clusters can ArgoCD ApplicationSets manage?

ArgoCD ApplicationSet does not have a defined maximum limit on the number of clusters it can manage. However, the practical scalability depends on various factors, including:

• Argo CD instance configuration: Proper tuning of Argo CD components, such as the application controller, is necessary to handle a large number of applications and clusters efficiently.

• Resource availability: The underlying infrastructure hosting Argo CD must have sufficient resources (CPU, memory) to support the management of numerous clusters and applications.

• Number of applications per cluster: A higher number of applications within each cluster will increase the load on Argo CD, potentially impacting performance.

• Network latency and reliability: Communication between the Argo CD instance and the managed clusters can become a bottleneck with a very large number of clusters or in environments with high latency.

For very large-scale deployments involving hundreds or thousands of clusters, it is often recommended to employ multiple Argo CD instances, each managing a subset of clusters, to distribute the load and improve performance and resilience. This approach also helps contain the “blast radius” in case of an outage in a single Argo CD instance.

3. Can I use ApplicationSets with different Kubernetes distributions?

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

4. What happens if one cluster fails during deployment?

ApplicationSets provide independent deployment to each cluster. If one cluster fails, other clusters continue deploying normally. ArgoCD provides detailed status reporting per cluster, allowing you to troubleshoot individual cluster issues without affecting others.

5. How do ApplicationSets handle secrets and configuration differences between clusters?

ApplicationSets support parameter substitution in templates, allowing you to pass cluster-specific values like resource limits, replica counts, or environment-specific configurations. For secrets, use ArgoCD’s secret management features or external secret operators to handle cluster-specific sensitive data.

ArgoCD ApplicationSets revolutionize multi-cluster Kubernetes deployment management by transforming complex, manual processes into streamlined, automated workflows. The results speak for themselves: deployment times reduced from 30+ minutes to just 5 minutes, operational overhead cut from requiring 3-4 engineers to self-service capabilities, and guaranteed environment consistency across all clusters.

By implementing the declarative GitOps approach demonstrated in this guide, platform engineering teams can provide developer self-service capabilities while maintaining control and observability. The unified management interface accelerates incident response and provides scalable operations that grow with your infrastructure without proportional complexity increases.

ApplicationSets transform multi-cluster management from an error-prone, manual burden into a reliable, automated system that enhances both developer experience and operational efficiency.

Ready to level up your Kubernetes deployments? Check out these next steps:

• Deploy ArgoCD on DigitalOcean: Get started with ArgoCD in just a few clicks.
• How to Deploy to Kubernetes Using ArgoCD and GitOps: Step-by-step tutorial to harness GitOps best practices with ArgoCD.
• Implementing GitOps using ArgoCD: Dive deeper into GitOps principles with practical ArgoCD guidance.

• ArgoCD ApplicationSet Documentation
• ArgoCD Official Documentation
• Kubernetes Multi-cluster Best Practices