Traefik & Kubernetes
- Configuration Examples
- Routing Configuration

Traefik & Kubernetes

The Kubernetes Gateway API, The Experimental Way.

Configuration Examples

Configuring Kubernetes Gateway provider and Deploying/Exposing Services

Gateway API

---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: my-gateway-class
spec:
  controllerName: traefik.io/gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
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/v1
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

Whoami Service

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

Traefik Service

---
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:v3.0
          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

RBAC

---
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
      - referencegrants
      - 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: default

Routing 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 API repository.
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/v1
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-controller

Kind: `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.

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

HTTP Listener

apiVersion: gateway.networking.k8s.io/v1
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: foo

HTTPS Listener

apiVersion: gateway.networking.k8s.io/v1
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: foo

TCP Listener

apiVersion: gateway.networking.k8s.io/v1
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: footcp

TLS Listener

apiVersion: gateway.networking.k8s.io/v1
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.

Declaring HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
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]
    - filters:                              # [20]
      - type: ExtensionRef                  # [21]
        extensionRef:                       # [22]
          group: traefik.io                 # [23]
          kind: Middleware                  # [24]
          name: my-middleware               # [25]
      - type: RequestRedirect               # [26]
        requestRedirect:                    # [27]
          scheme: https                     # [28]
          statusCode: 301                   # [29]
      - type: RequestHeaderModifier         # [30]
        requestHeaderModifier:              # [31]
          set:
            - name: X-Foo
              value: Bar
          add:
            - name: X-Bar
              value: Foo
          remove:
            - X-Baz

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]	`name`	Name of the HTTP header to be matched.
[13]	`value`	Value of HTTP Header to be matched.
[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` and `gateway.networking.k8s.io` values are supported.
[19]	`kind`	Kind is kind of the referent. Only `TraefikService` and `Service` values are supported.
[20]	`filters`	Defines the filters (middlewares) applied to the route.
[21]	`type`	Defines the type of filter; ExtensionRef is used for configuring custom HTTP filters.
[22]	`extensionRef`	Configuration of the custom HTTP filter.
[23]	`group`	Group of the kubernetes object to reference.
[24]	`kind`	Kind of the kubernetes object to reference.
[25]	`name`	Name of the kubernetes object to reference.
[26]	`type`	Defines the type of filter; RequestRedirect redirects a request to another location.
[27]	`requestRedirect`	Configuration of redirect filter.
[28]	`scheme`	Scheme is the scheme to be used in the value of the Location header in the response.
[29]	`statusCode`	StatusCode is the HTTP status code to be used in response.
[30]	`type`	Defines the type of filter; RequestHeaderModifier modifies request headers.
[31]	`requestHeaderModifier`	Configuration of RequestHeaderModifier filter.

Kind: `TCPRoute`

TCPRoute allows mapping TCP requests from a Gateway to Kubernetes Services.

Declaring TCPRoute

apiVersion: gateway.networking.k8s.io/v1
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.io                 # [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` 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.

Declaring TLSRoute

apiVersion: gateway.networking.k8s.io/v1
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.io                 # [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` and `gateway.networking.k8s.io` values are supported.
[12]	`kind`	Kind is kind of the referent. Only `TraefikService` and `Service` values are supported.