Traefik & Kubernetes

The Kubernetes Gateway API, The Experimental Way. {: .subtitle }

Configuration Examples

Configuring Kubernetes Gateway provider and Deploying/Exposing Services

Gateway API

  1. ---
  2. apiVersion: gateway.networking.k8s.io/v1alpha2
  3. kind: GatewayClass
  4. metadata:
  5. name: my-gateway-class
  6. spec:
  7. controllerName: traefik.io/gateway-controller
  8. ---
  9. apiVersion: gateway.networking.k8s.io/v1alpha2
  10. kind: Gateway
  11. metadata:
  12. name: my-gateway
  13. spec:
  14. gatewayClassName: my-gateway-class
  15. listeners:
  16. - name: https
  17. protocol: HTTPS
  18. port: 443
  19. tls:
  20. certificateRefs:
  21. - kind: Secret
  22. name: mysecret
  23. ---
  24. apiVersion: gateway.networking.k8s.io/v1alpha2
  25. kind: HTTPRoute
  26. metadata:
  27. name: http-app
  28. namespace: default
  29. spec:
  30. parentRefs:
  31. - name: my-gateway
  32. hostnames:
  33. - whoami
  34. rules:
  35. - matches:
  36. - path:
  37. type: Exact
  38. value: /foo
  39. backendRefs:
  40. - name: whoami
  41. port: 80
  42. weight: 1

Whoami Service

  1. ---
  2. apiVersion: apps/v1
  3. kind: Deployment
  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. selector:
  26. app: whoami
  27. ports:
  28. - protocol: TCP
  29. port: 80

Traefik Service

  1. ---
  2. apiVersion: v1
  3. kind: ServiceAccount
  4. metadata:
  5. name: traefik-controller
  6. ---
  7. apiVersion: apps/v1
  8. kind: Deployment
  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:v2.8
  25. args:
  26. - --entrypoints.web.address=:80
  27. - --entrypoints.websecure.address=:443
  28. - --experimental.kubernetesgateway
  29. - --providers.kubernetesgateway
  30. ports:
  31. - name: web
  32. containerPort: 80
  33. - name: websecure
  34. containerPort: 443
  35. ---
  36. apiVersion: v1
  37. kind: Service
  38. metadata:
  39. name: traefik
  40. spec:
  41. type: LoadBalancer
  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

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. - namespaces
  11. verbs:
  12. - list
  13. - watch
  14. - apiGroups:
  15. - ""
  16. resources:
  17. - services
  18. - endpoints
  19. - secrets
  20. verbs:
  21. - get
  22. - list
  23. - watch
  24. - apiGroups:
  25. - gateway.networking.k8s.io
  26. resources:
  27. - gatewayclasses
  28. - gateways
  29. - httproutes
  30. - tcproutes
  31. - tlsroutes
  32. verbs:
  33. - get
  34. - list
  35. - watch
  36. - apiGroups:
  37. - gateway.networking.k8s.io
  38. resources:
  39. - gatewayclasses/status
  40. - gateways/status
  41. - httproutes/status
  42. - tcproutes/status
  43. - tlsroutes/status
  44. verbs:
  45. - update
  46. ---
  47. apiVersion: rbac.authorization.k8s.io/v1
  48. kind: ClusterRoleBinding
  49. metadata:
  50. name: gateway-controller
  51. roleRef:
  52. apiGroup: rbac.authorization.k8s.io
  53. kind: ClusterRole
  54. name: gateway-role
  55. subjects:
  56. - kind: ServiceAccount
  57. name: traefik-controller
  58. 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:

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
TCPRouteAllows mapping TCP requests from a Gateway to Kubernetes ServicesRoute
TLSRouteAllows mapping TLS 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. apiVersion: gateway.networking.k8s.io/v1alpha2
  2. kind: GatewayClass
  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. 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 ProtocolTLS ModeRoute Type Supported
TCPNot applicableTCPRoute
TLSPassthroughTLSRoute, TCPRoute
TLSTerminateTLSRoute, TCPRoute
HTTPNot applicableHTTPRoute
HTTPSTerminateHTTPRoute

Declaring Gateway

HTTP Listener

  1. apiVersion: gateway.networking.k8s.io/v1alpha2
  2. kind: Gateway
  3. metadata:
  4. name: my-http-gateway
  5. namespace: default
  6. spec:
  7. gatewayClassName: my-gateway-class # [1]
  8. listeners: # [2]
  9. - name: http # [3]
  10. protocol: HTTP # [4]
  11. port: 80 # [5]
  12. allowedRoutes: # [9]
  13. kinds:
  14. - kind: HTTPRoute # [10]
  15. namespaces:
  16. from: Selector # [11]
  17. selector: # [12]
  18. matchLabels:
  19. app: foo

HTTPS Listener

  1. apiVersion: gateway.networking.k8s.io/v1alpha2
  2. kind: Gateway
  3. metadata:
  4. name: my-https-gateway
  5. namespace: default
  6. spec:
  7. gatewayClassName: my-gateway-class # [1]
  8. listeners: # [2]
  9. - name: https # [3]
  10. protocol: HTTPS # [4]
  11. port: 443 # [5]
  12. tls: # [7]
  13. certificateRefs: # [8]
  14. - kind: "Secret"
  15. name: "mysecret"
  16. allowedRoutes: # [9]
  17. kinds:
  18. - kind: HTTPSRoute # [10]
  19. namespaces:
  20. from: Selector # [11]
  21. selector: # [12]
  22. matchLabels:
  23. app: foo

TCP Listener

  1. apiVersion: gateway.networking.k8s.io/v1alpha2
  2. kind: Gateway
  3. metadata:
  4. name: my-tcp-gateway
  5. namespace: default
  6. spec:
  7. gatewayClassName: my-gateway-class # [1]
  8. listeners: # [2]
  9. - name: tcp # [3]
  10. protocol: TCP # [4]
  11. port: 8000 # [5]
  12. allowedRoutes: # [9]
  13. kinds:
  14. - kind: TCPRoute # [10]
  15. namespaces:
  16. from: Selector # [11]
  17. selector: # [12]
  18. matchLabels:
  19. app: footcp

TLS Listener

  1. apiVersion: gateway.networking.k8s.io/v1alpha2
  2. kind: Gateway
  3. metadata:
  4. name: my-tls-gateway
  5. namespace: default
  6. spec:
  7. gatewayClassName: my-gateway-class # [1]
  8. listeners: # [2]
  9. - name: tls # [3]
  10. protocol: TLS # [4]
  11. port: 443 # [5]
  12. hostname: foo.com # [6]
  13. tls: # [7]
  14. certificateRefs: # [8]
  15. - kind: "Secret"
  16. name: "mysecret"
  17. allowedRoutes: # [9]
  18. kinds:
  19. - kind: TLSRoute # [10]
  20. namespaces:
  21. from: Selector # [11]
  22. selector: # [12]
  23. matchLabels:
  24. app: footcp
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]nameName of the Listener.
[4]protocolThe network protocol this listener expects to receive (only HTTP and HTTPS are implemented).
[5]portThe network port.
[6]hostnameHostname specifies the virtual hostname to match for protocol types that define this concept. When unspecified, “”, or *, all hostnames are matched.
[7]tlsTLS configuration for the Listener. This field is required if the Protocol field is “HTTPS” or “TLS” and ignored otherwise.
[8]certificateRefsThe references to Kubernetes objects that contains TLS certificates and private keys (only one reference to a Kubernetes Secret is supported).
[9]allowedRoutesDefines the types of routes that MAY be attached to a Listener and the trusted namespaces where those Route resources MAY be present.
[10]kindThe kind of the Route.
[11]fromFrom indicates in which namespaces the Routes will be selected for this Gateway. Possible values are All, Same and Selector (Defaults to Same).
[12]selectorSelector 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

  1. apiVersion: gateway.networking.k8s.io/v1alpha2
  2. kind: HTTPRoute
  3. metadata:
  4. name: http-app
  5. namespace: default
  6. spec:
  7. parentRefs: # [1]
  8. - name: my-tcp-gateway # [2]
  9. namespace: default # [3]
  10. sectionName: tcp # [4]
  11. hostnames: # [5]
  12. - whoami
  13. rules: # [6]
  14. - matches: # [7]
  15. - path: # [8]
  16. type: Exact # [9]
  17. value: /bar # [10]
  18. - headers: # [11]
  19. name: foo # [12]
  20. value: bar # [13]
  21. - backendRefs: # [14]
  22. - name: whoamitcp # [15]
  23. weight: 1 # [16]
  24. port: 8080 # [17]
  25. - name: [email protected]
  26. group: traefik.containo.us # [18]
  27. kind: TraefikService # [19]
RefAttributeDescription
[1]parentRefsReferences the resources (usually Gateways) that a Route wants to be attached to.
[2]nameName of the referent.
[3]namespaceNamespace of the referent. When unspecified (or empty string), this refers to the local namespace of the Route.
[4]sectionNameName of a section within the target resource (the Listener name).
[5]hostnamesA set of hostname that should match against the HTTP Host header to select a HTTPRoute to process the request.
[6]rulesA list of HTTP matchers, filters and actions.
[7]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.
[8]pathAn HTTP request path matcher. If this field is not specified, a default prefix match on the “/“ path is provided.
[9]typeType of match against the path Value (supported types: Exact, Prefix).
[10]valueThe value of the HTTP path to match against.
[11]headersConditions to select a HTTP route by matching HTTP request headers.
[12]typeType of match for the HTTP request header match against the values (supported types: Exact).
[13]valueA map of HTTP Headers to be matched. It MUST contain at least one entry.
[14]backendRefsDefines the backend(s) where matching requests should be sent.
[15]nameThe name of the referent service.
[16]weightThe proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs).
[17]portThe port of the referent service.
[18]groupGroup is the group of the referent. Only traefik.containo.us and gateway.networking.k8s.io values are supported.
[19]kindKind 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

  1. apiVersion: gateway.networking.k8s.io/v1alpha2
  2. kind: TCPRoute
  3. metadata:
  4. name: tcp-app
  5. namespace: default
  6. spec:
  7. parentRefs: # [1]
  8. - name: my-tcp-gateway # [2]
  9. namespace: default # [3]
  10. sectionName: tcp # [4]
  11. rules: # [5]
  12. - backendRefs: # [6]
  13. - name: whoamitcp # [7]
  14. weight: 1 # [8]
  15. port: 8080 # [9]
  16. - name: [email protected]
  17. group: traefik.containo.us # [10]
  18. kind: TraefikService # [11]
RefAttributeDescription
[1]parentRefsReferences the resources (usually Gateways) that a Route wants to be attached to.
[2]nameName of the referent.
[3]namespaceNamespace of the referent. When unspecified (or empty string), this refers to the local namespace of the Route.
[4]sectionNameName of a section within the target resource (the Listener name).
[5]rulesRules are a list of TCP matchers and actions.
[6]backendRefsDefines the backend(s) where matching requests should be sent.
[7]nameThe name of the referent service.
[8]weightThe proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs).
[9]portThe port of the referent service.
[10]groupGroup is the group of the referent. Only traefik.containo.us and gateway.networking.k8s.io values are supported.
[11]kindKind 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

  1. apiVersion: gateway.networking.k8s.io/v1alpha2
  2. kind: TLSRoute
  3. metadata:
  4. name: tls-app
  5. namespace: default
  6. spec:
  7. parentRefs: # [1]
  8. - name: my-tls-gateway # [2]
  9. namespace: default # [3]
  10. sectionName: tcp # [4]
  11. hostnames: # [5]
  12. - whoami
  13. rules: # [6]
  14. - backendRefs: # [7]
  15. - name: whoamitcp # [8]
  16. weight: 1 # [9]
  17. port: 8080 # [10]
  18. - name: [email protected]
  19. group: traefik.containo.us # [11]
  20. kind: TraefikService # [12]
RefAttributeDescription
[1]parentRefsReferences the resources (usually Gateways) that a Route wants to be attached to.
[2]nameName of the referent.
[3]namespaceNamespace of the referent. When unspecified (or empty string), this refers to the local namespace of the Route.
[4]sectionNameName of a section within the target resource (the Listener name).
[5]hostnamesDefines a set of SNI names that should match against the SNI attribute of TLS ClientHello message in TLS handshake.
[6]rulesRules are a list of TCP matchers and actions.
[7]backendRefsDefines the backend(s) where matching requests should be sent.
[8]nameThe name of the referent service.
[9]weightThe proportion of traffic forwarded to a targetRef, computed as weight/(sum of all weights in targetRefs).
[10]portThe port of the referent service.
[11]groupGroup is the group of the referent. Only traefik.containo.us and gateway.networking.k8s.io values are supported.
[12]kindKind is kind of the referent. Only TraefikService and Service values are supported.