> For the complete documentation index, see [llms.txt](https://dinush-chathurya.gitbook.io/kustomize-e-book/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dinush-chathurya.gitbook.io/kustomize-e-book/production-ready-practices/13-multi-cluster-deployments.md).

# Multi-Cluster Deployments

Running workloads across multiple Kubernetes clusters can increase availability, enable geo-distribution, and support isolation of environments. In this chapter, we’ll explore how to design and manage multi-cluster deployments using Kustomize and GitOps.

***

## Why Multi-Cluster?

* **High Availability**: Spread workloads across regions to tolerate failures.
* **Data Residency**: Comply with local regulations by hosting in specific geographies.
* **Environment Isolation**: Separate dev, staging, and production into different clusters for safety.
* **Scalability**: Allocate resources dedicated to workloads with varying SLAs.

***

## Common Cluster Topologies

1. **Hub-Spoke**
   * A central “hub” cluster holds GitOps control plane (e.g., ArgoCD).
   * “Spoke” clusters run applications.
2. **Mesh**
   * Each cluster runs its own control plane but communicates with peers.
3. **Environment-Per-Cluster**
   * One cluster for dev, one for staging, one for prod.

***

## Git Repository Layouts

### Monorepo

```yaml
git-repo/
├── clusters/
│   ├── dev/          # overlays/dev
│   ├── staging/      # overlays/staging
│   └── prod/         # overlays/prod
└── apps/
    └── my-service/   # base Kustomize config
```

### Polyrepo

* **apps/** repos: contain base + overlays for each service
* **clusters/** repo: contains cluster-specific ArgoCD or ApplicationSet definitions

***

## Kustomize for Multi-Cluster

Use overlays per cluster under a common base:

```yaml
apps/my-service/
├── base/
│   └── kustomization.yaml
└── overlays/
    ├── dev-cluster/
    │   └── kustomization.yaml
    ├── eu-cluster/
    │   └── kustomization.yaml
    └── prod-cluster/
        └── kustomization.yaml
```

Each `overlays/<cluster>/kustomization.yaml` references `../../base` and applies cluster-specific patches.

***

## ArgoCD Multi-Cluster Setup

### ApplicationSet Example

Use the [ArgoCD ApplicationSet](https://argocd-applicationset.readthedocs.io/) for dynamic multi-cluster deployments:

```yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-service-multicluster
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            env: staging
  template:
    metadata:
      name: my-service-{{cluster.name}}
    spec:
      project: default
      source:
        repoURL: https://github.com/your-org/git-repo.git
        path: apps/my-service/overlays/{{cluster.name}}
        targetRevision: main
      destination:
        server: https://{{cluster.server}}
        namespace: my-service-namespace
      syncPolicy:
        automated: {}
```

This automatically creates one Application per matching cluster.

## Monitoring & Observability

* **Centralized Logging/Tracing**: Use a mesh (e.g., Fluentd → Elasticsearch) across clusters.
* **Cross-Cluster Metrics**: Aggregate Prometheus metrics with Thanos or Cortex.
* **Cluster Health Dashboards**: Use Grafana dashboards per cluster.

## Best Practices

* **Label Clusters Consistently**: Facilitate selection in ApplicationSets.
* **Namespace Isolation**: Don’t share namespaces across clusters for security.
* **Config Drift Detection**: Use ArgoCD’s health and diff features to catch drift.
* **Resource Quotas**: Enforce quotas per cluster to prevent runaway consumption.
* **Disaster Recovery Plans**: Backup Kustomize repos, cluster state, and etcd snapshots.

## Summary

Multi-cluster deployments enhance reliability, compliance, and scalability but add operational complexity. By organizing your Kustomize overlays per cluster, leveraging ArgoCD ApplicationSets, and enforcing robust monitoring and security practices, you can manage many clusters at scale with confidence.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://dinush-chathurya.gitbook.io/kustomize-e-book/production-ready-practices/13-multi-cluster-deployments.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.