Traefik & Kubernetes¶
The Kubernetes Gateway API, The Experimental Way. {: .subtitle }
Configuration Examples¶
Configuring Kubernetes Gateway provider and Deploying/Exposing Services
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GatewayClass
metadata:
name: my-gateway-class
spec:
controllerName: traefik.io/gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
name: my-gateway
spec:
gatewayClassName: my-gateway-class
listeners:
- name: https
protocol: HTTPS
port: 443
tls:
certificateRefs:
- kind: Secret
name: mysecret
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
name: http-app
namespace: default
spec:
parentRefs:
- name: my-gateway
hostnames:
- whoami
rules:
- matches:
- path:
type: Exact
value: /foo
backendRefs:
- name: whoami
port: 80
weight: 1---
apiVersion: apps/v1
kind: Deployment
metadata:
name: whoami
spec:
replicas: 2
selector:
matchLabels:
app: whoami
template:
metadata:
labels:
app: whoami
spec:
containers:
- name: whoami
image: traefik/whoami
---
apiVersion: v1
kind: Service
metadata:
name: whoami
spec:
selector:
app: whoami
ports:
- protocol: TCP
port: 80---
apiVersion: v1
kind: ServiceAccount
metadata:
name: traefik-controller
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: traefik
spec:
replicas: 1
selector:
matchLabels:
app: traefik-lb
template:
metadata:
labels:
app: traefik-lb
spec:
serviceAccountName: traefik-controller
containers:
- name: traefik
image: traefik:v2.11
args:
- --entryPoints.web.address=:80
- --entryPoints.websecure.address=:443
- --experimental.kubernetesgateway
- --providers.kubernetesgateway
ports:
- name: web
containerPort: 80
- name: websecure
containerPort: 443
---
apiVersion: v1
kind: Service
metadata:
name: traefik
spec:
type: LoadBalancer
selector:
app: traefik-lb
ports:
- protocol: TCP
port: 80
targetPort: web
name: web
- protocol: TCP
port: 443
targetPort: websecure
name: websecure---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: gateway-role
rules:
- apiGroups:
- ""
resources:
- namespaces
verbs:
- list
- watch
- apiGroups:
- ""
resources:
- services
- endpoints
- secrets
verbs:
- get
- list
- watch
- apiGroups:
- gateway.networking.k8s.io
resources:
- gatewayclasses
- gateways
- httproutes
- tcproutes
- tlsroutes
verbs:
- get
- list
- watch
- apiGroups:
- gateway.networking.k8s.io
resources:
- gatewayclasses/status
- gateways/status
- httproutes/status
- tcproutes/status
- tlsroutes/status
verbs:
- update
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: gateway-controller
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: gateway-role
subjects:
- kind: ServiceAccount
name: traefik-controller
namespace: defaultRouting Configuration¶
Custom Resource Definition (CRD)¶
- You can find an exhaustive list, of the custom resources and their attributes in
the reference page or in the Kubernetes
Sigs
Gateway APIrepository. - Validate that the prerequisites are fulfilled before using the Traefik Kubernetes Gateway Provider.
You can find an excerpt of the supported Kubernetes Gateway API resources in the table below:
| Kind | Purpose | Concept Behind |
|---|---|---|
| GatewayClass | Defines a set of Gateways that share a common configuration and behaviour | GatewayClass |
| Gateway | Describes how traffic can be translated to Services within the cluster | Gateway |
| HTTPRoute | HTTP rules for mapping requests from a Gateway to Kubernetes Services | Route |
| TCPRoute | Allows mapping TCP requests from a Gateway to Kubernetes Services | Route |
| TLSRoute | Allows mapping TLS requests from a Gateway to Kubernetes Services | Route |
Kind: GatewayClass¶
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
GatewayClass official documentation.
The GatewayClass should be declared by the infrastructure provider, otherwise please register the GatewayClass
definition in the Kubernetes cluster before
creating GatewayClass objects.
Declaring GatewayClass
apiVersion: gateway.networking.k8s.io/v1alpha2
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.
controllerName: traefik.io/gateway-controllerKind: Gateway¶
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.
Register the Gateway definition in the
Kubernetes cluster before creating Gateway objects.
Depending on the Listener Protocol, different modes and Route types are supported.
| Listener Protocol | TLS Mode | Route Type Supported |
|---|---|---|
| TCP | Not applicable | TCPRoute |
| TLS | Passthrough | TLSRoute, TCPRoute |
| TLS | Terminate | TLSRoute, TCPRoute |
| HTTP | Not applicable | HTTPRoute |
| HTTPS | Terminate | HTTPRoute |
Declaring Gateway
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
name: my-http-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
- name: http # [3]
protocol: HTTP # [4]
port: 80 # [5]
allowedRoutes: # [9]
kinds:
- kind: HTTPRoute # [10]
namespaces:
from: Selector # [11]
selector: # [12]
matchLabels:
app: fooapiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
name: my-https-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
- name: https # [3]
protocol: HTTPS # [4]
port: 443 # [5]
tls: # [7]
certificateRefs: # [8]
- kind: "Secret"
name: "mysecret"
allowedRoutes: # [9]
kinds:
- kind: HTTPSRoute # [10]
namespaces:
from: Selector # [11]
selector: # [12]
matchLabels:
app: fooapiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
name: my-tcp-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
- name: tcp # [3]
protocol: TCP # [4]
port: 8000 # [5]
allowedRoutes: # [9]
kinds:
- kind: TCPRoute # [10]
namespaces:
from: Selector # [11]
selector: # [12]
matchLabels:
app: footcpapiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
name: my-tls-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class # [1]
listeners: # [2]
- name: tls # [3]
protocol: TLS # [4]
port: 443 # [5]
hostname: foo.com # [6]
tls: # [7]
certificateRefs: # [8]
- kind: "Secret"
name: "mysecret"
allowedRoutes: # [9]
kinds:
- kind: TLSRoute # [10]
namespaces:
from: Selector # [11]
selector: # [12]
matchLabels:
app: footcp| 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. |
| [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. |
Kind: HTTPRoute¶
HTTPRoute defines HTTP rules for mapping requests from a Gateway to Kubernetes Services.
Register the HTTPRoute definition in the
Kubernetes cluster before creating HTTPRoute objects.
Declaring HTTPRoute
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
name: http-app
namespace: default
spec:
parentRefs: # [1]
- name: my-tcp-gateway # [2]
namespace: default # [3]
sectionName: tcp # [4]
hostnames: # [5]
- whoami
rules: # [6]
- matches: # [7]
- path: # [8]
type: Exact # [9]
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
group: traefik.io # [18]
kind: TraefikService # [19]| 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, PathPrefix). |
| [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. |
| [18] | group |
Group is the group of the referent. Only traefik.io, traefik.containo.us and gateway.networking.k8s.io values are supported. |
| [19] | kind |
Kind is kind of the referent. Only TraefikService and Service values are supported. |
Kind: TCPRoute¶
TCPRoute allows mapping TCP requests from a Gateway to Kubernetes Services.
Register the TCPRoute definition in the
Kubernetes cluster before creating TCPRoute objects.
Declaring TCPRoute
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
name: tcp-app
namespace: default
spec:
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
group: traefik.containo.us # [10]
kind: TraefikService # [11]| 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, traefik.containo.us and gateway.networking.k8s.io values are supported. |
| [11] | kind |
Kind is kind of the referent. Only TraefikService and Service values are supported. |
Kind: TLSRoute¶
TLSRoute allows mapping TLS requests from a Gateway to Kubernetes Services.
Register the TLSRoute definition in the
Kubernetes cluster before creating TLSRoute objects.
Declaring TLSRoute
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
name: tls-app
namespace: default
spec:
parentRefs: # [1]
- name: my-tls-gateway # [2]
namespace: default # [3]
sectionName: tcp # [4]
hostnames: # [5]
- whoami
rules: # [6]
- backendRefs: # [7]
- name: whoamitcp # [8]
weight: 1 # [9]
port: 8080 # [10]
- name: api@internal
group: traefik.containo.us # [11]
kind: TraefikService # [12]| 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, traefik.containo.us and gateway.networking.k8s.io values are supported. |
| [12] | kind |
Kind is kind of the referent. Only TraefikService and Service values are supported. |
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.