Kubernetes Gateway API
The Kubernetes Gateway provider is a Traefik Hub API Gateway 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.
When Traefik Hub API Gateway is installed using the Helm Chart, by default, the provider kubernetesGateway is not enabled.
If you need to use Traefik Custom resources (like Middlewares),
you need to enable the provider kubernetesCRD,
and install the required CRDs and RBACs too.
Requirements
When you install Traefik Hub API Gateway without using the Helm Chart, or when you are upgrading the stack using Helm, ensure that you satisfy the following requirements:
- Add/update all the Kubernetes Gateway API CRDs
- Add/update the RBAC for the Traefik Hub API Gateway resources
# Install Gateway API CRDs from the Experimental channel.
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.1.0/experimental-install.yaml
# Install Traefik Hub API Gateway RBACs.
kubectl apply -f kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.1/docs/content/reference/dynamic-configuration/kubernetes-gateway-rbac.yml
Configuration Example
- Static Configuration
- Helm Chart Values
## YAML file
providers:
kubernetesGateway:
experimentalChannel: true
throttleDuration: 2s
## Values file
providers:
kubernetesGateway:
enabled: true
experimentalChannel: true
throttleDuration: 2s
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.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.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.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.