Multiple clusters with one 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.

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

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

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

Example

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:

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).

​Configure

​Example

​Namespaces

​Tokens

​Field reference

​Related

Configure

Example

Namespaces

Tokens

Field reference

Related