Traefik & Kubernetes¶

The Kubernetes Gateway API, The Experimental Way.

Configuration Examples¶

Configuring Kubernetes Gateway provider and Deploying/Exposing Services

Gateway API

---
kind: GatewayClass
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: my-gateway-class
spec:
  controller: traefik.io/gateway-controller

---
kind: Gateway
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: my-gateway
spec:
  gatewayClassName: my-gateway-class
  listeners:
    - protocol: HTTPS
      port: 443
      tls:
        certificateRef:
          group: "core"
          kind: "Secret"
          name: "mysecret"
      routes:
        kind: HTTPRoute
        selector:
          matchLabels:
            app: foo
---
kind: HTTPRoute
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: http-app-1
  namespace: default
  labels:
    app: foo
spec:
  hostnames:
    - "whoami"
  rules:
    - matches:
        - path:
            type: Exact
            value: /foo
      forwardTo:
        - serviceName: whoami
          port: 80
          weight: 1

Whoami Service

---
kind: Deployment
apiVersion: apps/v1
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:
  ports:
    - protocol: TCP
      port: 80
  selector:
    app: whoami

Traefik Service

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: traefik-controller

---
kind: Deployment
apiVersion: apps/v1
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/traefik:latest
          imagePullPolicy: IfNotPresent
          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:
  selector:
    app: traefik-lb
  ports:
    - protocol: TCP
      port: 80
      targetPort: web
      name: web
    - protocol: TCP
      port: 443
      targetPort: websecure
      name: websecure
  type: LoadBalancer

RBAC

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: gateway-role
rules:
  - apiGroups:
      - ""
    resources:
      - services
      - endpoints
      - secrets
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - networking.x-k8s.io
    resources:
      - gatewayclasses
      - gateways
      - httproutes
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - networking.x-k8s.io
    resources:
      - gatewayclasses/status
      - gateways/status
      - httproutes/status
    verbs:
      - update

---
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1beta1
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

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

kind: GatewayClass
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: my-gateway-class
spec:
  # Controller is a domain/path string that indicates
  # the controller that is managing Gateways of this class.
  controller: 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.

Declaring Gateway

kind: Gateway
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: my-gateway
  namespace: default
spec:
  gatewayClassName: my-gateway-class        # [1]
  listeners:                                # [2]
    - protocol: HTTPS                       # [3] 
      port: 443                             # [4]
      tls:                                  # [5]
        certificateRef:                     # [6]
          group: "core"
          kind: "Secret"
          name: "mysecret"
      routes:                               # [7]
        kind: HTTPRoute                     # [8]
        selector:                           # [9]
          matchLabels:                      # [10]
            app: foo

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]	`protocol`	The network protocol this listener expects to receive (only HTTP and HTTPS are implemented).
[4]	`port`	The network port.
[5]	`tls`	TLS configuration for the Listener. This field is required if the Protocol field is "HTTPS" or "TLS" and ignored otherwise.
[6]	`certificateRef`	The reference to Kubernetes object that contains a TLS certificate and private key.
[7]	`routes`	A schema for associating routes with the Listener using selectors.
[8]	`kind`	The kind of the referent.
[9]	`selector`	Routes in namespaces selected by the selector may be used by this Gateway routes to associate with the Gateway.
[10]	`matchLabels`	A set of route labels used for selecting routes to associate with the 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

kind: HTTPRoute
apiVersion: networking.x-k8s.io/v1alpha1
metadata:
  name: http-app-1
  namespace: default
  labels:                       # [1]
    app: foo
spec:
  hostnames:                    # [2]
    - "whoami"
  rules:                        # [3]
    - matches:                  # [4]
        - path:                 # [5]
            type: Exact         # [6]
            value: /bar         # [7]
        - headers:              # [8]
            type: Exact         # [9]
            values:             # [10]
              foo: bar
      forwardTo:                # [11]
        - serviceName: whoami   # [12]
          weight: 1             # [13]
          port: 80              # [14]

Ref	Attribute	Description
[1]	`labels`	Labels to match with the `Gateway` labelselector.
[2]	`hostnames`	A set of hostname that should match against the HTTP Host header to select a HTTPRoute to process the request.
[3]	`rules`	A list of HTTP matchers, filters and actions.
[4]	`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.
[5]	`path`	An HTTP request path matcher. If this field is not specified, a default prefix match on the "/" path is provided.
[6]	`type`	Type of match against the path Value (supported types: `Exact`, `Prefix`).
[7]	`value`	The value of the HTTP path to match against.
[8]	`headers`	Conditions to select a HTTP route by matching HTTP request headers.
[9]	`type`	Type of match for the HTTP request header match against the `values` (supported types: `Exact`).
[10]	`values`	A map of HTTP Headers to be matched. It MUST contain at least one entry.
[11]	`forwardTo`	The upstream target(s) where the request should be sent.
[12]	`serviceName`	The name of the referent service.
[13]	`weight`	The proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs).
[14]	`port`	The port of the referent service.

Traefik & Kubernetes¶

Configuration Examples¶

Routing Configuration¶

Custom Resource Definition (CRD)¶

Kind: GatewayClass¶

Kind: Gateway¶

Kind: HTTPRoute¶

Kind: `GatewayClass`¶

Kind: `Gateway`¶

Kind: `HTTPRoute`¶