argocd cluster add my-context # registers a cluster
# Application targets it:
destination:
server: https://remote-cluster-api
namespace: app
ArgoCD
Topics in this category
ArgoCD
Multi-cluster
A single ArgoCD instance can deploy to many clusters. You register external clusters (their API server and credentials are stored as secrets), then Applications set their destination.server (or name) to the target cluster. The ArgoCD control plane runs in one cluster and pushes desired state to the registered remote clusters.
Real-world example
One central ArgoCD deploys to dev, staging, and prod clusters by targeting each cluster's API in the Application destination.
Applications
App of Apps
Multi-cluster
Use `argocd cluster add <context>` (which creates a service account and stores credentials as a cluster Secret), or declaratively create a cluster Secret with the API URL, credentials, and the argocd.argoproj.io/secret-type: cluster label. ArgoCD then lists it as a deployment destination.
kind: Secret
metadata:
labels:
argocd.argoproj.io/secret-type: cluster
stringData:
server: https://remote-api
config: '{"bearerToken":"...","tlsClientConfig":{...}}'
Real-world example
A new prod cluster is registered by applying a labeled cluster Secret, after which apps can target it.
RBAC
Applications
Multi-cluster
The in-cluster destination (https://kubernetes.default.svc) is the cluster ArgoCD runs in—no separate credentials needed. External clusters are remote and require stored credentials/secrets. Applications choose by destination.server URL or by the cluster's registered name via destination.name.
destination:
server: https://kubernetes.default.svc # in-cluster
# or
destination:
name: prod-eu # external, by name
Real-world example
Platform tooling deploys in-cluster while business apps target the remote prod cluster by name.
Applications
App of Apps
Multi-cluster
Hub-and-spoke runs one central ArgoCD (the hub) managing many remote clusters (spokes)—simple governance, single pane of glass, but the hub is critical and needs network/credentials to all clusters. The alternative runs an ArgoCD per cluster—more isolation and resilience, but more instances to operate. Choice depends on scale, security, and blast-radius tolerance.
Real-world example
A company uses hub-and-spoke for central control, accepting that the hub cluster must reach every spoke's API.
App of Apps
RBAC
Multi-cluster
Use an ApplicationSet with a cluster generator, which creates one Application per registered cluster from a single template, keeping them consistent and auto-adding new clusters. Combine with cluster labels to target subsets (e.g., only prod clusters) and per-cluster values for regional differences.
generators:
- clusters:
selector:
matchLabels: { env: prod }
template:
spec:
destination: { server: '{{server}}', namespace: app }
Real-world example
Adding a new prod cluster automatically gets the app deployed to it via the cluster-generator ApplicationSet.
Applications
App of Apps
Multi-cluster
Credentials are stored as Kubernetes Secrets in the argocd namespace, ideally managed via sealed/external secrets rather than plaintext. Use least-privilege service accounts on target clusters (scoped RBAC), rotate tokens, and consider short-lived credentials (e.g., IRSA/workload identity) instead of long-lived bearer tokens.
Real-world example
Target-cluster access uses a scoped service account with only the permissions ArgoCD needs, with tokens rotated regularly.
RBAC
Applications
Multi-cluster
Parameterize by cluster: use ApplicationSet generator values (cluster name, labels, region) injected into templates, per-cluster Helm values or Kustomize overlays selected by cluster, and cluster labels to drive which apps deploy where. This keeps a shared base while allowing region- or size-specific settings per cluster.
template:
spec:
source:
helm:
valueFiles: ['values-{{metadata.labels.region}}.yaml']
Real-world example
Each cluster picks a region-specific values file, so EU and US clusters get appropriate endpoints and sizes from one template.
Applications
App of Apps
Multi-cluster
Label registered clusters (e.g., env=prod, region=eu) and use a cluster generator selector with matchLabels/matchExpressions to include only matching clusters. This lets one ApplicationSet deploy to just the intended fleet subset and automatically include new clusters that match the labels.
generators:
- clusters:
selector:
matchLabels: { env: prod }
Real-world example
A monitoring stack ApplicationSet deploys only to clusters labeled env=prod via the selector.
Applications
App of Apps
Multi-cluster
In hub-and-spoke, hub outage stops deployments to all spokes (though running workloads keep running), and the hub needs reliable network to every API. Mitigations: HA ArgoCD, backups of app definitions in Git (rebuildable), regional/independent instances for critical isolation, and monitoring connectivity to each cluster.
Real-world example
The hub ArgoCD is run HA and its config lives in Git, so a hub failure is recoverable and doesn't affect already-running workloads.
App of Apps
RBAC
Multi-cluster
Can one ArgoCD instance deploy to the cluster it runs in and remote clusters simultaneously?
BeginnerYes. ArgoCD treats its own cluster (in-cluster) and registered remote clusters as destinations. Applications simply set the appropriate destination. So a single instance can manage local platform components and remote workload clusters at the same time.
Real-world example
The management cluster's ArgoCD deploys its own ingress locally and application workloads to three remote clusters.
Applications
App of Apps
Multi-cluster