Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Multi-cluster and ApplicationSets

Multi-cluster Management with Argo CD

Manage many Kubernetes clusters from one Argo CD: register clusters with the CLI or declarative Secrets, target them by name or URL, and choose a topology.

One Argo CD installation can deploy to many clusters. It runs in a single management cluster and reaches the others through the Kubernetes API using stored credentials. This lesson covers how a cluster is registered, how an Application targets it, and which topology to choose.

The built-in cluster

Every installation knows the cluster it runs in as https://kubernetes.default.svc, with the name in-cluster. An Application can deploy there without registering anything:

YAML
destination:
  name: in-cluster
  namespace: shop

Some teams disable the in-cluster target for safety once all workloads run elsewhere, via cluster.inClusterEnabled: "false" in argocd-cm.

Registering a cluster with the CLI

The CLI reads your kubeconfig. Pick a context name and register it:

Terminal
argocd cluster add prod-eu-1 --name prod-eu-1
argocd cluster list

What cluster add does behind the scenes:

  1. Creates a ServiceAccount argocd-manager in the kube-system namespace of the target cluster.
  2. Binds it to a ClusterRole with broad permissions (cluster-admin-like by default).
  3. Reads its token and stores the connection details in a Secret in the argocd namespace of the management cluster.

That Secret is the real registration. You can remove it with argocd cluster rm <server> (Argo CD does not delete the workloads).

Declarative registration

For GitOps-managed setups, create the Secret yourself. The label tells Argo CD it is a cluster:

YAML
apiVersion: v1
kind: Secret
metadata:
  name: cluster-prod-eu-1
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
    env: prod
    region: eu
type: Opaque
stringData:
  name: prod-eu-1
  server: https://k8s-eu-1.example.com:6443
  config: |
    {
      "bearerToken": "<token>",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64 CA>"
      }
    }

The extra labels (env, region) are what ApplicationSet cluster generators select on. Never commit the token itself in plain text; see Secrets in GitOps. Cloud providers offer token-less options (for example exec-based credentials, IAM roles for service accounts, workload identity) configured in the same config field.

Targeting a cluster

An Application chooses a cluster in destination with either name or server, never both:

YAML
destination:
  name: prod-eu-1            # preferred: readable, stable if the URL changes
  namespace: shop
YAML
destination:
  server: https://k8s-eu-1.example.com:6443
  namespace: shop

Using names keeps Application manifests readable and lets you re-point a name to a rebuilt cluster. AppProjects then limit which destinations an app may use (see Security and RBAC).

Limiting what Argo CD can do

The default argocd-manager role is powerful. You can narrow it:

  • Register the cluster with namespaces (namespaces in the Secret data, or --namespace on the CLI) so Argo CD manages only those namespaces and cannot list cluster-wide resources.
  • Set clusterResources: "true" only when cluster-scoped objects (CRDs, ClusterRoles) are needed.
  • Use a custom role for the ServiceAccount instead of cluster-admin and grant only the API groups you deploy.

Topologies

flowchart TB
  subgraph H["Hub and spoke"]
    A["Argo CD (management cluster)"] --> W1["Workload cluster 1"]
    A --> W2["Workload cluster 2"]
    A --> W3["Workload cluster 3"]
  end

One Argo CD manages many clusters.

Topology Description Strengths Weaknesses
Hub and spoke One central Argo CD reaches all clusters One UI, one audit trail, one place to upgrade Single point of failure; needs network paths and credentials for every cluster
Instance per cluster Argo CD in each cluster manages only itself Strong isolation, no stored remote credentials Many installs to upgrade; no combined view
Several hubs Separate Argo CD per environment or team Blast radius is limited More to operate; fewer shared dashboards

A reasonable default is a hub per environment tier (non-production and production), so a mistake in staging cannot reach production credentials.

Stand-in: which clusters does this app reach?

Python Stand-in: destination validation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Operating tips

  • Check connectivity with argocd cluster get <server>; the status shows the connection state and the API version seen.
  • Rotate tokens regularly and automate re-creating the cluster Secret.
  • Cluster names appear in many manifests; choose them once, e.g. <env>-<region>-<n>.
  • A private cluster API needs a network path from the application controller, not from your laptop.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the argocd cluster add command create in the target cluster?

    It creates the ServiceAccount and binding, then stores the token as a Secret in the management cluster.
  2. 2. Which label marks a Secret as a registered cluster?

    That label makes Argo CD treat the Secret as cluster credentials.
  3. 3. An Application destination may set:

    Setting both is invalid. A name is usually clearer.
  4. 4. What is a downside of hub and spoke?

    Centralization concentrates risk, so protect it and consider a hub per environment tier.

Summary

  • in-cluster is built in; other clusters are registered with argocd cluster add or a labelled Secret.
  • Applications target a cluster by name or server.
  • Narrow the default permissions with namespaces and custom roles.
  • Choose hub and spoke, one instance per cluster, or several hubs, based on isolation and operating cost.

Next: ApplicationSet Generators