Traefik & Kubernetes

The Kubernetes Gateway API, The Experimental Way.

Configuration Examples

Configuring Kubernetes Gateway provider and Deploying/Exposing Services

Gateway API

  1. ---
  2. kind: GatewayClass
  3. apiVersion: networking.x-k8s.io/v1alpha1
  4. metadata:
  5. name: my-gateway-class
  6. spec:
  7. controller: traefik.io/gateway-controller
  8. ---
  9. kind: Gateway
  10. apiVersion: networking.x-k8s.io/v1alpha1
  11. metadata:
  12. name: my-gateway
  13. spec:
  14. gatewayClassName: my-gateway-class
  15. listeners:
  16. - protocol: HTTPS
  17. port: 443
  18. tls:
  19. certificateRef:
  20. group: "core"
  21. kind: "Secret"
  22. name: "mysecret"
  23. routes:
  24. kind: HTTPRoute
  25. selector:
  26. matchLabels:
  27. app: foo
  28. ---
  29. kind: HTTPRoute
  30. apiVersion: networking.x-k8s.io/v1alpha1
  31. metadata:
  32. name: http-app-1
  33. namespace: default
  34. labels:
  35. app: foo
  36. spec:
  37. hostnames:
  38. - "whoami"
  39. rules:
  40. - matches:
  41. - path:
  42. type: Exact
  43. value: /foo
  44. forwardTo:
  45. - serviceName: whoami
  46. port: 80
  47. weight: 1

Whoami Service

  1. ---
  2. kind: Deployment
  3. apiVersion: apps/v1
  4. metadata:
  5. name: whoami
  6. spec:
  7. replicas: 2
  8. selector:
  9. matchLabels:
  10. app: whoami
  11. template:
  12. metadata:
  13. labels:
  14. app: whoami
  15. spec:
  16. containers:
  17. - name: whoami
  18. image: traefik/whoami
  19. ---
  20. apiVersion: v1
  21. kind: Service
  22. metadata:
  23. name: whoami
  24. spec:
  25. ports:
  26. - protocol: TCP
  27. port: 80
  28. selector:
  29. app: whoami

Traefik Service

  1. ---
  2. apiVersion: v1
  3. kind: ServiceAccount
  4. metadata:
  5. name: traefik-controller
  6. ---
  7. kind: Deployment
  8. apiVersion: apps/v1
  9. metadata:
  10. name: traefik
  11. spec:
  12. replicas: 1
  13. selector:
  14. matchLabels:
  15. app: traefik-lb
  16. template:
  17. metadata:
  18. labels:
  19. app: traefik-lb
  20. spec:
  21. serviceAccountName: traefik-controller
  22. containers:
  23. - name: traefik
  24. image: traefik/traefik:latest
  25. imagePullPolicy: IfNotPresent
  26. args:
  27. - --entrypoints.web.address=:80
  28. - --entrypoints.websecure.address=:443
  29. - --experimental.kubernetesgateway
  30. - --providers.kubernetesgateway
  31. ports:
  32. - name: web
  33. containerPort: 80
  34. - name: websecure
  35. containerPort: 443
  36. ---
  37. apiVersion: v1
  38. kind: Service
  39. metadata:
  40. name: traefik
  41. spec:
  42. selector:
  43. app: traefik-lb
  44. ports:
  45. - protocol: TCP
  46. port: 80
  47. targetPort: web
  48. name: web
  49. - protocol: TCP
  50. port: 443
  51. targetPort: websecure
  52. name: websecure
  53. type: LoadBalancer

RBAC

  1. ---
  2. apiVersion: rbac.authorization.k8s.io/v1
  3. kind: ClusterRole
  4. metadata:
  5. name: gateway-role
  6. rules:
  7. - apiGroups:
  8. - ""
  9. resources:
  10. - services
  11. - endpoints
  12. - secrets
  13. verbs:
  14. - get
  15. - list
  16. - watch
  17. - apiGroups:
  18. - networking.x-k8s.io
  19. resources:
  20. - gatewayclasses
  21. - gateways
  22. - httproutes
  23. verbs:
  24. - get
  25. - list
  26. - watch
  27. - apiGroups:
  28. - networking.x-k8s.io
  29. resources:
  30. - gatewayclasses/status
  31. - gateways/status
  32. - httproutes/status
  33. verbs:
  34. - update
  35. ---
  36. kind: ClusterRoleBinding
  37. apiVersion: rbac.authorization.k8s.io/v1beta1
  38. metadata:
  39. name: gateway-controller
  40. roleRef:
  41. apiGroup: rbac.authorization.k8s.io
  42. kind: ClusterRole
  43. name: gateway-role
  44. subjects:
  45. - kind: ServiceAccount
  46. name: traefik-controller
  47. 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 Service APIs 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:

KindPurposeConcept Behind
GatewayClassDefines a set of Gateways that share a common configuration and behaviourGatewayClass
GatewayDescribes how traffic can be translated to Services within the clusterGateway
HTTPRouteHTTP rules for mapping requests from a Gateway to Kubernetes ServicesRoute

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

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

  1. kind: Gateway
  2. apiVersion: networking.x-k8s.io/v1alpha1
  3. metadata:
  4. name: my-gateway
  5. namespace: default
  6. spec:
  7. gatewayClassName: my-gateway-class # [1]
  8. listeners: # [2]
  9. - protocol: HTTPS # [3]
  10. port: 443 # [4]
  11. tls: # [5]
  12. certificateRef: # [6]
  13. group: "core"
  14. kind: "Secret"
  15. name: "mysecret"
  16. routes: # [7]
  17. kind: HTTPRoute # [8]
  18. selector: # [9]
  19. matchLabels: # [10]
  20. app: foo
RefAttributeDescription
[1]gatewayClassNameGatewayClassName used for this Gateway. This is the name of a GatewayClass resource.
[2]listenersLogical endpoints that are bound on this Gateway’s addresses. At least one Listener MUST be specified.
[3]protocolThe network protocol this listener expects to receive (only HTTP and HTTPS are implemented).
[4]portThe network port.
[5]tlsTLS configuration for the Listener. This field is required if the Protocol field is “HTTPS” or “TLS” and ignored otherwise.
[6]certificateRefThe reference to Kubernetes object that contains a TLS certificate and private key.
[7]routesA schema for associating routes with the Listener using selectors.
[8]kindThe kind of the referent.
[9]selectorRoutes in namespaces selected by the selector may be used by this Gateway routes to associate with the Gateway.
[10]matchLabelsA 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

  1. kind: HTTPRoute
  2. apiVersion: networking.x-k8s.io/v1alpha1
  3. metadata:
  4. name: http-app-1
  5. namespace: default
  6. labels: # [1]
  7. app: foo
  8. spec:
  9. hostnames: # [2]
  10. - "whoami"
  11. rules: # [3]
  12. - matches: # [4]
  13. - path: # [5]
  14. type: Exact # [6]
  15. value: /bar # [7]
  16. - headers: # [8]
  17. type: Exact # [9]
  18. values: # [10]
  19. - foo: bar
  20. forwardTo: # [11]
  21. - serviceName: whoami # [12]
  22. weight: 1 # [13]
  23. port: 80 # [14]
RefAttributeDescription
[1]labelsLabels to match with the Gateway labelselector.
[2]hostnamesA set of hostname that should match against the HTTP Host header to select a HTTPRoute to process the request.
[3]rulesA list of HTTP matchers, filters and actions.
[4]matchesConditions 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]pathAn HTTP request path matcher. If this field is not specified, a default prefix match on the “/“ path is provided.
[6]typeType of match against the path Value (supported types: Exact, Prefix).
[7]valueThe value of the HTTP path to match against.
[8]headersConditions to select a HTTP route by matching HTTP request headers.
[9]typeType of match for the HTTP request header match against the values (supported types: Exact).
[10]valuesA map of HTTP Headers to be matched. It MUST contain at least one entry.
[11]forwardToThe upstream target(s) where the request should be sent.
[12]serviceNameThe name of the referent service.
[13]weightThe proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs).
[14]portThe port of the referent service.