Skip to main content

Uplink EntryPoints

Uplink Entry Points are specialized entry points used for inter-cluster communication in multi-cluster deployments. They are configured on child clusters and serve two purposes:

  1. Expose advertised workloads: Parent clusters poll child clusters to discover advertised workloads
  2. Receive forwarded traffic: Parent clusters forward traffic to child clusters through these entry points

Overview​

Uplink Entry Points are separate from regular entry points to ensure proper isolation:

  • Regular entry points handle direct client traffic
  • Uplink entry points handle inter-cluster traffic from parent clusters

This separation prevents routers without explicit entry points from accidentally receiving inter-cluster traffic.

Configuration Example​

Configure uplink entry points on child clusters in the Hub static configuration:

ports:
  multicluster:
    port: 9443
    uplink: true
    asDefault: true
    expose:
      default: true
    http:
      tls:
        enabled: true

Configuration Options​

Uplink entry points support the same configuration options as regular entry points. The key options are:

FieldDescriptionDefaultRequired
hub.uplinkEntryPoints.<name>.addressThe address to listen on, in the format [host]:port.-Yes
hub.uplinkEntryPoints.<name>.asDefaultMark this uplink entry point as default. Uplinks without explicit entryPoints use default uplink entry points.falseNo
hub.uplinkEntryPoints.<name>.http.tlsEnable TLS on this entry point. Recommended for production.-No
hub.uplinkEntryPoints.<name>.http.tls.optionsReference a TLSOption for advanced TLS settings.-No
hub.uplinkEntryPoints.<name>.http.tls.certResolverUse a certificate resolver (e.g., Let's Encrypt) for automatic certificates.-No
hub.uplinkEntryPoints.<name>.proxyProtocol.trustedIPsTrust PROXY protocol headers from these IPs. Useful when behind a load balancer.-No
hub.uplinkEntryPoints.<name>.transport.respondingTimeouts.readTimeoutMaximum duration for reading the entire request.60sNo
hub.uplinkEntryPoints.<name>.transport.respondingTimeouts.writeTimeoutMaximum duration for writing the response.0sNo

For a complete list of options, see the EntryPoints reference.

Default Behavior​

The asDefault option controls which uplink entry points are used when an Uplink resource doesn't specify explicit entry points:

  • If no uplink entry point has asDefault: true: All uplink entry points will publish the route with the uplink reference
  • If at least one uplink entry point has asDefault: true: Only those marked as default will publish the route with the uplink reference

This mirrors the behavior of regular entry points.

Example: Default vs Explicit Entry Points​

hub:
  uplinkEntryPoints:
    public:
      address: ":9443"
      asDefault: true # Used by uplinks without explicit entryPoints
    internal:
      address: ":9443"
      asDefault: false # Only used when explicitly referenced

Validation Rules​

Uplink entry points have specific validation rules:

  1. No name conflicts: Uplink entry point names must not conflict with regular entry point names
  2. HTTP only: Uplink entry points handle HTTP traffic only. UDP protocol is not supported in the entry point address.
# Invalid: conflicts with regular entryPoint named "websecure"
entryPoints:
  websecure:
    address: ":443"

hub:
  uplinkEntryPoints:
    websecure: # Error: conflicts with regular entryPoint
      address: ":9443"

Security Considerations​

Uplink entry points share TLS and transport configuration options with regular entry points, but they differ in what they expose and how authentication works:

AspectRegular EntryPointUplink EntryPoint
TrafficDirect client requestsInter-cluster traffic from parent
Discovery APINoneExposes GET /uplinks for parent polling
AuthenticationMiddlewares on the router (JWT, BasicAuth, etc.)Typically handled on the parent cluster — child routes on this port are accessible without parent-side auth
TLSStandard TLSmTLS recommended — the child verifies the parent's client certificate
Network accessPublic-facingShould be restricted to parent cluster IPs
Key difference

Authentication middlewares configured on the parent cluster do not protect the uplink entry point. If the uplink port is publicly reachable, an attacker can discover advertised routes via the discovery API and send requests directly to child routers, bypassing the parent entirely.

To secure uplink entry points:

  • Restrict network access: Use firewall rules or private networks so only the parent cluster can reach the uplink port.
  • Enable mTLS: Configure mutual TLS so the child verifies the parent's client certificate (see TLS Configuration below and Securing Inter-Cluster Communication).
  • Add child-side middlewares (e.g., IP allowlisting, rate limiting) for defense-in-depth.

TLS Configuration​

For production deployments, always enable TLS on uplink entry points:

# Child cluster
hub:
  uplinkEntryPoints:
    multicluster:
      address: ":9443"
      http:
        tls: {} # Traefik generates a self-signed certificate
warning

When tls: {} is set without explicit certificates, Traefik generates an ephemeral self-signed certificate in memory at each startup. This certificate is not written to disk and changes on every restart, so the parent cluster cannot pin or trust it with rootCAs. Instead, the parent must skip server certificate verification:

# Parent cluster - child configuration
hub:
  providers:
    multicluster:
      children:
        cluster-1:
          address: "https://child-address:9443"
          serversTransport:
            insecureSkipVerify: true # Required for self-signed certs

This disables server identity verification and should only be used for development. For production, use Custom Certificates or Let's Encrypt so the parent can verify the child's identity.

Network Considerations​

When deploying multi-cluster setups:

  1. Firewall Rules: Restrict access to the uplink port so that only the parent cluster can reach it. Without mTLS, any client that can reach the uplink port can forge the internal Hub-Uplink header and access child routes directly.
  2. Load Balancers: If using load balancers in front of child clusters, configure them to forward to the uplink entry point port. Consider using internal load balancers that are not publicly accessible.
  3. Service Exposure: In Kubernetes, expose uplink entry points via a Service (LoadBalancer or NodePort). When using the Helm chart with expose.default: true, the uplink port is automatically added to the existing Traefik LoadBalancer service — no separate service is needed.
caution

The uplink entry point does not validate the Hub-Uplink header used for internal routing. If the uplink port is publicly reachable without mTLS, a malicious client can craft requests with this header to access any route advertised through the uplink. Always use mTLS (see Security Considerations) or strict firewall rules (allow only parent cluster IPs) to protect the uplink port in production.

Kubernetes Service Example (non-Helm)​

If you are not using the Helm chart, create a Kubernetes Service to expose the uplink entry point. You can add the uplink port to your existing Traefik service:

apiVersion: v1
kind: Service
metadata:
  name: traefik
  namespace: traefik
spec:
  type: LoadBalancer
  selector:
    app.kubernetes.io/name: traefik
  ports:
    - name: web
      port: 80
      targetPort: 8000
      protocol: TCP
    - name: websecure
      port: 443
      targetPort: 8443
      protocol: TCP
    - name: multicluster
      port: 9443
      targetPort: 9443
      protocol: TCP

Related Content​