traefik/docs/content/providers/kubernetes-gateway.md

Traefik & Kubernetes with Gateway API

The Kubernetes Gateway API, The Experimental Way. {: .subtitle }

Gateway API is the evolution of Kubernetes APIs that relate to Services, such as Ingress. The Gateway API project is part of Kubernetes, working under SIG-NETWORK.

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

This provider is proposed as an experimental feature and partially supports the Gateway API v0.3.0 specification.

!!! warning "Enabling The Experimental Kubernetes Gateway Provider"

Since this provider is still experimental, it needs to be activated in the experimental section of the static configuration.

```yaml tab="File (YAML)"
experimental:
  kubernetesGateway: true

providers:
  kubernetesGateway: {}
  #...
```

```toml tab="File (TOML)"
[experimental]
  kubernetesGateway = true

[providers.kubernetesGateway]
#...
```

```bash tab="CLI"
--experimental.kubernetesgateway=true --providers.kubernetesgateway=true #...
```

Configuration Requirements

!!! tip "All Steps for a Successful Deployment"

* Add/update the Kubernetes Gateway API [definitions](../reference/dynamic-configuration/kubernetes-gateway.md#definitions).
* Add/update the [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) for the Traefik custom resources.
* Add all needed Kubernetes Gateway API [resources](../reference/dynamic-configuration/kubernetes-gateway.md#resources).

Examples

??? example "Kubernetes Gateway Provider Basic Example"

```yaml tab="Gateway API"
--8<-- "content/reference/dynamic-configuration/kubernetes-gateway-simple-https.yml"
```

```yaml tab="Whoami Service"
--8<-- "content/reference/dynamic-configuration/kubernetes-whoami-svc.yml"
```

```yaml tab="Traefik Service"
--8<-- "content/reference/dynamic-configuration/kubernetes-gateway-traefik-lb-svc.yml"
```

```yaml tab="Gateway API CRDs"
# All resources definition must be declared
--8<-- "content/reference/dynamic-configuration/networking.x-k8s.io_gatewayclasses.yaml"
--8<-- "content/reference/dynamic-configuration/networking.x-k8s.io_gateways.yaml"
--8<-- "content/reference/dynamic-configuration/networking.x-k8s.io_httproutes.yaml"
```

```yaml tab="RBAC"
--8<-- "content/reference/dynamic-configuration/kubernetes-gateway-rbac.yml"
```

The Kubernetes Gateway API project provides several guides on how to use the APIs. These guides can help you to go further than the example above. The getting started guide details how to install the CRDs from their repository.

!!! note ""

Keep in mind that the Traefik Gateway provider only supports the `v0.3.0` (v1alpha1).

For now, the Traefik Gateway Provider can be used while following the below guides:

• Simple Gateway
• HTTP routing
• TLS

Resource Configuration

When using Kubernetes Gateway API as a provider, Traefik uses Kubernetes Custom Resource Definitions to retrieve its routing configuration.

All concepts can be found in the official API concepts documentation. Traefik implements the following resources:

• GatewayClass defines a set of Gateways that share a common configuration and behaviour.
• Gateway describes how traffic can be translated to Services within the cluster.
• HTTPRoute defines HTTP rules for mapping requests from a Gateway to Kubernetes Services.
• TCPRoute defines TCP rules for mapping requests from a Gateway to Kubernetes Services.
• TLSRoute defines TLS rules for mapping requests from a Gateway to Kubernetes Services.

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.

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

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

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

token

Optional, Default=""

Bearer token used for the Kubernetes client configuration.

providers:
  kubernetesGateway:
    token: "mytoken"
    # ...

[providers.kubernetesGateway]
  token = "mytoken"
  # ...

--providers.kubernetesgateway.token=mytoken

certAuthFilePath

Optional, Default=""

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

providers:
  kubernetesGateway:
    certAuthFilePath: "/my/ca.crt"
    # ...

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

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

namespaces

Optional, Default: []

Array of namespaces to watch. If left empty, watches all namespaces if the value of namespaces.

providers:
  kubernetesGateway:
    namespaces:
    - "default"
    - "production"
    # ...

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

--providers.kubernetesgateway.namespaces=default,production

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.

providers:
  kubernetesGateway:
    labelselector: "app=traefik"
    # ...

[providers.kubernetesGateway]
  labelselector = "app=traefik"
  # ...

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

providers:
  kubernetesGateway:
    throttleDuration: "10s"
    # ...

[providers.kubernetesGateway]
  throttleDuration = "10s"
  # ...

--providers.kubernetesgateway.throttleDuration=10s