Traefik & Kubernetes

The Kubernetes Ingress Controller, The Custom Resource Way.

Resource Configuration

If you're in a hurry, maybe you'd rather go through the dynamic configuration reference.

Traefik IngressRoute definition

  1. apiVersion: apiextensions.k8s.io/v1beta1
  2. kind: CustomResourceDefinition
  3. metadata:
  4.   name: ingressroutes.traefik.containo.us
  6. spec:
  7.   group: traefik.containo.us
  8.   version: v1alpha1
  9.   names:
  10.     kind: IngressRoute
  11.     plural: ingressroutes
  12.     singular: ingressroute
  13.   scope: Namespaced
  15. ---
  16. apiVersion: apiextensions.k8s.io/v1beta1
  17. kind: CustomResourceDefinition
  18. metadata:
  19.   name: ingressroutetcps.traefik.containo.us
  21. spec:
  22.   group: traefik.containo.us
  23.   version: v1alpha1
  24.   names:
  25.     kind: IngressRouteTCP
  26.     plural: ingressroutetcps
  27.     singular: ingressroutetcp
  28.   scope: Namespaced

That IngressRoute kind can then be used to define an IngressRoute object, such as in:

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: ingressroutefoo
  6. spec:
  7.   entryPoints:
  8.     - web
  9.   routes:
  10.   # Match is the rule corresponding to an underlying router.
  11.   # Later on, match could be the simple form of a path prefix, e.g. just "/bar",
  12.   # but for now we only support a traefik style matching rule.
  13.   - match: Host(`foo.com`) && PathPrefix(`/bar`)
  14.     # kind could eventually be one of "Rule", "Path", "Host", "Method", "Header",
  15.     # "Parameter", etc, to support simpler forms of rule matching, but for now we
  16.     # only support "Rule".
  17.     kind: Rule
  18.     # (optional) Priority disambiguates rules of the same length, for route matching.
  19.     priority: 12
  20.     services:
  21.     - name: whoami
  22.       port: 80
  23.       # (default 1) A weight used by the weighted round-robin strategy (WRR).  
  24.       weight: 1
  25.       # (default true) PassHostHeader controls whether to leave the request's Host
  26.       # Header as it was before it reached the proxy, or whether to let the proxy set it
  27.       # to the destination (backend) host.
  28.       passHostHeader: true
  29.       responseForwarding:
  30.         # (default 100ms) Interval between flushes of the buffered response body to the client.
  31.         flushInterval: 100ms
  33. ---
  34. apiVersion: traefik.containo.us/v1alpha1
  35. kind: IngressRouteTCP
  36. metadata:
  37.   name: ingressroutetcpfoo.crd
  39. spec:
  40.   entryPoints:
  41.     - footcp
  42.   routes:
  43.   # Match is the rule corresponding to an underlying router.
  44.   - match: HostSNI(`*`)
  45.     services:
  46.     - name: whoamitcp
  47.       port: 8080

Middleware

Additionally, to allow for the use of middlewares in an IngressRoute, we defined the CRD below for the Middleware kind.

  1. apiVersion: apiextensions.k8s.io/v1beta1
  2. kind: CustomResourceDefinition
  3. metadata:
  4.   name: middlewares.traefik.containo.us
  6. spec:
  7.   group: traefik.containo.us
  8.   version: v1alpha1
  9.   names:
  10.     kind: Middleware
  11.     plural: middlewares
  12.     singular: middleware
  13.   scope: Namespaced

Once the Middleware kind has been registered with the Kubernetes cluster, it can then be used in IngressRoute definitions, such as:

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: stripprefix
  5.   namespace: foo
  7. spec:
  8.   stripPrefix:
  9.     prefixes:
  10.       - /stripit
  12. ---
  13. apiVersion: traefik.containo.us/v1alpha1
  14. kind: IngressRoute
  15. metadata:
  16.   name: ingressroutebar
  18. spec:
  19.   entryPoints:
  20.     - web
  21.   routes:
  22.   - match: Host(`bar.com`) && PathPrefix(`/stripit`)
  23.     kind: Rule
  24.     services:
  25.     - name: whoami
  26.       port: 80
  27.     middlewares:
  28.     - name: stripprefix
  29.       namespace: foo

Cross-provider namespace

As Kubernetes also has its own notion of namespace, one should not confuse the kubernetes namespace of a resource(in the reference to the middleware) with the provider namespace,when the definition of the middleware is from another provider.In this context, specifying a namespace when referring to the resource does not make any sense, and will be ignored.

More information about available middlewares in the dedicated middlewares section.

Services

If one needs a setup more sophisticated than a load-balancer of servers (which is a Kubernetes Service kind behind the scenes),one can define and use additional service objects specific to Traefik, based on the TraefikService kind defined in the CRD below.

  1. apiVersion: apiextensions.k8s.io/v1beta1
  2. kind: CustomResourceDefinition
  3. metadata:
  4.   name: traefikservices.traefik.containo.us
  6. spec:
  7.   group: traefik.containo.us
  8.   version: v1alpha1
  9.   names:
  10.     kind: TraefikService
  11.     plural: traefikservices
  12.     singular: traefikservice
  13.   scope: Namespaced

Once the TraefikService kind has been registered with the Kubernetes cluster, it can then be used in IngressRoute definitions(as well as recursively in other Traefik Services), such as below.Note how the name field in the IngressRoute definition now refers to a TraefikService instead of a (Kubernetes) Service.The reason this is allowed, and why a name can refer either to a TraefikService or a Service,is because the kind field is used to break the ambiguity. The allowed values for this field are TraefikService, or Service(which is the default value).

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: TraefikService
  3. metadata:
  4.   name: wrr1
  5.   namespace: default
  7. spec:
  8.   weighted:
  9.     services:
  10.       - name: s2
  11.         kind: Service
  12.         port: 80
  13.         weight: 1
  14.       - name: s3
  15.         weight: 1
  16.         port: 80
  18. ---
  19. apiVersion: traefik.containo.us/v1alpha1
  20. kind: TraefikService
  21. metadata:
  22.   name: mirror1
  23.   namespace: default
  25. spec:
  26.   mirroring:
  27.     name: wrr1
  28.     kind: TraefikService
  29.     mirrors:
  30.       - name: s1
  31.         percent: 20
  32.         port: 80
  34. ---
  35. apiVersion: traefik.containo.us/v1alpha1
  36. kind: IngressRoute
  37. metadata:
  38.   name: ingressroutebar
  39.   namespace: default
  42. spec:
  43.   entryPoints:
  44.     - web
  45.   routes:
  46.   - match: Host(`bar.com`) && PathPrefix(`/foo`)
  47.     kind: Rule
  48.     services:
  49.     - name: mirror1
  50.       namespace: default
  51.       kind: TraefikService

References and namespaces

If the optional namespace attribute is not set, the configuration will be applied with the namespace of the current resource.

Additionally, when the definition of the TraefikService is from another provider,the cross-provider syntax ([email protected]) should be used to refer to the TraefikService, just as in the middleware case.Specifying a namespace attribute in this case would not make any sense, and will be ignored (except if the provider is kubernetescrd).

TLS Option

Additionally, to allow for the use of TLS options in an IngressRoute, we defined the CRD below for the TLSOption kind.More information about TLS Options is available in the dedicated TLS Configuration Options.

  1. apiVersion: apiextensions.k8s.io/v1beta1
  2. kind: CustomResourceDefinition
  3. metadata:
  4.   name: tlsoptions.traefik.containo.us
  6. spec:
  7.   group: traefik.containo.us
  8.   version: v1alpha1
  9.   names:
  10.     kind: TLSOption
  11.     plural: tlsoptions
  12.     singular: tlsoption
  13.   scope: Namespaced

Once the TLSOption kind has been registered with the Kubernetes cluster or defined in the File Provider, it can then be used in IngressRoute definitions, such as:

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: TLSOption
  3. metadata:
  4.   name: mytlsoption
  5.   namespace: default
  7. spec:
  8.   minVersion: VersionTLS12
  10. ---
  11. apiVersion: traefik.containo.us/v1alpha1
  12. kind: IngressRoute
  13. metadata:
  14.   name: ingressroutebar
  16. spec:
  17.   entryPoints:
  18.     - web
  19.   routes:
  20.   - match: Host(`bar.com`) && PathPrefix(`/stripit`)
  21.     kind: Rule
  22.     services:
  23.     - name: whoami
  24.       port: 80
  25.   tls:
  26.     options: 
  27.       name: mytlsoption
  28.       namespace: default

References and namespaces

If the optional namespace attribute is not set, the configuration will be applied with the namespace of the IngressRoute.

Additionally, when the definition of the TLS option is from another provider,the cross-provider syntax ([email protected]) should be used to refer to the TLS option,just as in the middleware case.Specifying a namespace attribute in this case would not make any sense, and will be ignored.

TLS

To allow for TLS, we made use of the Secret kind, as it was already defined, and it can be directly used in an IngressRoute:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: supersecret
  6. data:
  7.   tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  8.   tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=
  10. ---
  11. apiVersion: traefik.containo.us/v1alpha1
  12. kind: IngressRoute
  13. metadata:
  14.   name: ingressroutetls
  16. spec:
  17.   entryPoints:
  18.     - websecure
  19.   routes:
  20.   - match: Host(`foo.com`) && PathPrefix(`/bar`)
  21.     kind: Rule
  22.     services:
  23.     - name: whoami
  24.       port: 443
  25.   tls:
  26.     secretName: supersecret

Further

Also see the full example with Let's Encrypt.