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 Standard version v1.2.1 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.

Using The 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.

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.

Install/update the Kubernetes Gateway API CRDs.

# Install Gateway API CRDs from the Standard channel.
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml

Install/update the Traefik RBAC.

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

Configuration Example¶

You can enable the kubernetesGateway provider as detailed below:

File (YAML)

providers:
  kubernetesGateway: {}
  # ...

File (TOML)

[providers.kubernetesGateway]
# ...

CLI

--providers.kubernetesgateway=true

Helm Chart Values

## Values file
providers:
  kubernetesGateway:
    enabled: true

Configuration Options¶

Field	Description	Default	Required
`providers.providersThrottleDuration`	Minimum amount of time to wait for, after a configuration reload, before taking into account any new configuration refresh event. If multiple events occur within this time, only the most recent one is taken into account, and all others are discarded. This option cannot be set per provider, but the throttling algorithm applies to each of them independently.	2s	No
`providers.kubernetesGateway.endpoint`	Server endpoint URL. More information here.	""	No
`providers.kubernetesGateway.experimentalChannel`	Toggles support for the Experimental Channel resources (Gateway API release channels documentation). (ex: `TCPRoute` and `TLSRoute`)	false	No
`providers.kubernetesGateway.token`	Bearer token used for the Kubernetes client configuration.	""	No
`providers.kubernetesGateway.certAuthFilePath`	Path to the certificate authority file. Used for the Kubernetes client configuration.	""	No
`providers.kubernetesGateway.namespaces`	Array of namespaces to watch. If left empty, watch all namespaces.	{}	No
`providers.kubernetesGateway.labelselector`	Allow filtering on specific resource objects only using label selectors. Only to Traefik Custom Resources (they all must match the filter). No effect on Kubernetes `Secrets`, `EndpointSlices` and `Services`. See label-selectors for details.	""	No
`providers.kubernetesGateway.throttleDuration`	Minimum amount of time to wait between two Kubernetes events before producing a new configuration. This prevents a Kubernetes cluster that updates many times per second from continuously changing your Traefik configuration. If empty, every event is caught.	0s	No
`providers.kubernetesGateway.nativeLBByDefault`	Defines whether to use Native Kubernetes load-balancing mode by default. For more information, please check out the `traefik.io/service.nativelb` service annotation documentation.	false	No
`providers.kubernetesGateway.` `statusAddress.hostname`	Hostname copied to the Gateway `status.addresses`.	""	No
`providers.kubernetesGateway.` `statusAddress.ip`	IP address copied to the Gateway `status.addresses`, and currently only supports one IP value (IPv4 or IPv6).	""	No
`providers.kubernetesGateway.` `statusAddress.publishedService`	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.	""	No

`endpoint`¶

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)

providers:
  kubernetesGateway:
    endpoint: "http://localhost:8080"
    # ...

File (TOML)

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

CLI

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

Routing Configuration¶

See the dedicated section in routing.

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.

Using Traefik OSS in Production?

If you are using Traefik at work, consider adding enterprise-grade API gateway capabilities or commercial support for Traefik OSS.

Adding API Gateway capabilities to Traefik OSS is fast and seamless. There's no rip and replace and all configurations remain intact. See it in action via this short video.