Multi-Cluster Provider

The multicluster provider enables automatic cross-cluster service discovery and HTTP traffic distribution. A parent Traefik cluster automatically discovers workloads advertised by child clusters running on different infrastructure and creates routable services — no manual service registration required.

License Requirement

Multi-Cluster is a licensed feature. The multi-cluster feature must be included in your license for both parent and child clusters. Contact the Traefik Labs sales team for access.

This provider works in conjunction with:

Uplink Entry Points: Special entry points for inter-cluster communication on child clusters
Uplink: A resource that child clusters use to advertise workloads to parent clusters. Each provider exposes this concept in its own way (CRD for Kubernetes, labels for Docker, file configuration for the file provider, etc.)

Overview

The Multi-Cluster provider enables advanced traffic management patterns across clusters:

Weighted Load Balancing: Distribute traffic across multiple child clusters using weighted round-robin
Failover: Route traffic to backup clusters when primary clusters become unavailable
Canary Deployments: Gradually shift traffic between clusters during migrations
Traffic Mirroring: Mirror traffic to secondary clusters for testing

How It Works

Child clusters define Uplink Entry Points and create Uplink resources to advertise their workloads
Parent cluster configures the multicluster provider with the addresses of child clusters
The provider polls each child cluster to discover advertised workloads
Discovered workloads are materialized as services on the parent cluster
Parent cluster routers can then route traffic to these services, which automatically load balance across children

Configuration Example

Parent Cluster

The parent cluster configures the multicluster provider with the addresses of each child cluster:

Helm Chart
Install Configuration

hub:
  providers:
    multicluster:
      enabled: true
      pollInterval: 5
      pollTimeout: 5
      children:
        cluster-1:
          address: "https://child1-traefik.example.com:9443"
        cluster-2:
          address: "https://child2-traefik.example.com:9443"
          serversTransport:
            insecureSkipVerify: true

hub:
  providers:
    multicluster:
      pollInterval: 5s
      pollTimeout: 5s
      children:
        cluster-1:
          address: "https://child1-traefik.example.com:9443"
        cluster-2:
          address: "https://child2-traefik.example.com:9443"
          serversTransport:
            insecureSkipVerify: true

Child Cluster

Each child cluster must enable the multicluster provider. On Kubernetes, the kubernetescrd provider is also required to use Uplink CRDs:

Helm Chart
Install Configuration

hub:
  providers:
    multicluster:
      enabled: true

# Required when using Uplink CRDs (Kubernetes)
providers:
  kubernetesCRD:
    enabled: true

hub:
  providers:
    multicluster: {}

# Required when using Uplink CRDs (Kubernetes)
providers:
  kubernetescrd: {}

Configuration Options

Field	Description	Default	Required
`hub.providers.multicluster.enabled`	Enable the Multi-Cluster provider. Helm chart only — not needed when using install configuration.	`false`	Yes (Helm)
`hub.providers.multicluster.pollInterval`	Interval between polling child clusters for uplink updates.	`5s`	No
`hub.providers.multicluster.pollTimeout`	Timeout for polling requests to child clusters.	`5s`	No
`hub.providers.multicluster.children`	Map of child cluster configurations, keyed by a unique name.	`{}`	Yes
`hub.providers.multicluster.children.<name>.address`	URL of the child cluster's uplink entry point (e.g., `https://child:9443`).	`""`	Yes
`hub.providers.multicluster.children.<name>.serversTransport`	TLS and transport configuration for connecting to this child. See ServersTransport.	`null`	No

serversTransport

The serversTransport option configures the TLS settings and transport parameters used when communicating with a child cluster.

Field	Description	Default	Required
`serversTransport.serverName`	Server name used for SNI and certificate verification.	`""`	No
`serversTransport.insecureSkipVerify`	Disable TLS certificate verification. Not recommended for production.	`false`	No
`serversTransport.rootCAs`	List of root CA certificate file paths for verifying the child's server certificate.	`[]`	No
`serversTransport.certificates`	Client certificates for mTLS authentication with the child cluster.	`[]`	No
`serversTransport.certificates[].certFile`	Path to the client certificate file.	`""`	No
`serversTransport.certificates[].keyFile`	Path to the client private key file.	`""`	No
`serversTransport.cipherSuites`	List of cipher suites used when connecting to child clusters.	`[]` (Go defaults)	No
`serversTransport.minVersion`	Minimum TLS version for connections to child clusters (e.g., `VersionTLS12`, `VersionTLS13`).	`""` (Go default)	No
`serversTransport.maxVersion`	Maximum TLS version for connections to child clusters.	`""` (Go default)	No
`serversTransport.maxIdleConnsPerHost`	Maximum idle (keep-alive) connections per host. If zero, Go's default (`2`) is used. If negative, connection reuse is disabled.	`0`	No
`serversTransport.disableHTTP2`	Disable HTTP/2 for connections to child clusters.	`false`	No
`serversTransport.peerCertURI`	URI used to match against SAN URI during the child's certificate verification.	`""`	No
`serversTransport.forwardingTimeouts.dialTimeout`	Timeout for establishing connections to child clusters.	`30s`	No
`serversTransport.forwardingTimeouts.responseHeaderTimeout`	Timeout for reading response headers from child clusters.	`0s` (no timeout)	No
`serversTransport.forwardingTimeouts.idleConnTimeout`	Timeout for idle connections before closing.	`90s`	No
`serversTransport.forwardingTimeouts.readIdleTimeout`	Timeout after which an HTTP/2 health check ping is sent if no frame is received. If zero, no health check is performed.	`0s`	No
`serversTransport.forwardingTimeouts.pingTimeout`	Timeout after which the HTTP/2 connection is closed if no response to a ping is received.	`15s`	No
`serversTransport.spiffe.ids`	Allowed SPIFFE IDs for mTLS.	`[]`	No
`serversTransport.spiffe.trustDomain`	SPIFFE trust domain.	`""`	No

Auto-Generated Services

When child clusters advertise uplinks, the Multi-Cluster provider automatically creates services on the parent cluster. The service names follow this pattern:

Service Name	Pattern	Description
`banking@multicluster`	`<uplink-name>@multicluster`	Weighted round-robin across all children advertising this uplink
`banking-cluster-1@multicluster`	`<uplink-name>-<child-name>@multicluster`	Direct access to a specific child cluster

Where:

<uplink-name> is the uplink's expose name. For Kubernetes Uplinks, this defaults to <namespace>-<name> (e.g., banking-banking-api for an Uplink named banking-api in namespace banking). You can override it with spec.exposeName. For file provider uplinks, the name is used as-is.
<child-name> is the key used in the parent's children configuration (e.g., cluster-1, cluster-2).

Weighted Round-Robin Service

For each uplink name (e.g., banking), a weighted round-robin service is created that load balances across all children advertising that uplink:

# Auto-generated service: banking@multicluster
services:
  banking:
    weighted:
      services:
        - name: banking-cluster-1
          weight: 10 # From child's uplink weight
        - name: banking-cluster-2
          weight: 5

You can also create your own weighted service on the parent and target the per-child services directly. This lets you override child weights at the parent level. Use the uplink expose name as the prefix (defaults to <namespace>-<name> when spec.exposeName is not set):

apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
  name: banking-parent-weights
  namespace: apps
spec:
  weighted:
    services:
      - name: banking-cluster-1@multicluster
        kind: TraefikService
        weight: 90
      - name: banking-cluster-2@multicluster
        kind: TraefikService
        weight: 10

Per-Child Services

Individual services are also created for each child advertising an uplink, allowing direct routing to specific clusters:

# Auto-generated services for direct child access
services:
  banking-cluster-1:
    loadBalancer:
      servers:
        - url: "https://child1-traefik.example.com:9443"

  banking-cluster-2:
    loadBalancer:
      servers:
        - url: "https://child2-traefik.example.com:9443"

Using Multi-Cluster Services

Once child clusters advertise uplinks, you can reference the auto-generated services in your parent cluster's routing configuration (<uplink>-<child-cluster-name>@multicluster):

Routing Configuration
Kubernetes IngressRoute

http:
  routers:
    banking-router:
      rule: "PathPrefix(`/banking`)"
      entryPoints:
        - websecure
      service: banking@multicluster # WRR across all children
      middlewares:
        - strip-prefix

    banking-primary:
      rule: "PathPrefix(`/banking`) && Header(`X-Route-To`, `primary`)"
      entryPoints:
        - websecure
      service: banking-cluster-1@multicluster # Direct to cluster-1
      middlewares:
        - strip-prefix

  middlewares:
    strip-prefix:
      stripPrefix:
        prefixes:
          - "/banking"

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: banking-route
  namespace: apps
spec:
  entryPoints:
    - websecure
  routes:
    - match: PathPrefix(`/banking`)
      kind: Rule
      services:
        - name: banking@multicluster
          kind: TraefikService
      middlewares:
        - name: strip-prefix

Advanced Patterns

Failover Configuration

Use a failover service to automatically route to a backup cluster when the primary fails:

http:
  services:
    banking-failover:
      failover:
        service: banking-cluster-1@multicluster
        fallback: banking-cluster-2@multicluster
        # Circuit breaker on child clusters triggers failover

  routers:
    banking:
      rule: "PathPrefix(`/banking`)"
      service: banking-failover

Traffic Mirroring

Mirror a percentage of traffic to a secondary cluster for testing:

http:
  services:
    banking-mirrored:
      mirroring:
        service: banking-cluster-1@multicluster
        mirrors:
          - name: banking-cluster-2@multicluster
            percent: 10

Canary Deployment

Gradually shift traffic between clusters:

http:
  services:
    banking-canary:
      weighted:
        services:
          - name: banking-cluster-1@multicluster
            weight: 90
          - name: banking-cluster-2@multicluster
            weight: 10

Uplink Entry Points: Configure entry points on child clusters for inter-cluster communication
Uplink Resource: Define uplinks on child clusters to advertise workloads
ServersTransport: Detailed TLS configuration reference

Overview​

How It Works​

Configuration Example​

Parent Cluster​

Child Cluster​

Configuration Options​

serversTransport​

Auto-Generated Services​

Weighted Round-Robin Service​

Per-Child Services​

Using Multi-Cluster Services​

Advanced Patterns​

Failover Configuration​

Traffic Mirroring​

Canary Deployment​

Related Content​