Traefik & Kubernetes with Gateway API

The Kubernetes Gateway provider is a Traefik implementation of the Gateway API specification from the Kubernetes Special Interest Groups (SIGs).

This provider supports version v1.1.0 of the Gateway API specification.

It fully supports all HTTP core and some extended features, as well as the TCPRoute and TLSRoute resources from the Experimental channel.

For more details, check out the conformance report.

Requirements

Traefik follows the Kubernetes support policy, and supports at least the latest three minor versions of Kubernetes. General functionality cannot be guaranteed for older versions.

Helm Chart

When using the Traefik Helm Chart, the CRDs (Custom Resource Definitions) and RBAC (Role-Based Access Control) are automatically managed for you. The only remaining task is to enable the kubernetesGateway in the chart values.

  1. Install/update the Kubernetes Gateway API CRDs.

    1. # Install Gateway API CRDs from the Experimental channel.
    2. kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/experimental-install.yaml

  2. Install/update the Traefik RBAC.

    1. # Install Traefik RBACs.
    2. kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.1/docs/content/reference/dynamic-configuration/kubernetes-gateway-rbac.yml

  3. Deploy Traefik and enable the kubernetesGateway provider in the static configuration as detailed below:

    File (YAML)

    1. providers:
    2.   kubernetesGateway: {}

    File (TOML)

    1. [providers.kubernetesGateway]

    CLI

    1. --providers.kubernetesgateway=true

Routing Configuration

When using the Kubernetes Gateway API provider, Traefik uses the Gateway API CRDs to retrieve its routing configuration. Check out the Gateway API concepts documentation, and the dedicated routing section in the Traefik documentation.

Provider Configuration

endpoint

Optional, Default=””

The Kubernetes server endpoint URL.

When deployed into Kubernetes, Traefik reads the environment variables KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT or KUBECONFIG to construct the endpoint.

The access token is looked up in /var/run/secrets/kubernetes.io/serviceaccount/token and the SSL CA certificate in /var/run/secrets/kubernetes.io/serviceaccount/ca.crt. Both are mounted automatically when deployed inside Kubernetes.

The endpoint may be specified to override the environment variable values inside a cluster.

When the environment variables are not found, Traefik tries to connect to the Kubernetes API server with an external-cluster client. In this case, the endpoint is required. Specifically, it may be set to the URL used by kubectl proxy to connect to a Kubernetes cluster using the granted authentication and authorization of the associated kubeconfig.

File (YAML)

  1. providers:
  2.   kubernetesGateway:
  3.     endpoint: "http://localhost:8080"
  4.     # ...

File (TOML)

  1. [providers.kubernetesGateway]
  2.   endpoint = "http://localhost:8080"
  3.   # ...

CLI

  1. --providers.kubernetesgateway.endpoint=http://localhost:8080

token

Optional, Default=””

Bearer token used for the Kubernetes client configuration.

File (YAML)

  1. providers:
  2.   kubernetesGateway:
  3.     token: "mytoken"
  4.     # ...

File (TOML)

  1. [providers.kubernetesGateway]
  2.   token = "mytoken"
  3.   # ...

CLI

  1. --providers.kubernetesgateway.token=mytoken

certAuthFilePath

Optional, Default=””

Path to the certificate authority file. Used for the Kubernetes client configuration.

File (YAML)

  1. providers:
  2.   kubernetesGateway:
  3.     certAuthFilePath: "/my/ca.crt"
  4.     # ...

File (TOML)

  1. [providers.kubernetesGateway]
  2.   certAuthFilePath = "/my/ca.crt"
  3.   # ...

CLI

  1. --providers.kubernetesgateway.certauthfilepath=/my/ca.crt

namespaces

Optional, Default: []

Array of namespaces to watch. If left empty, Traefik watches all namespaces.

File (YAML)

  1. providers:
  2.   kubernetesGateway:
  3.     namespaces:
  4.     - "default"
  5.     - "production"
  6.     # ...

File (TOML)

  1. [providers.kubernetesGateway]
  2.   namespaces = ["default", "production"]
  3.   # ...

CLI

  1. --providers.kubernetesgateway.namespaces=default,production

statusAddress

ip

Optional, Default: “”

This IP will get copied to the Gateway status.addresses, and currently only supports one IP value (IPv4 or IPv6).

File (YAML)

  1. providers:
  2.   kubernetesGateway:
  3.     statusAddress:
  4.       ip: "1.2.3.4"
  5.     # ...

File (TOML)

  1. [providers.kubernetesGateway.statusAddress]
  2.   ip = "1.2.3.4"
  3.   # ...

CLI

  1. --providers.kubernetesgateway.statusaddress.ip=1.2.3.4

hostname

Optional, Default: “”

This Hostname will get copied to the Gateway status.addresses.

File (YAML)

  1. providers:
  2.   kubernetesGateway:
  3.     statusAddress:
  4.       hostname: "example.net"
  5.     # ...

File (TOML)

  1. [providers.kubernetesGateway.statusAddress]
  2.   hostname = "example.net"
  3.   # ...

CLI

  1. --providers.kubernetesgateway.statusaddress.hostname=example.net

service

Optional

The Kubernetes service to copy status addresses from. When using third parties tools like External-DNS, this option can be used to copy the service loadbalancer.status (containing the service’s endpoints IPs) to the gateways.

File (YAML)

  1. providers:
  2.   kubernetesGateway:
  3.     statusAddress:
  4.       service:
  5.         namespace: default
  6.         name: foo
  7.     # ...

File (TOML)

  1. [providers.kubernetesGateway.statusAddress.service]
  2.   namespace = "default"
  3.   name = "foo"
  4.   # ...

CLI

  1. --providers.kubernetesgateway.statusaddress.service.namespace=default
  2. --providers.kubernetesgateway.statusaddress.service.name=foo

experimentalChannel

Optional, Default: false

Toggles support for the Experimental Channel resources (Gateway API release channels documentation). This option currently enables support for TCPRoute and TLSRoute.

File (YAML)

  1. providers:
  2.   kubernetesGateway:
  3.     experimentalChannel: true

File (TOML)

  1. [providers.kubernetesGateway]
  2.     experimentalChannel = true
  3.   # ...

CLI

  1. --providers.kubernetesgateway.experimentalchannel=true

labelselector

Optional, Default: “”

A label selector can be defined to filter on specific GatewayClass objects only. If left empty, Traefik processes all GatewayClass objects in the configured namespaces.

See label-selectors for details.

File (YAML)

  1. providers:
  2.   kubernetesGateway:
  3.     labelselector: "app=traefik"
  4.     # ...

File (TOML)

  1. [providers.kubernetesGateway]
  2.   labelselector = "app=traefik"
  3.   # ...

CLI

  1. --providers.kubernetesgateway.labelselector="app=traefik"

throttleDuration

Optional, Default: 0

The throttleDuration option defines how often the provider is allowed to handle events from Kubernetes. This prevents a Kubernetes cluster that updates many times per second from continuously changing your Traefik configuration.

If left empty, the provider does not apply any throttling and does not drop any Kubernetes events.

The value of throttleDuration should be provided in seconds or as a valid duration format, see time.ParseDuration.

File (YAML)

  1. providers:
  2.   kubernetesGateway:
  3.     throttleDuration: "10s"
  4.     # ...

File (TOML)

  1. [providers.kubernetesGateway]
  2.   throttleDuration = "10s"
  3.   # ...

CLI

  1. --providers.kubernetesgateway.throttleDuration=10s

Using Traefik OSS in Production? Consider Adding Advanced Capabilities.

Add API Gateway or API Management capabilities seamlessly to your existing Traefik deployments. No rip and replace. No learning curve.