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, e.g. Ingress. The Gateway API project is part of Kubernetes, working under SIG-NETWORK.

The Kubernetes Gateway provider is a Traefik implementation of the service apis specifications from the Kubernetes SIGs.

This provider is proposed as an experimental feature and partially supports the service apis v0.1.0 specification.

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

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

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

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

```yaml tab="File (YAML)"
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 Service APIs provides several guides of how to use their API. Those guides will help you to go further than the example above. The getting started show you how to install the CRDs from their repository. Thus, keep in mind that the Traefik Gateway provider only supports the v0.1.0.

For now, the Traefik Gateway Provider could be used to achieve the following set-up guides:

• Simple Gateway
• HTTP routing
• TLS (Partial support: only on listeners with terminate mode)

Resource Configuration

When using Kubernetes Gateway API as a provider, Traefik uses Kubernetes Custom Resource Definition 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 define HTTP rules for mapping requests from a Gateway to Kubernetes Services.

Provider Configuration

endpoint

Optional, Default=empty

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

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

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

The Kubernetes server endpoint as URL.

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

The access token will be 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 will try 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.

token

Optional, Default=empty

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

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

--providers.kubernetesgateway.token=mytoken

Bearer token used for the Kubernetes client configuration.

certAuthFilePath

Optional, Default=empty

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

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

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

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

namespaces

Optional, Default: all namespaces (empty array)

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

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

--providers.kubernetesgateway.namespaces=default,production

Array of namespaces to watch.

labelselector

Optional, Default: empty (process all resources)

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

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

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

By default, Traefik processes all resource objects in the configured namespaces. A label selector can be defined to filter on specific GatewayClass objects only.

See label-selectors for details.

throttleDuration

Optional, Default: 0 (no throttling)

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

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

--providers.kubernetesgateway.throttleDuration=10s