• Traefik & Kubernetes
    • Provider Configuration
      • endpoint
      • token
      • certAuthFilePath
      • namespaces
      • labelselector
      • ingressClass
      • throttleDuration
    • Resource Configuration
      • Traefik IngressRoute definition
      • Middleware
      • TLS Option
      • TLS
    • Further

    Traefik & Kubernetes

    The Kubernetes Ingress Controller, The Custom Resource Way.

    Traefik used to support Kubernetes only through the Kubernetes Ingress provider, which is a Kubernetes Ingress controller in the strict sense of the term.

    However, as the community expressed the need to benefit from Traefik features without resorting to (lots of) annotations,we ended up writing a Custom Resource Definition (alias CRD in the following) for an IngressRoute type, defined below, in order to provide a better way to configure access to a Kubernetes cluster.

    Provider Configuration

    endpoint

    Optional, Default=empty

    1. [providers.kubernetesCRD]
    2.   endpoint = "http://localhost:8080"
    3.   # ...
    1. providers:
    2.   kubernetesCRD:
    3.     endpoint = "http://localhost:8080"
    4.     # ...
    1. --providers.kubernetescrd.endpoint="http://localhost:8080"

    The Kubernetes server endpoint as URL.

    When deployed into Kubernetes, Traefik will read the environment variables KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT or KUBECONFIG to construct the endpoint.

    The access token will be looked up in /var/run/secrets/kubernetes.io/serviceaccount/token and the SSL CA certificate in /var/run/secrets/kubernetes.io/serviceaccount/ca.crt.Both are provided mounted automatically when deployed inside Kubernetes.

    The endpoint may be specified to override the environment variable values inside a cluster.

    When the environment variables are not found, Traefik will try to connect to the Kubernetes API server with an external-cluster client.In this case, the endpoint is required.Specifically, it may be set to the URL used by kubectl proxy to connect to a Kubernetes cluster using the granted authentication and authorization of the associated kubeconfig.

    token

    Optional, Default=empty

    1. [providers.kubernetesCRD]
    2.   token = "mytoken"
    3.   # ...
    1. providers:
    2.   kubernetesCRD:
    3.     token = "mytoken"
    4.     # ...
    1. --providers.kubernetescrd.token="mytoken"

    Bearer token used for the Kubernetes client configuration.

    certAuthFilePath

    Optional, Default=empty

    1. [providers.kubernetesCRD]
    2.   certAuthFilePath = "/my/ca.crt"
    3.   # ...
    1. providers:
    2.   kubernetesCRD:
    3.     certAuthFilePath: "/my/ca.crt"
    4.     # ...
    1. --providers.kubernetescrd.certauthfilepath="/my/ca.crt"

    Path to the certificate authority file.Used for the Kubernetes client configuration.

    namespaces

    Optional, Default: all namespaces (empty array)

    1. [providers.kubernetesCRD]
    2.   namespaces = ["default", "production"]
    3.   # ...
    1. providers:
    2.   kubernetesCRD:
    3.     namespaces:
    4.     - "default"
    5.     - "production"
    6.     # ...
    1. --providers.kubernetescrd.namespaces="default,production"

    Array of namespaces to watch.

    labelselector

    Optional,Default: empty (process all Ingresses)

    1. [providers.kubernetesCRD]
    2.   labelselector = "A and not B"
    3.   # ...
    1. providers:
    2.   kubernetesCRD:
    3.     labelselector: "A and not B"
    4.     # ...
    1. --providers.kubernetescrd.labelselector="A and not B"

    By default, Traefik processes all Ingress objects in the configured namespaces.A label selector can be defined to filter on specific Ingress objects only.

    See label-selectors for details.

    ingressClass

    Optional, Default: empty

    1. [providers.kubernetesCRD]
    2.   ingressClass = "traefik-internal"
    3.   # ...
    1. providers:
    2.   kubernetesCRD:
    3.     ingressClass: "traefik-internal"
    4.     # ...
    1. --providers.kubernetescrd.ingressclass="traefik-internal"

    Value of kubernetes.io/ingress.class annotation that identifies Ingress objects to be processed.

    If the parameter is non-empty, only Ingresses containing an annotation with the same value are processed.Otherwise, Ingresses missing the annotation, having an empty value, or the value traefik are processed.

    throttleDuration

    Optional, Default: 0 (no throttling)

    1. [providers.kubernetesCRD]
    2.   throttleDuration = "10s"
    3.   # ...
    1. providers:
    2.   kubernetesCRD:
    3.     throttleDuration: "10s"
    4.     # ...
    1. --providers.kubernetescrd.throttleDuration="10s"

    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.

    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.     - web
    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.