> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multiple clusters with one TFY Agent

> Run one physical Kubernetes cluster as multiple logical clusters in TrueFoundry using a single tfy-agent.

Register **multiple clusters in TrueFoundry** against the **same physical Kubernetes cluster**, with only **one** `tfy-agent` and **one** `tfy-agent-proxy`. Use this when teams share one cluster but need separate cluster views, tokens, and namespace boundaries.

<Note>
  This is not multiple physical clusters and not one agent per team. For separate physical clusters, install a normal single-cluster agent on each.
</Note>

```text theme={"dark"}
Physical Kubernetes cluster
│
├── Logical cluster: team-a      → namespaces: ns-a, ns-shared
├── Logical cluster: team-b      → namespaces: ns-b, ns-shared
└── Logical cluster: platform    → namespaces: *  (everything)

        ▲
   one tfy-agent + one tfy-agent-proxy
        ▼
   TrueFoundry control plane
```

## Configure

1. Create each logical cluster in TrueFoundry and copy its **cluster token**.
2. Set `clustersConfig` in your `tfy-agent` Helm values with **more than one** entry (that enables multi-logical mode).
3. Upgrade / install the chart, then confirm each logical cluster shows as **connected** in the UI.

### Example

```yaml theme={"dark"}
clustersConfig:
  - name: team-a
    token: "<CLUSTER_TOKEN_FOR_TEAM_A>"
    controlPlaneURL: https://your-control-plane.example.com
    tenantName: your-tenant
    namespaces:
      - ns-a
      - ns-shared

  - name: team-b
    token: "<CLUSTER_TOKEN_FOR_TEAM_B>"
    controlPlaneURL: https://your-control-plane.example.com
    tenantName: your-tenant
    namespaces:
      - ns-b
      - ns-shared

  - name: platform
    token: "<CLUSTER_TOKEN_FOR_PLATFORM>"
    controlPlaneURL: https://your-control-plane.example.com
    tenantName: your-tenant
    namespaces:
      - "*"
```

### Namespaces

| Configuration | Meaning |
| - | - |
| `namespaces: ["ns-a", "ns-b"]` | Only those namespaces under that logical cluster |
| `namespaces: ["*"]` | All namespaces on the physical cluster |
| Same namespace on multiple logical clusters | Allowed; shown under each |
| Namespace not listed anywhere, and no cluster has `*` | Not shown under any logical cluster |

There is no default leftover cluster — unmatched namespaces are ignored.

### Tokens

Use **one** style for every logical cluster. Do not mix.

| Style | What you set |
| - | - |
| Pass tokens in Helm values | Set `token` on every `clustersConfig` entry. Do not set `config.clusterTokenSecret`. |
| Use a Kubernetes Secret | Set `config.clusterTokenSecret` once, put every cluster token in that Secret, and set `tokenSecretKey` on every entry (omit `token`). |

If you use a Secret for one logical cluster, you must use that Secret approach for **all** of them. If you pass a token directly for one logical cluster, you must pass tokens directly for **all** of them.

Secret example:

```yaml theme={"dark"}
config:
  clusterTokenSecret: my-tfy-agent-tokens

clustersConfig:
  - name: team-a
    tokenSecretKey: CLUSTER_TOKEN_TEAM_A
    controlPlaneURL: https://your-control-plane.example.com
    tenantName: your-tenant
    namespaces:
      - ns-a
      - ns-shared

  - name: team-b
    tokenSecretKey: CLUSTER_TOKEN_TEAM_B
    controlPlaneURL: https://your-control-plane.example.com
    tenantName: your-tenant
    namespaces:
      - ns-b
      - ns-shared
```

### Field reference

| Field | Required | Description |
| - | - | - |
| `name` | Yes | Friendly name for this logical cluster entry |
| `token` | Yes if not using Secret | Cluster token from TrueFoundry. Required on every entry when `config.clusterTokenSecret` is not set |
| `tokenSecretKey` | Yes if using Secret | Key in the Secret for this cluster’s token. Defaults to `CLUSTER_TOKEN_<name>` |
| `controlPlaneURL` | Yes | Control plane URL for this logical cluster |
| `tenantName` | Yes | Tenant name for this logical cluster |
| `namespaces` | Yes | Non-empty list of namespaces, or `["*"]` for all |
| `clusterSecretStoreName` | No | Override for the External Secrets store name (defaults to `tfy-secret-store-<tenantName>`) |

For a single logical cluster, keep using the normal install (`config.clusterToken` only, empty `clustersConfig`).

## Related

* [TFY Agent overview](/docs/tfy-agent)
* [tfy-agent Helm chart](https://github.com/truefoundry/infra-charts/tree/main/charts/tfy-agent)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.