2022-04-15 13:44:08 +00:00
---
title: "Traefik Kubernetes Gateway"
description: "The Kubernetes Gateway API can be used as a provider for routing and load balancing in Traefik Proxy. View examples in the technical documentation."
---
2020-12-15 15:40:05 +00:00
# Traefik & Kubernetes
2021-11-09 10:34:06 +00:00
The Kubernetes Gateway API, The Experimental Way. {: .subtitle }
2020-12-15 15:40:05 +00:00
## Configuration Examples
??? example "Configuring Kubernetes Gateway provider and Deploying/Exposing Services"
```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 "
```
2022-06-01 08:42:08 +00:00
2020-12-15 15:40:05 +00:00
```yaml tab="Traefik Service"
--8< -- " content / reference / dynamic-configuration / kubernetes-gateway-traefik-lb-svc . yml "
```
```yaml tab="RBAC"
--8< -- " content / reference / dynamic-configuration / kubernetes-gateway-rbac . yml "
```
## Routing Configuration
### Custom Resource Definition (CRD)
* You can find an exhaustive list, of the custom resources and their attributes in
2021-11-09 10:34:06 +00:00
[the reference page ](../../reference/dynamic-configuration/kubernetes-gateway.md ) or in the Kubernetes
Sigs `Gateway API` [repository ](https://github.com/kubernetes-sigs/gateway-api ).
* Validate that [the prerequisites ](../../providers/kubernetes-gateway.md#configuration-requirements ) are fulfilled
before using the Traefik Kubernetes Gateway Provider.
2020-12-15 15:40:05 +00:00
You can find an excerpt of the supported Kubernetes Gateway API resources in the table below:
2023-03-20 14:38:08 +00:00
| Kind | Purpose | Concept Behind |
|------------------------------------|---------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [GatewayClass ](#kind-gatewayclass ) | Defines a set of Gateways that share a common configuration and behaviour | [GatewayClass ](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/gatewayclass ) |
| [Gateway ](#kind-gateway ) | Describes how traffic can be translated to Services within the cluster | [Gateway ](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/gateway ) |
| [HTTPRoute ](#kind-httproute ) | HTTP rules for mapping requests from a Gateway to Kubernetes Services | [Route ](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/httproute ) |
| [TCPRoute ](#kind-tcproute ) | Allows mapping TCP requests from a Gateway to Kubernetes Services | [Route ](https://gateway-api.sigs.k8s.io/v1alpha2/guides/tcp/ ) |
| [TLSRoute ](#kind-tlsroute ) | Allows mapping TLS requests from a Gateway to Kubernetes Services | [Route ](https://gateway-api.sigs.k8s.io/v1alpha2/guides/tls/ ) |
2020-12-15 15:40:05 +00:00
### Kind: `GatewayClass`
2021-11-09 10:34:06 +00:00
`GatewayClass` is cluster-scoped resource defined by the infrastructure provider. This resource represents a class of
Gateways that can be instantiated. More details on the
2022-06-10 13:12:08 +00:00
GatewayClass [official documentation ](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/gatewayclass/ ).
2020-12-15 15:40:05 +00:00
The `GatewayClass` should be declared by the infrastructure provider, otherwise please register the `GatewayClass`
2021-11-09 10:34:06 +00:00
[definition ](../../reference/dynamic-configuration/kubernetes-gateway.md#definitions ) in the Kubernetes cluster before
2020-12-15 15:40:05 +00:00
creating `GatewayClass` objects.
!!! info "Declaring GatewayClass"
```yaml
2021-11-09 10:34:06 +00:00
apiVersion: gateway.networking.k8s.io/v1alpha2
2020-12-15 15:40:05 +00:00
kind: GatewayClass
metadata:
name: my-gateway-class
spec:
# Controller is a domain/path string that indicates
# the controller that is managing Gateways of this class.
2021-11-09 10:34:06 +00:00
controllerName: traefik.io/gateway-controller
2020-12-15 15:40:05 +00:00
```
### Kind: `Gateway`
2021-11-09 10:34:06 +00:00
A `Gateway` is 1:1 with the life cycle of the configuration of infrastructure. When a user creates a Gateway, some load
balancing infrastructure is provisioned or configured by the GatewayClass controller. More details on the
Gateway [official documentation ](https://gateway-api.sigs.k8s.io/v1alpha2/api-types/gateway/ ).
2020-12-15 15:40:05 +00:00
Register the `Gateway` [definition ](../../reference/dynamic-configuration/kubernetes-gateway.md#definitions ) in the
Kubernetes cluster before creating `Gateway` objects.
2021-05-20 09:50:12 +00:00
Depending on the Listener Protocol, different modes and Route types are supported.
2021-11-09 10:34:06 +00:00
| Listener Protocol | TLS Mode | Route Type Supported |
|-------------------|----------------|--------------------------------------------------------|
| TCP | Not applicable | [TCPRoute ](#kind-tcproute ) |
| TLS | Passthrough | [TLSRoute ](#kind-tlsroute ), [TCPRoute ](#kind-tcproute ) |
| TLS | Terminate | [TLSRoute ](#kind-tlsroute ), [TCPRoute ](#kind-tcproute ) |
| HTTP | Not applicable | [HTTPRoute ](#kind-httproute ) |
| HTTPS | Terminate | [HTTPRoute ](#kind-httproute ) |
2021-05-20 09:50:12 +00:00
2020-12-15 15:40:05 +00:00
!!! info "Declaring Gateway"
2021-05-20 09:50:12 +00:00
```yaml tab="HTTP Listener"
2021-11-09 10:34:06 +00:00
apiVersion: gateway.networking.k8s.io/v1alpha2
2021-05-20 09:50:12 +00:00
kind: Gateway
metadata:
name: my-http-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
2021-11-09 10:34:06 +00:00
- name: http # [3]
2022-06-01 08:42:08 +00:00
protocol: HTTP # [4]
2021-11-09 10:34:06 +00:00
port: 80 # [5]
allowedRoutes: # [9]
kinds:
- kind: HTTPRoute # [10]
2021-10-04 13:46:08 +00:00
namespaces:
2021-11-09 10:34:06 +00:00
from: Selector # [11]
selector: # [12]
2022-06-01 08:42:08 +00:00
matchLabels:
2021-10-04 13:46:08 +00:00
app: foo
2020-12-15 15:40:05 +00:00
```
2021-05-20 09:50:12 +00:00
```yaml tab="HTTPS Listener"
2021-11-09 10:34:06 +00:00
apiVersion: gateway.networking.k8s.io/v1alpha2
2020-12-15 15:40:05 +00:00
kind: Gateway
metadata:
2021-05-20 09:50:12 +00:00
name: my-https-gateway
2020-12-15 15:40:05 +00:00
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
2021-11-09 10:34:06 +00:00
- name: https # [3]
2022-06-01 08:42:08 +00:00
protocol: HTTPS # [4]
2021-11-09 10:34:06 +00:00
port: 443 # [5]
tls: # [7]
certificateRefs: # [8]
- kind: "Secret"
name: "mysecret"
allowedRoutes: # [9]
kinds:
- kind: HTTPSRoute # [10]
2021-10-04 13:46:08 +00:00
namespaces:
2021-11-09 10:34:06 +00:00
from: Selector # [11]
selector: # [12]
2022-06-01 08:42:08 +00:00
matchLabels:
2021-10-04 13:46:08 +00:00
app: foo
2020-12-15 15:40:05 +00:00
```
2021-05-20 09:50:12 +00:00
```yaml tab="TCP Listener"
2021-11-09 10:34:06 +00:00
apiVersion: gateway.networking.k8s.io/v1alpha2
2021-05-20 09:50:12 +00:00
kind: Gateway
metadata:
name: my-tcp-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
2021-11-09 10:34:06 +00:00
- name: tcp # [3]
2022-06-01 08:42:08 +00:00
protocol: TCP # [4]
2021-11-09 10:34:06 +00:00
port: 8000 # [5]
allowedRoutes: # [9]
kinds:
2022-06-01 08:42:08 +00:00
- kind: TCPRoute # [10]
2021-10-04 13:46:08 +00:00
namespaces:
2021-11-09 10:34:06 +00:00
from: Selector # [11]
selector: # [12]
2022-06-01 08:42:08 +00:00
matchLabels:
2021-10-04 13:46:08 +00:00
app: footcp
2021-05-20 09:50:12 +00:00
```
```yaml tab="TLS Listener"
2021-11-09 10:34:06 +00:00
apiVersion: gateway.networking.k8s.io/v1alpha2
2021-05-20 09:50:12 +00:00
kind: Gateway
metadata:
name: my-tls-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
2021-11-09 10:34:06 +00:00
- name: tls # [3]
2022-06-01 08:42:08 +00:00
protocol: TLS # [4]
2021-11-09 10:34:06 +00:00
port: 443 # [5]
hostname: foo.com # [6]
tls: # [7]
certificateRefs: # [8]
- kind: "Secret"
name: "mysecret"
allowedRoutes: # [9]
kinds:
- kind: TLSRoute # [10]
2021-10-04 13:46:08 +00:00
namespaces:
2021-11-09 10:34:06 +00:00
from: Selector # [11]
selector: # [12]
2022-06-01 08:42:08 +00:00
matchLabels:
2021-10-04 13:46:08 +00:00
app: footcp
2021-05-20 09:50:12 +00:00
```
2021-10-04 13:46:08 +00:00
| Ref | Attribute | Description |
|------|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [1] | `gatewayClassName` | GatewayClassName used for this Gateway. This is the name of a GatewayClass resource. |
| [2] | `listeners` | Logical endpoints that are bound on this Gateway's addresses. At least one Listener MUST be specified. |
2021-11-09 10:34:06 +00:00
| [3] | `name` | Name of the Listener. |
| [4] | `protocol` | The network protocol this listener expects to receive (only HTTP and HTTPS are implemented). |
| [5] | `port` | The network port. |
| [6] | `hostname` | Hostname specifies the virtual hostname to match for protocol types that define this concept. When unspecified, “”, or *, all hostnames are matched. |
| [7] | `tls` | TLS configuration for the Listener. This field is required if the Protocol field is "HTTPS" or "TLS" and ignored otherwise. |
| [8] | `certificateRefs` | The references to Kubernetes objects that contains TLS certificates and private keys (only one reference to a Kubernetes Secret is supported). |
| [9] | `allowedRoutes` | Defines the types of routes that MAY be attached to a Listener and the trusted namespaces where those Route resources MAY be present. |
| [10] | `kind` | The kind of the Route. |
| [11] | `from` | From indicates in which namespaces the Routes will be selected for this Gateway. Possible values are `All` , `Same` and `Selector` (Defaults to `Same` ). |
| [12] | `selector` | Selector must be specified when From is set to `Selector` . In that case, only Routes in Namespaces matching this Selector will be selected by this Gateway. |
2020-12-15 15:40:05 +00:00
### Kind: `HTTPRoute`
2021-11-09 10:34:06 +00:00
`HTTPRoute` defines HTTP rules for mapping requests from a `Gateway` to Kubernetes Services.
2020-12-15 15:40:05 +00:00
Register the `HTTPRoute` [definition ](../../reference/dynamic-configuration/kubernetes-gateway.md#definitions ) in the
Kubernetes cluster before creating `HTTPRoute` objects.
!!! info "Declaring HTTPRoute"
```yaml
2021-11-09 10:34:06 +00:00
apiVersion: gateway.networking.k8s.io/v1alpha2
2020-12-15 15:40:05 +00:00
kind: HTTPRoute
metadata:
2021-11-09 10:34:06 +00:00
name: http-app
2020-12-15 15:40:05 +00:00
namespace: default
spec:
2021-11-09 10:34:06 +00:00
parentRefs: # [1]
- name: my-tcp-gateway # [2]
namespace: default # [3]
2022-06-01 08:42:08 +00:00
sectionName: tcp # [4]
2021-11-09 10:34:06 +00:00
hostnames: # [5]
- whoami
rules: # [6]
- matches: # [7]
- path: # [8]
2021-02-02 18:36:04 +00:00
type: Exact # [9]
2021-11-09 10:34:06 +00:00
value: /bar # [10]
- headers: # [11]
name: foo # [12]
value: bar # [13]
- backendRefs: # [14]
- name: whoamitcp # [15]
weight: 1 # [16]
port: 8080 # [17]
- name: api@internal
2023-03-20 14:38:08 +00:00
group: traefik.io # [18]
2021-11-09 10:34:06 +00:00
kind: TraefikService # [19]
2020-12-15 15:40:05 +00:00
```
2021-11-09 10:34:06 +00:00
| Ref | Attribute | Description |
|------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [1] | `parentRefs` | References the resources (usually Gateways) that a Route wants to be attached to. |
| [2] | `name` | Name of the referent. |
| [3] | `namespace` | Namespace of the referent. When unspecified (or empty string), this refers to the local namespace of the Route. |
| [4] | `sectionName` | Name of a section within the target resource (the Listener name). |
| [5] | `hostnames` | A set of hostname that should match against the HTTP Host header to select a HTTPRoute to process the request. |
| [6] | `rules` | A list of HTTP matchers, filters and actions. |
| [7] | `matches` | Conditions used for matching the rule against incoming HTTP requests. Each match is independent, i.e. this rule will be matched if **any** one of the matches is satisfied. |
| [8] | `path` | An HTTP request path matcher. If this field is not specified, a default prefix match on the "/" path is provided. |
| [9] | `type` | Type of match against the path Value (supported types: `Exact` , `Prefix` ). |
| [10] | `value` | The value of the HTTP path to match against. |
| [11] | `headers` | Conditions to select a HTTP route by matching HTTP request headers. |
| [12] | `type` | Type of match for the HTTP request header match against the `values` (supported types: `Exact` ). |
| [13] | `value` | A map of HTTP Headers to be matched. It MUST contain at least one entry. |
| [14] | `backendRefs` | Defines the backend(s) where matching requests should be sent. |
| [15] | `name` | The name of the referent service. |
| [16] | `weight` | The proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs). |
| [17] | `port` | The port of the referent service. |
2023-03-22 15:40:06 +00:00
| [18] | `group` | Group is the group of the referent. Only `traefik.io` and `gateway.networking.k8s.io` values are supported. |
2021-11-09 10:34:06 +00:00
| [19] | `kind` | Kind is kind of the referent. Only `TraefikService` and `Service` values are supported. |
2021-05-20 09:50:12 +00:00
### Kind: `TCPRoute`
2021-11-09 10:34:06 +00:00
`TCPRoute` allows mapping TCP requests from a `Gateway` to Kubernetes Services.
2021-05-20 09:50:12 +00:00
Register the `TCPRoute` [definition ](../../reference/dynamic-configuration/kubernetes-gateway.md#definitions ) in the
Kubernetes cluster before creating `TCPRoute` objects.
!!! info "Declaring TCPRoute"
```yaml
2021-11-09 10:34:06 +00:00
apiVersion: gateway.networking.k8s.io/v1alpha2
2021-05-20 09:50:12 +00:00
kind: TCPRoute
metadata:
2021-11-09 10:34:06 +00:00
name: tcp-app
2021-05-20 09:50:12 +00:00
namespace: default
spec:
2021-11-09 10:34:06 +00:00
parentRefs: # [1]
- name: my-tcp-gateway # [2]
namespace: default # [3]
sectionName: tcp # [4]
rules: # [5]
- backendRefs: # [6]
- name: whoamitcp # [7]
weight: 1 # [8]
port: 8080 # [9]
- name: api@internal
2023-03-21 11:00:46 +00:00
group: traefik.io # [10]
2021-11-09 10:34:06 +00:00
kind: TraefikService # [11]
2021-05-20 09:50:12 +00:00
```
2023-03-22 15:40:06 +00:00
| Ref | Attribute | Description |
|------|---------------|-----------------------------------------------------------------------------------------------------------------|
| [1] | `parentRefs` | References the resources (usually Gateways) that a Route wants to be attached to. |
| [2] | `name` | Name of the referent. |
| [3] | `namespace` | Namespace of the referent. When unspecified (or empty string), this refers to the local namespace of the Route. |
| [4] | `sectionName` | Name of a section within the target resource (the Listener name). |
| [5] | `rules` | Rules are a list of TCP matchers and actions. |
| [6] | `backendRefs` | Defines the backend(s) where matching requests should be sent. |
| [7] | `name` | The name of the referent service. |
| [8] | `weight` | The proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs). |
| [9] | `port` | The port of the referent service. |
| [10] | `group` | Group is the group of the referent. Only `traefik.io` and `gateway.networking.k8s.io` values are supported. |
| [11] | `kind` | Kind is kind of the referent. Only `TraefikService` and `Service` values are supported. |
2021-05-20 09:50:12 +00:00
### Kind: `TLSRoute`
2021-11-09 10:34:06 +00:00
`TLSRoute` allows mapping TLS requests from a `Gateway` to Kubernetes Services.
2021-05-20 09:50:12 +00:00
Register the `TLSRoute` [definition ](../../reference/dynamic-configuration/kubernetes-gateway.md#definitions ) in the
Kubernetes cluster before creating `TLSRoute` objects.
2021-11-09 10:34:06 +00:00
!!! info "Declaring TLSRoute"
2021-05-20 09:50:12 +00:00
```yaml
2021-11-09 10:34:06 +00:00
apiVersion: gateway.networking.k8s.io/v1alpha2
2021-05-20 09:50:12 +00:00
kind: TLSRoute
metadata:
2021-11-09 10:34:06 +00:00
name: tls-app
2021-05-20 09:50:12 +00:00
namespace: default
spec:
2021-11-09 10:34:06 +00:00
parentRefs: # [1]
- name: my-tls-gateway # [2]
namespace: default # [3]
sectionName: tcp # [4]
hostnames: # [5]
2022-06-01 08:42:08 +00:00
- whoami
2021-11-09 10:34:06 +00:00
rules: # [6]
- backendRefs: # [7]
- name: whoamitcp # [8]
weight: 1 # [9]
port: 8080 # [10]
- name: api@internal
2023-03-21 11:00:46 +00:00
group: traefik.io # [11]
2021-11-09 10:34:06 +00:00
kind: TraefikService # [12]
2021-05-20 09:50:12 +00:00
```
2023-03-22 15:40:06 +00:00
| Ref | Attribute | Description |
|------|---------------|---------------------------------------------------------------------------------------------------------------------|
| [1] | `parentRefs` | References the resources (usually Gateways) that a Route wants to be attached to. |
| [2] | `name` | Name of the referent. |
| [3] | `namespace` | Namespace of the referent. When unspecified (or empty string), this refers to the local namespace of the Route. |
| [4] | `sectionName` | Name of a section within the target resource (the Listener name). |
| [5] | `hostnames` | Defines a set of SNI names that should match against the SNI attribute of TLS ClientHello message in TLS handshake. |
| [6] | `rules` | Rules are a list of TCP matchers and actions. |
| [7] | `backendRefs` | Defines the backend(s) where matching requests should be sent. |
| [8] | `name` | The name of the referent service. |
| [9] | `weight` | The proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs). |
| [10] | `port` | The port of the referent service. |
| [11] | `group` | Group is the group of the referent. Only `traefik.io` and `gateway.networking.k8s.io` values are supported. |
| [12] | `kind` | Kind is kind of the referent. Only `TraefikService` and `Service` values are supported. |
