Traefik & Kubernetes

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

    All Steps for a Successful Deployment

    • Add/update all the Traefik resources definitions
    • Add/update the for the Traefik custom resources
    • Use Helm Chart or use a custom Traefik Deployment
      • Enable the kubernetesCRD provider
      • Apply the needed kubernetesCRD provider
    • Add all needed traefik custom resources

    Initializing Resource Definition and RBAC

    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.     resources:
    20.       - ingresses
    21.     verbs:
    22.       - get
    23.       - list
    24.       - watch
    25.   - apiGroups:
    26.     resources:
    27.       - ingresses/status
    28.     verbs:
    29.       - update
    30.   - apiGroups:
    31.       - traefik.containo.us
    32.     resources:
    33.       - middlewares
    34.       - ingressroutes
    35.       - traefikservices
    36.       - ingressroutetcps
    37.       - ingressrouteudps
    38.       - tlsoptions
    40.     verbs:
    41.       - get
    42.       - list
    43.       - watch
    45. ---
    46. kind: ClusterRoleBinding
    47. apiVersion: rbac.authorization.k8s.io/v1beta1
    48. metadata:
    49.   name: traefik-ingress-controller
    51. roleRef:
    52.   apiGroup: rbac.authorization.k8s.io
    53.   kind: ClusterRole
    54.   name: traefik-ingress-controller
    55. subjects:
    56.   - kind: ServiceAccount
    57.     name: traefik-ingress-controller
    58.     namespace: default

    When using KubernetesCRD as a provider, Traefik uses to retrieve its routing configuration. Traefik Custom Resource Definitions are a Kubernetes implementation of the Traefik concepts. The main particularities are:

    • The usage of name and namespace to refer to another Kubernetes resource.
    • The usage of secret for sensible data like:
      • TLS certificate.
      • Authentication data.
    • The structure of the configuration.
    • The obligation to declare all the .

    The Traefik CRD are building blocks which you can assemble according to your needs. See the list of CRDs in the dedicated routing section.

    By design, Traefik is a stateless application, meaning that it only derives its configuration from the environment it runs in, without additional configuration. For this reason, users can run multiple instances of Traefik at the same time to achieve HA, as is a common pattern in the kubernetes ecosystem.

    When using a single instance of Traefik with LetsEncrypt, no issues should be encountered, however this could be a single point of failure. Unfortunately, it is not possible to run multiple instances of Traefik 2.0 with LetsEncrypt enabled, because there is no way to ensure that the correct instance of Traefik will receive the challenge request, and subsequent responses. Previous versions of Traefik used a to attempt to achieve this, but due to sub-optimal performance was dropped as a feature in 2.0.

    If you require LetsEncrypt with HA in a kubernetes environment, we recommend using TraefikEE where distributed LetsEncrypt is a supported feature.

    Optional, Default=empty

    1. [providers.kubernetesCRD]
    2.   endpoint = "http://localhost:8080"
    3.   # ...
    1. providers:
    2.     endpoint = "http://localhost:8080"
    3.     # ...
    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.   # ...
    2.   kubernetesCRD:
    3.     token = "mytoken"
    4.     # ...

    Bearer token used for the Kubernetes client configuration.

    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

    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.

    Optional,Default: empty (process all resources)

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

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

    See 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 resource objects to be processed.

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

    Optional, Default: 0 (no throttling)

    1. [providers.kubernetesCRD]
    2.   throttleDuration = "10s"
    1. --providers.kubernetescrd.throttleDuration=10s