Traefik & Kubernetes

The Kubernetes Ingress Controller, The Custom Resource Way.

Configuration Examples

Configuring KubernetesCRD and Deploying/Exposing Services

Resource Definition

  1. # All resources definition must be declared
  2. apiVersion: apiextensions.k8s.io/v1beta1
  3. kind: CustomResourceDefinition
  4. metadata:
  5.   name: ingressroutes.traefik.containo.us
  7. spec:
  8.   group: traefik.containo.us
  9.   version: v1alpha1
  10.   names:
  11.     kind: IngressRoute
  12.     plural: ingressroutes
  13.     singular: ingressroute
  14.   scope: Namespaced
  16. ---
  17. apiVersion: apiextensions.k8s.io/v1beta1
  18. kind: CustomResourceDefinition
  19. metadata:
  20.   name: middlewares.traefik.containo.us
  22. spec:
  23.   group: traefik.containo.us
  24.   version: v1alpha1
  25.   names:
  26.     kind: Middleware
  27.     plural: middlewares
  28.     singular: middleware
  29.   scope: Namespaced
  31. ---
  32. apiVersion: apiextensions.k8s.io/v1beta1
  33. kind: CustomResourceDefinition
  34. metadata:
  35.   name: ingressroutetcps.traefik.containo.us
  37. spec:
  38.   group: traefik.containo.us
  39.   version: v1alpha1
  40.   names:
  41.     kind: IngressRouteTCP
  42.     plural: ingressroutetcps
  43.     singular: ingressroutetcp
  44.   scope: Namespaced
  46. ---
  47. apiVersion: apiextensions.k8s.io/v1beta1
  48. kind: CustomResourceDefinition
  49. metadata:
  50.   name: ingressrouteudps.traefik.containo.us
  52. spec:
  53.   group: traefik.containo.us
  54.   version: v1alpha1
  55.   names:
  56.     kind: IngressRouteUDP
  57.     plural: ingressrouteudps
  58.     singular: ingressrouteudp
  59.   scope: Namespaced
  61. ---
  62. apiVersion: apiextensions.k8s.io/v1beta1
  63. kind: CustomResourceDefinition
  64. metadata:
  65.   name: tlsoptions.traefik.containo.us
  67. spec:
  68.   group: traefik.containo.us
  69.   version: v1alpha1
  70.   names:
  71.     kind: TLSOption
  72.     plural: tlsoptions
  73.     singular: tlsoption
  74.   scope: Namespaced
  76. ---
  77. apiVersion: apiextensions.k8s.io/v1beta1
  78. kind: CustomResourceDefinition
  79. metadata:
  80.   name: tlsstores.traefik.containo.us
  82. spec:
  83.   group: traefik.containo.us
  84.   version: v1alpha1
  85.   names:
  86.     kind: TLSStore
  87.     plural: tlsstores
  88.     singular: tlsstore
  89.   scope: Namespaced
  91. ---
  92. apiVersion: apiextensions.k8s.io/v1beta1
  93. kind: CustomResourceDefinition
  94. metadata:
  95.   name: traefikservices.traefik.containo.us
  97. spec:
  98.   group: traefik.containo.us
  99.   version: v1alpha1
  100.   names:
  101.     kind: TraefikService
  102.     plural: traefikservices
  103.     singular: traefikservice
  104.   scope: Namespaced

RBAC

  1. kind: ClusterRole
  2. apiVersion: rbac.authorization.k8s.io/v1beta1
  3. metadata:
  4.   name: traefik-ingress-controller
  6. rules:
  7.   - apiGroups:
  8.       - ""
  9.     resources:
  10.       - services
  11.       - endpoints
  12.       - secrets
  13.     verbs:
  14.       - get
  15.       - list
  16.       - watch
  17.   - apiGroups:
  18.       - extensions
  19.       - networking.k8s.io
  20.     resources:
  21.       - ingresses
  22.       - ingressclasses
  23.     verbs:
  24.       - get
  25.       - list
  26.       - watch
  27.   - apiGroups:
  28.       - extensions
  29.     resources:
  30.       - ingresses/status
  31.     verbs:
  32.       - update
  33.   - apiGroups:
  34.       - traefik.containo.us
  35.     resources:
  36.       - middlewares
  37.       - ingressroutes
  38.       - traefikservices
  39.       - ingressroutetcps
  40.       - ingressrouteudps
  41.       - tlsoptions
  42.       - tlsstores
  43.     verbs:
  44.       - get
  45.       - list
  46.       - watch
  48. ---
  49. kind: ClusterRoleBinding
  50. apiVersion: rbac.authorization.k8s.io/v1beta1
  51. metadata:
  52.   name: traefik-ingress-controller
  54. roleRef:
  55.   apiGroup: rbac.authorization.k8s.io
  56.   kind: ClusterRole
  57.   name: traefik-ingress-controller
  58. subjects:
  59.   - kind: ServiceAccount
  60.     name: traefik-ingress-controller
  61.     namespace: default

Traefik

  1. apiVersion: v1
  2. kind: ServiceAccount
  3. metadata:
  4.   name: traefik-ingress-controller
  6. ---
  7. kind: Deployment
  8. apiVersion: apps/v1
  9. metadata:
  10.   name: traefik
  11.   labels:
  12.     app: traefik
  14. spec:
  15.   replicas: 1
  16.   selector:
  17.     matchLabels:
  18.       app: traefik
  19.   template:
  20.     metadata:
  21.       labels:
  22.         app: traefik
  23.     spec:
  24.       serviceAccountName: traefik-ingress-controller
  25.       containers:
  26.         - name: traefik
  27.           image: traefik:v2.3
  28.           args:
  29.             - --log.level=DEBUG
  30.             - --api
  31.             - --api.insecure
  32.             - --entrypoints.web.address=:80
  33.             - --entrypoints.tcpep.address=:8000
  34.             - --entrypoints.udpep.address=:9000/udp
  35.             - --providers.kubernetescrd
  36.           ports:
  37.             - name: web
  38.               containerPort: 80
  39.             - name: admin
  40.               containerPort: 8080
  41.             - name: tcpep
  42.               containerPort: 8000
  43.             - name: udpep
  44.               containerPort: 9000
  46. ---
  47. apiVersion: v1
  48. kind: Service
  49. metadata:
  50.   name: traefik
  51. spec:
  52.   type: LoadBalancer
  53.   selector:
  54.     app: traefik
  55.   ports:
  56.     - protocol: TCP
  57.       port: 80
  58.       name: web
  59.       targetPort: 80
  60.     - protocol: TCP
  61.       port: 8080
  62.       name: admin
  63.       targetPort: 8080
  64.     - protocol: TCP
  65.       port: 8000
  66.       name: tcpep
  67.       targetPort: 8000
  69. ---
  70. apiVersion: v1
  71. kind: Service
  72. metadata:
  73.   name: traefikudp
  74. spec:
  75.   type: LoadBalancer
  76.   selector:
  77.     app: traefik
  78.   ports:
  79.     - protocol: UDP
  80.       port: 9000
  81.       name: udpep
  82.       targetPort: 9000

IngressRoute

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: myingressroute
  5.   namespace: default
  7. spec:
  8.   entryPoints:
  9.     - web
  11.   routes:
  12.   - match: Host(`foo`) && PathPrefix(`/bar`)
  13.     kind: Rule
  14.     services:
  15.     - name: whoami
  16.       port: 80
  18. ---
  19. apiVersion: traefik.containo.us/v1alpha1
  20. kind: IngressRouteTCP
  21. metadata:
  22.   name: ingressroute.tcp
  23.   namespace: default
  25. spec:
  26.   entryPoints:
  27.     - tcpep
  28.   routes:
  29.   - match: HostSNI(`bar`)
  30.     kind: Rule
  31.     services:
  32.       - name: whoamitcp
  33.         port: 8080
  35. ---
  36. apiVersion: traefik.containo.us/v1alpha1
  37. kind: IngressRouteUDP
  38. metadata:
  39.   name: ingressroute.udp
  40.   namespace: default
  42. spec:
  43.   entryPoints:
  44.     - fooudp
  45.   routes:
  46.   - kind: Rule
  47.     services:
  48.       - name: whoamiudp
  49.         port: 8080

Whoami

  1. kind: Deployment
  2. apiVersion: apps/v1
  3. metadata:
  4.   name: whoami
  5.   namespace: default
  6.   labels:
  7.     app: traefiklabs
  8.     name: whoami
  10. spec:
  11.   replicas: 2
  12.   selector:
  13.     matchLabels:
  14.       app: traefiklabs
  15.       task: whoami
  16.   template:
  17.     metadata:
  18.       labels:
  19.         app: traefiklabs
  20.         task: whoami
  21.     spec:
  22.       containers:
  23.         - name: whoami
  24.           image: traefik/whoami
  25.           ports:
  26.             - containerPort: 80
  28. ---
  29. apiVersion: v1
  30. kind: Service
  31. metadata:
  32.   name: whoami
  33.   namespace: default
  35. spec:
  36.   ports:
  37.     - name: http
  38.       port: 80
  39.   selector:
  40.     app: traefiklabs
  41.     task: whoami
  43. ---
  44. kind: Deployment
  45. apiVersion: apps/v1
  46. metadata:
  47.   name: whoamitcp
  48.   namespace: default
  49.   labels:
  50.     app: traefiklabs
  51.     name: whoamitcp
  53. spec:
  54.   replicas: 2
  55.   selector:
  56.     matchLabels:
  57.       app: traefiklabs
  58.       task: whoamitcp
  59.   template:
  60.     metadata:
  61.       labels:
  62.         app: traefiklabs
  63.         task: whoamitcp
  64.     spec:
  65.       containers:
  66.         - name: whoamitcp
  67.           image: traefik/whoamitcp
  68.           ports:
  69.             - containerPort: 8080
  71. ---
  72. apiVersion: v1
  73. kind: Service
  74. metadata:
  75.   name: whoamitcp
  76.   namespace: default
  78. spec:
  79.   ports:
  80.     - protocol: TCP
  81.       port: 8080
  82.   selector:
  83.     app: traefiklabs
  84.     task: whoamitcp
  86. ---
  87. kind: Deployment
  88. apiVersion: apps/v1
  89. metadata:
  90.   name: whoamiudp
  91.   namespace: default
  92.   labels:
  93.     app: traefiklabs
  94.     name: whoamiudp
  96. spec:
  97.   replicas: 2
  98.   selector:
  99.     matchLabels:
  100.       app: traefiklabs
  101.       task: whoamiudp
  102.   template:
  103.     metadata:
  104.       labels:
  105.         app: traefiklabs
  106.         task: whoamiudp
  107.     spec:
  108.       containers:
  109.         - name: whoamiudp
  110.           image: traefik/whoamiudp:latest
  111.           ports:
  112.             - containerPort: 8080
  114. ---
  115. apiVersion: v1
  116. kind: Service
  117. metadata:
  118.   name: whoamiudp
  119.   namespace: default
  121. spec:
  122.   ports:
  123.     - port: 8080
  124.   selector:
  125.     app: traefiklabs
  126.     task: whoamiudp

Routing Configuration

Custom Resource Definition (CRD)

  • You can find an exhaustive list, generated from Traefik’s source code, of the custom resources and their attributes in the reference page.
  • Validate that the prerequisites are fulfilled before using the Traefik custom resources.
  • Traefik CRDs are building blocks that you can assemble according to your needs.

You can find an excerpt of the available custom resources in the table below:

KindPurposeConcept Behind
IngressRouteHTTP RoutingHTTP router
MiddlewareTweaks the HTTP requests before they are sent to your serviceHTTP Middlewares
TraefikServiceAbstraction for HTTP loadbalancing/mirroringHTTP service
IngressRouteTCPTCP RoutingTCP router
IngressRouteUDPUDP RoutingUDP router
TLSOptionsAllows to configure some parameters of the TLS connectionTLSOptions
TLSStoresAllows to configure the default TLS storeTLSStores

Kind: IngressRoute

IngressRoute is the CRD implementation of a Traefik HTTP router.

Register the IngressRoute kind in the Kubernetes cluster before creating IngressRoute objects.

IngressRoute Attributes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: foo
  5.   namespace: bar
  6. spec:
  7.   entryPoints:                      # [1]
  8.     - foo
  9.   routes:                           # [2]
  10.   - kind: Rule
  11.     match: Host(`test.example.com`) # [3]
  12.     priority: 10                    # [4]
  13.     middlewares:                    # [5]
  14.     - name: middleware1             # [6]
  15.       namespace: default            # [7]
  16.     services:                       # [8]
  17.     - kind: Service
  18.       name: foo
  19.       namespace: default
  20.       passHostHeader: true
  21.       port: 80
  22.       responseForwarding:
  23.         flushInterval: 1ms
  24.       scheme: https
  25.       sticky:
  26.         cookie:
  27.           httpOnly: true
  28.           name: cookie
  29.           secure: true
  30.           sameSite: none
  31.       strategy: RoundRobin
  32.       weight: 10
  33.   tls:                              # [9]
  34.     secretName: supersecret         # [10]
  35.     options:                        # [11]
  36.       name: opt                     # [12]
  37.       namespace: default            # [13]
  38.     certResolver: foo               # [14]
  39.     domains:                        # [15]
  40.     - main: example.net             # [16]
  41.       sans:                         # [17]
  42.       - a.example.net
  43.       - b.example.net
RefAttributePurpose
[1]entryPointsList of entry points names
[2]routesList of routes
[3]routes[n].matchDefines the rule corresponding to an underlying router.
[4]routes[n].priorityDisambiguate rules of the same length, for route matching
[5]routes[n].middlewaresList of reference to Middleware
[6]middlewares[n].nameDefines the Middleware name
[7]middlewares[n].namespaceDefines the Middleware namespace
[8]routes[n].servicesList of any combination of TraefikService and reference to a Kubernetes service (See below for ExternalName Service setup)
[9]tlsDefines TLS certificate configuration
[10]tls.secretNameDefines the secret name used to store the certificate (in the IngressRoute namespace)
[11]tls.optionsDefines the reference to a TLSOption
[12]options.nameDefines the TLSOption name
[13]options.namespaceDefines the TLSOption namespace
[14]tls.certResolverDefines the reference to a CertResolver
[15]tls.domainsList of domains
[16]domains[n].mainDefines the main domain name
[17]domains[n].sansList of SANs (alternative domains)

Declaring an IngressRoute

IngressRoute

  1. # All resources definition must be declared
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: IngressRoute
  4. metadata:
  5.   name: testName
  6.   namespace: default
  7. spec:
  8.   entryPoints:
  9.     - web
  10.   routes:
  11.   - kind: Rule
  12.     match: Host(`test.example.com`)
  13.     middlewares:
  14.     - name: middleware1
  15.       namespace: default
  16.     priority: 10
  17.     services:
  18.     - kind: Service
  19.       name: foo
  20.       namespace: default
  21.       passHostHeader: true
  22.       port: 80
  23.       responseForwarding:
  24.         flushInterval: 1ms
  25.       scheme: https
  26.       sticky:
  27.         cookie:
  28.           httpOnly: true
  29.           name: cookie
  30.           secure: true
  31.       strategy: RoundRobin
  32.       weight: 10
  33.   tls:
  34.     certResolver: foo
  35.     domains:
  36.     - main: example.net
  37.       sans:
  38.       - a.example.net
  39.       - b.example.net
  40.     options:
  41.       name: opt
  42.       namespace: default
  43.     secretName: supersecret

Middlewares

  1. # All resources definition must be declared
  2. # Prefixing with /foo
  3. apiVersion: traefik.containo.us/v1alpha1
  4. kind: Middleware
  5. metadata:
  6.   name: middleware1
  7.   namespace: default
  8. spec:
  9.   addPrefix:
  10.     prefix: /foo

TLSOption

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: TLSOption
  3. metadata:
  4.   name: opt
  5.   namespace: default
  7. spec:
  8.   minVersion: VersionTLS12

Secret

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: supersecret
  6. data:
  7.   tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  8.   tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

Configuring Backend Protocol

There are 3 ways to configure the backend protocol for communication between Traefik and your pods:

  • Setting the scheme explicitly (http/https/h2c)
  • Configuring the name of the kubernetes service port to start with https (https)
  • Setting the kubernetes service port to use port 443 (https)

If you do not configure the above, Traefik will assume an http connection.

Using Kubernetes ExternalName Service

Traefik backends creation needs a port to be set, however Kubernetes ExternalName Service could be defined without any port. Accordingly, Traefik supports defining a port in two ways:

  • only on IngressRoute service
  • on both sides, you’ll be warned if the ports don’t match, and the IngressRoute service port is used

Thus, in case of two sides port definition, Traefik expects a match between ports.

Examples

IngressRoute

  1. ---
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: IngressRoute
  4. metadata:
  5.   name: test.route
  6.   namespace: default
  8. spec:
  9.   entryPoints:
  10.     - foo
  12.   routes:
  13.   - match: Host(`example.net`)
  14.     kind: Rule
  15.     services:
  16.     - name: external-svc
  17.       port: 80
  19. ---
  20. apiVersion: v1
  21. kind: Service
  22. metadata:
  23.   name: external-svc
  24.   namespace: default
  25. spec:
  26.   externalName: external.domain
  27.   type: ExternalName

ExternalName Service

  1. ---
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: IngressRoute
  4. metadata:
  5.   name: test.route
  6.   namespace: default
  8. spec:
  9.   entryPoints:
  10.     - foo
  12.   routes:
  13.   - match: Host(`example.net`)
  14.     kind: Rule
  15.     services:
  16.     - name: external-svc
  18. ---
  19. apiVersion: v1
  20. kind: Service
  21. metadata:
  22.   name: external-svc
  23.   namespace: default
  24. spec:
  25.   externalName: external.domain
  26.   type: ExternalName
  27.   ports:
  28.     - port: 80

Both sides

  1. ---
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: IngressRoute
  4. metadata:
  5.   name: test.route
  6.   namespace: default
  8. spec:
  9.   entryPoints:
  10.     - foo
  12.   routes:
  13.   - match: Host(`example.net`)
  14.     kind: Rule
  15.     services:
  16.     - name: external-svc
  17.       port: 80
  19. ---
  20. apiVersion: v1
  21. kind: Service
  22. metadata:
  23.   name: external-svc
  24.   namespace: default
  25. spec:
  26.   externalName: external.domain
  27.   type: ExternalName
  28.   ports:
  29.     - port: 80

Kind: Middleware

Middleware is the CRD implementation of a Traefik middleware.

Register the Middleware kind in the Kubernetes cluster before creating Middleware objects or referencing middlewares in the IngressRoute objects.

Declaring and Referencing a Middleware

Middleware

  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

IngressRoute

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: ingressroutebar
  6. spec:
  7.   entryPoints:
  8.     - web
  9.   routes:
  10.   - match: Host(`example.com`) && PathPrefix(`/stripit`)
  11.     kind: Rule
  12.     services:
  13.     - name: whoami
  14.       port: 80
  15.     middlewares:
  16.     - name: stripprefix
  17.       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 comes from another provider. In this context, specifying a namespace when referring to the resource does not make any sense, and will be ignored. Additionally, when you want to reference a Middleware from the CRD Provider, you have to append the namespace of the resource in the resource-name as Traefik appends the namespace internally automatically.

More information about available middlewares in the dedicated middlewares section.

Kind: TraefikService

TraefikService is the CRD implementation of a “Traefik Service”.

Register the TraefikService kind in the Kubernetes cluster before creating TraefikService objects, referencing services in the IngressRoute objects, or recursively in others TraefikService objects.

Disambiguate Traefik and Kubernetes Services

As the field name can reference different types of objects, use the field kind to avoid any ambiguity.

The field kind allows the following values:

TraefikService object allows to use any (valid) combinations of:

Server Load Balancing

More information in the dedicated server load balancing section.

Declaring and Using Server Load Balancing

IngressRoute

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: ingressroutebar
  5.   namespace: default
  7. spec:
  8.   entryPoints:
  9.     - web
  10.   routes:
  11.   - match: Host(`example.com`) && PathPrefix(`/foo`)
  12.     kind: Rule
  13.     services:
  14.     - name: svc1
  15.       namespace: default
  16.     - name: svc2
  17.       namespace: default

K8s Service

  1. apiVersion: v1
  2. kind: Service
  3. metadata:
  4.   name: svc1
  5.   namespace: default
  7. spec:
  8.   ports:
  9.     - name: http
  10.       port: 80
  11.   selector:
  12.     app: traefiklabs
  13.     task: app1
  14. ---
  15. apiVersion: v1
  16. kind: Service
  17. metadata:
  18.   name: svc2
  19.   namespace: default
  21. spec:
  22.   ports:
  23.     - name: http
  24.       port: 80
  25.   selector:
  26.     app: traefiklabs
  27.     task: app2

Weighted Round Robin

More information in the dedicated Weighted Round Robin service load balancing section.

Declaring and Using Weighted Round Robin

IngressRoute

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: ingressroutebar
  5.   namespace: default
  7. spec:
  8.   entryPoints:
  9.     - web
  10.   routes:
  11.   - match: Host(`example.com`) && PathPrefix(`/foo`)
  12.     kind: Rule
  13.     services:
  14.     - name: wrr1
  15.       namespace: default
  16.       kind: TraefikService

Weighted Round Robin

  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: svc1
  11.         port: 80
  12.         weight: 1
  13.       - name: wrr2
  14.         kind: TraefikService
  15.         weight: 1
  16.       - name: mirror1
  17.         kind: TraefikService
  18.         weight: 1
  20. ---
  21. apiVersion: traefik.containo.us/v1alpha1
  22. kind: TraefikService
  23. metadata:
  24.   name: wrr2
  25.   namespace: default
  27. spec:
  28.   weighted:
  29.     services:
  30.       - name: svc2
  31.         port: 80
  32.         weight: 1
  33.       - name: svc3
  34.         port: 80
  35.         weight: 1

K8s Service

  1. apiVersion: v1
  2. kind: Service
  3. metadata:
  4.   name: svc1
  5.   namespace: default
  7. spec:
  8.   ports:
  9.     - name: http
  10.       port: 80
  11.   selector:
  12.     app: traefiklabs
  13.     task: app1
  14. ---
  15. apiVersion: v1
  16. kind: Service
  17. metadata:
  18.   name: svc2
  19.   namespace: default
  21. spec:
  22.   ports:
  23.     - name: http
  24.       port: 80
  25.   selector:
  26.     app: traefiklabs
  27.     task: app2
  28. ---
  29. apiVersion: v1
  30. kind: Service
  31. metadata:
  32.   name: svc3
  33.   namespace: default
  35. spec:
  36.   ports:
  37.     - name: http
  38.       port: 80
  39.   selector:
  40.     app: traefiklabs
  41.     task: app3

Mirroring

More information in the dedicated mirroring service section.

Declaring and Using Mirroring

IngressRoute

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: ingressroutebar
  5.   namespace: default
  7. spec:
  8.   entryPoints:
  9.     - web
  10.   routes:
  11.   - match: Host(`example.com`) && PathPrefix(`/foo`)
  12.     kind: Rule
  13.     services:
  14.     - name: mirror1
  15.       namespace: default
  16.       kind: TraefikService

Mirroring k8s Service

  1. # Mirroring from a k8s Service
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: TraefikService
  4. metadata:
  5.   name: mirror1
  6.   namespace: default
  8. spec:
  9.   mirroring:
  10.     name: svc1
  11.     port: 80
  12.     mirrors:
  13.       - name: svc2
  14.         port: 80
  15.         percent: 20
  16.       - name: svc3
  17.         kind: TraefikService
  18.         percent: 20

Mirroring Traefik Service

  1. # Mirroring from a Traefik Service
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: TraefikService
  4. metadata:
  5.   name: mirror1
  6.   namespace: default
  8. spec:
  9.   mirroring:
  10.     name: wrr1
  11.     kind: TraefikService
  12.      mirrors:
  13.        - name: svc2
  14.          port: 80
  15.          percent: 20
  16.        - name: svc3
  17.          kind: TraefikService
  18.          percent: 20

K8s Service

  1. apiVersion: v1
  2. kind: Service
  3. metadata:
  4.   name: svc1
  5.   namespace: default
  7. spec:
  8.   ports:
  9.     - name: http
  10.       port: 80
  11.   selector:
  12.     app: traefiklabs
  13.     task: app1
  14. ---
  15. apiVersion: v1
  16. kind: Service
  17. metadata:
  18.   name: svc2
  19.   namespace: default
  21. spec:
  22.   ports:
  23.     - name: http
  24.       port: 80
  25.   selector:
  26.     app: traefiklabs
  27.     task: app2

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 (service@provider) 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).

Stickiness and load-balancing

As explained in the section about Sticky sessions, for stickiness to work all the way, it must be specified at each load-balancing level.

For instance, in the example below, there is a first level of load-balancing because there is a (Weighted Round Robin) load-balancing of the two whoami services, and there is a second level because each whoami service is a replicaset and is thus handled as a load-balancer of servers.

Stickiness on two load-balancing levels

IngressRoute

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: ingressroutebar
  5.   namespace: default
  7. spec:
  8.   entryPoints:
  9.     - web
  10.   routes:
  11.   - match: Host(`example.com`) && PathPrefix(`/foo`)
  12.     kind: Rule
  13.     services:
  14.     - name: wrr1
  15.       namespace: default
  16.       kind: TraefikService

Weighted Round Robin

  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: whoami1
  11.         kind: Service
  12.         port: 80
  13.         weight: 1
  14.         sticky:
  15.           cookie:
  16.             name: lvl2
  17.       - name: whoami2
  18.         kind: Service
  19.         weight: 1
  20.         port: 80
  21.         sticky:
  22.           cookie:
  23.             name: lvl2
  24.     sticky:
  25.       cookie:
  26.         name: lvl1

K8s Service

  1. apiVersion: v1
  2. kind: Service
  3. metadata:
  4.   name: whoami1
  6. spec:
  7.   ports:
  8.     - protocol: TCP
  9.       name: web
  10.       port: 80
  11.   selector:
  12.     app: whoami1
  14. ---
  15. apiVersion: v1
  16. kind: Service
  17. metadata:
  18.   name: whoami2
  20. spec:
  21.   ports:
  22.     - protocol: TCP
  23.       name: web
  24.       port: 80
  25.   selector:
  26.     app: whoami2

Deployment (to illustrate replicas)

  1. kind: Deployment
  2. apiVersion: apps/v1
  3. metadata:
  4.   namespace: default
  5.   name: whoami1
  6.   labels:
  7.     app: whoami1
  9. spec:
  10.   replicas: 2
  11.   selector:
  12.     matchLabels:
  13.       app: whoami1
  14.   template:
  15.     metadata:
  16.       labels:
  17.         app: whoami1
  18.     spec:
  19.       containers:
  20.         - name: whoami1
  21.           image: traefik/whoami
  22.           ports:
  23.             - name: web
  24.               containerPort: 80
  26. ---
  27. kind: Deployment
  28. apiVersion: apps/v1
  29. metadata:
  30.   namespace: default
  31.   name: whoami2
  32.   labels:
  33.     app: whoami2
  35. spec:
  36.   replicas: 2
  37.   selector:
  38.     matchLabels:
  39.       app: whoami2
  40.   template:
  41.     metadata:
  42.       labels:
  43.         app: whoami2
  44.     spec:
  45.       containers:
  46.         - name: whoami2
  47.           image: traefik/whoami
  48.           ports:
  49.             - name: web
  50.               containerPort: 80

To keep a session open with the same server, the client would then need to specify the two levels within the cookie for each request, e.g. with curl:

  1. curl -H Host:example.com -b "lvl1=default-whoami1-80; lvl2=http://10.42.0.6:80" http://localhost:8000/foo

assuming 10.42.0.6 is the IP address of one of the replicas (a pod then) of the whoami1 service.

Kind IngressRouteTCP

IngressRouteTCP is the CRD implementation of a Traefik TCP router.

Register the IngressRouteTCP kind in the Kubernetes cluster before creating IngressRouteTCP objects.

IngressRouteTCP Attributes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRouteTCP
  3. metadata:
  4.   name: ingressroutetcpfoo
  6. spec:
  7.   entryPoints:                  # [1]
  8.     - footcp
  9.   routes:                       # [2]
  10.   - match: HostSNI(`*`)         # [3]
  11.     services:                   # [4]
  12.     - name: foo                 # [5]
  13.       port: 8080                # [6]
  14.       weight: 10                # [7]
  15.       terminationDelay: 400     # [8]
  16.   tls:                          # [9]
  17.     secretName: supersecret     # [10]
  18.     options:                    # [11]
  19.       name: opt                 # [12]
  20.       namespace: default        # [13]
  21.     certResolver: foo           # [14]
  22.     domains:                    # [15]
  23.     - main: example.net         # [16]
  24.       sans:                     # [17]
  25.       - a.example.net
  26.       - b.example.net
  27.     passthrough: false          # [18]
RefAttributePurpose
[1]entryPointsList of entrypoints names
[2]routesList of routes
[3]routes[n].matchDefines the rule corresponding to an underlying router
[4]routes[n].servicesList of Kubernetes service definitions (See below for ExternalName Service setup)
[5]services[n].nameDefines the name of a Kubernetes service
[6]services[n].portDefines the port of a Kubernetes service
[7]services[n].weightDefines the weight to apply to the server load balancing
[8]services[n].terminationDelaycorresponds to the deadline that the proxy sets, after one of its connected peers indicates it has closed the writing capability of its connection, to close the reading capability as well, hence fully terminating the connection.
It is a duration in milliseconds, defaulting to 100. A negative value means an infinite deadline (i.e. the reading capability is never closed).
[9]tlsDefines TLS certificate configuration
[10]tls.secretNameDefines the secret name used to store the certificate (in the IngressRoute namespace)
[11]tls.optionsDefines the reference to a TLSOption
[12]options.nameDefines the TLSOption name
[13]options.namespaceDefines the TLSOption namespace
[14]tls.certResolverDefines the reference to a CertResolver
[15]tls.domainsList of domains
[16]domains[n].mainDefines the main domain name
[17]domains[n].sansList of SANs (alternative domains)
[18]tls.passthroughIf true, delegates the TLS termination to the backend

Declaring an IngressRouteTCP

IngressRouteTCP

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRouteTCP
  3. metadata:
  4.   name: ingressroutetcpfoo
  6. spec:
  7.   entryPoints:
  8.     - footcp
  9.   routes:
  10.   # Match is the rule corresponding to an underlying router.
  11.   - match: HostSNI(`*`)
  12.     services:
  13.     - name: foo
  14.       port: 8080
  15.       terminationDelay: 400
  16.       weight: 10
  17.     - name: bar
  18.       port: 8081
  19.       terminationDelay: 500
  20.       weight: 10
  21.   tls:
  22.     certResolver: foo
  23.     domains:
  24.     - main: example.net
  25.       sans:
  26.       - a.example.net
  27.       - b.example.net
  28.     options:
  29.       name: opt
  30.       namespace: default
  31.     secretName: supersecret
  32.     passthrough: false

TLSOption

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: TLSOption
  3. metadata:
  4.   name: opt
  5.   namespace: default
  7. spec:
  8.   minVersion: VersionTLS12

Secret

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: supersecret
  6. data:
  7.   tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  8.   tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

Using Kubernetes ExternalName Service

Traefik backends creation needs a port to be set, however Kubernetes ExternalName Service could be defined without any port. Accordingly, Traefik supports defining a port in two ways:

  • only on IngressRouteTCP service
  • on both sides, you’ll be warned if the ports don’t match, and the IngressRouteTCP service port is used

Thus, in case of two sides port definition, Traefik expects a match between ports.

Examples

IngressRouteTCP

  1. ---
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: IngressRouteTCP
  4. metadata:
  5.   name: test.route
  6.   namespace: default
  8. spec:
  9.   entryPoints:
  10.     - foo
  12.   routes:
  13.   - match: HostSNI(`*`)
  14.     kind: Rule
  15.     services:
  16.     - name: external-svc
  17.       port: 80
  19. ---
  20. apiVersion: v1
  21. kind: Service
  22. metadata:
  23.   name: external-svc
  24.   namespace: default
  25. spec:
  26.   externalName: external.domain
  27.   type: ExternalName

ExternalName Service

  1. ---
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: IngressRouteTCP
  4. metadata:
  5.   name: test.route
  6.   namespace: default
  8. spec:
  9.   entryPoints:
  10.     - foo
  12.   routes:
  13.   - match: HostSNI(`*`)
  14.     kind: Rule
  15.     services:
  16.     - name: external-svc
  18. ---
  19. apiVersion: v1
  20. kind: Service
  21. metadata:
  22.   name: external-svc
  23.   namespace: default
  24. spec:
  25.   externalName: external.domain
  26.   type: ExternalName
  27.   ports:
  28.     - port: 80

Both sides

  1. ---
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: IngressRouteTCP
  4. metadata:
  5.   name: test.route
  6.   namespace: default
  8. spec:
  9.   entryPoints:
  10.     - foo
  12.   routes:
  13.   - match: HostSNI(`*`)
  14.     kind: Rule
  15.     services:
  16.     - name: external-svc
  17.       port: 80
  19. ---
  20. apiVersion: v1
  21. kind: Service
  22. metadata:
  23.   name: external-svc
  24.   namespace: default
  25. spec:
  26.   externalName: external.domain
  27.   type: ExternalName
  28.   ports:
  29.     - port: 80

Kind IngressRouteUDP

IngressRouteUDP is the CRD implementation of a Traefik UDP router.

Register the IngressRouteUDP kind in the Kubernetes cluster before creating IngressRouteUDP objects.

IngressRouteUDP Attributes

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRouteUDP
  3. metadata:
  4.   name: ingressrouteudpfoo
  6. spec:
  7.   entryPoints:                  # [1]
  8.     - fooudp
  9.   routes:                       # [2]
  10.   - services:                   # [3]
  11.     - name: foo                 # [4]
  12.       port: 8080                # [5]
  13.       weight: 10                # [6]
RefAttributePurpose
[1]entryPointsList of entrypoints names
[2]routesList of routes
[3]routes[n].servicesList of Kubernetes service definitions
[4]services[n].nameDefines the name of a Kubernetes service
[6]services[n].portDefines the port of a Kubernetes service
[7]services[n].weightDefines the weight to apply to the server load balancing

Declaring an IngressRouteUDP

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRouteUDP
  3. metadata:
  4.   name: ingressrouteudpfoo
  6. spec:
  7.   entryPoints:
  8.     - fooudp
  9.   routes:
  10.   - services:
  11.     - name: foo
  12.       port: 8080
  13.       weight: 10
  14.     - name: bar
  15.       port: 8081
  16.       weight: 10

Kind: TLSOption

TLSOption is the CRD implementation of a Traefik “TLS Option”.

Register the TLSOption kind in the Kubernetes cluster before creating TLSOption objects or referencing TLS options in the IngressRoute / IngressRouteTCP objects.

TLSOption Attributes

TLSOption

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: TLSOption
  3. metadata:
  4.   name: mytlsoption
  5.   namespace: default
  7. spec:
  8.   minVersion: VersionTLS12                      # [1]
  9.   maxVersion: VersionTLS13                      # [1]
  10.   curvePreferences:                             # [3]
  11.     - CurveP521
  12.     - CurveP384
  13.   cipherSuites:                                 # [4]
  14.     - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  15.     - TLS_RSA_WITH_AES_256_GCM_SHA384
  16.   clientAuth:                                   # [5]
  17.     secretNames:                                # [6]
  18.       - secretCA1
  19.       - secretCA2
  20.     clientAuthType: VerifyClientCertIfGiven     # [7]
  21.   sniStrict: true                               # [8]
RefAttributePurpose
[1]minVersionDefines the minimum TLS version that is acceptable
[2]maxVersionDefines the maximum TLS version that is acceptable
[3]cipherSuiteslist of supported cipher suites for TLS versions up to TLS 1.2
[4]curvePreferencesList of the elliptic curves references that will be used in an ECDHE handshake, in preference order
[5]clientAuthdetermines the server’s policy for TLS Client Authentication
[6]clientAuth.secretNameslist of names of the referenced Kubernetes Secrets (in TLSOption namespace)
[7]clientAuth.clientAuthTypedefines the client authentication type to apply. The available values are: NoClientCert, RequestClientCert, VerifyClientCertIfGiven and RequireAndVerifyClientCert
[8]sniStrictif true, Traefik won’t allow connections from clients connections that do not specify a server_name extension

Declaring and referencing a TLSOption

TLSOption

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: TLSOption
  3. metadata:
  4.   name: mytlsoption
  5.   namespace: default
  7. spec:
  8.   minVersion: VersionTLS12
  9.   sniStrict: true
  10.   cipherSuites:
  11.     - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  12.     - TLS_RSA_WITH_AES_256_GCM_SHA384
  13.   clientAuth:
  14.     secretNames:
  15.       - secretCA1
  16.       - secretCA2
  17.     clientAuthType: VerifyClientCertIfGiven

IngressRoute

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: ingressroutebar
  6. spec:
  7.   entryPoints:
  8.     - web
  9.   routes:
  10.   - match: Host(`example.com`) && PathPrefix(`/stripit`)
  11.     kind: Rule
  12.     services:
  13.     - name: whoami
  14.       port: 80
  15.   tls:
  16.     options: 
  17.       name: mytlsoption
  18.       namespace: default

Secrets

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: secretCA1
  5.   namespace: default
  7. data:
  8.   tls.ca: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  10. ---
  11. apiVersion: v1
  12. kind: Secret
  13. metadata:
  14.   name: secretCA2
  15.   namespace: default
  17. data:
  18.   tls.ca: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=

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 (middlewarename@provider) 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.

Kind: TLSStore

TLSStore is the CRD implementation of a Traefik “TLS Store”.

Register the TLSStore kind in the Kubernetes cluster before creating TLSStore objects or referencing TLS stores in the IngressRoute / IngressRouteTCP objects.

Default TLS Store

Traefik currently only uses the TLS Store named “default”. This means that if you have two stores that are named default in different kubernetes namespaces, they may be randomly chosen. For the time being, please only configure one TLSSTore named default.

TLSStore Attributes

TLSStore

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: TLSStore
  3. metadata:
  4.   name: default
  5.   namespace: default
  7. spec:
  8.   defaultCertificate:
  9.     secretName: mySecret                      # [1]
RefAttributePurpose
[1]secretNameThe name of the referenced Kubernetes Secret that holds the default certificate for the store.

Declaring and referencing a TLSStore

TLSStore

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: TLSStore
  3. metadata:
  4.   name: default
  5.   namespace: default
  7. spec:
  8.   defaultCertificate:
  9.     secretName:  supersecret

IngressRoute

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: IngressRoute
  3. metadata:
  4.   name: ingressroutebar
  6. spec:
  7.   entryPoints:
  8.     - web
  9.   routes:
  10.   - match: Host(`example.com`) && PathPrefix(`/stripit`)
  11.     kind: Rule
  12.     services:
  13.     - name: whoami
  14.       port: 80
  15.   tls:
  16.     store: 
  17.       name: default

Secret

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: supersecret
  6. data:
  7.   tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  8.   tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

Further

Also see the full example with Let’s Encrypt.