Skip to content

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

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: foo
apiVersion: 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: foo
apiVersion: 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: footcp
apiVersion: 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.containo.us        # [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, 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.
[18] group Group is the group of the referent. Only 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.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.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.