Traefik & Kubernetes

    The Traefik Kubernetes Ingress provider is a Kubernetes Ingress controller; that is to say, it manages access to cluster services by supporting the Ingress specification.

    Traefik supports 1.14+ Kubernetes clusters.

    See the dedicated section in .

    You can enable the provider in the static configuration:

    File (YAML)

    File (TOML)

    1. [providers.kubernetesIngress]

    CLI

    1. --providers.kubernetesingress=true

    The provider then watches for incoming ingresses events, such as the example below, and derives the corresponding dynamic configuration from it, which in turn creates the resulting routers, services, handlers, etc.

    Ingress

    1. apiVersion: networking.k8s.io/v1
    2. kind: Ingress
    3. metadata:
    4.   name: foo
    5.   namespace: production
    7. spec:
    8.   rules:
    9.     - host: example.net
    10.       http:
    11.         paths:
    12.           - path: /bar
    13.             pathType: Exact
    14.             backend:
    15.               service:
    16.                 name:  service1
    17.                 port:
    18.                   number: 80
    19.           - path: /foo
    20.             pathType: Exact
    21.             backend:
    22.               service:
    23.                 name:  service1
    24.                 port:
    25.                   number: 80

    Ingress v1beta1 (deprecated)

    1. apiVersion: networking.k8s.io/v1beta1
    2. kind: Ingress
    3. metadata:
    4.   name: foo
    5.   namespace: production
    7. spec:
    8.   rules:
    9.     - host: example.net
    10.       http:
    11.         paths:
    12.           - path: /bar
    13.             backend:
    14.               serviceName: service1
    15.               servicePort: 80
    16.           - path: /foo
    17.             backend:
    18.               serviceName: service1
    19.               servicePort: 80

    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 Proxy with Let’s Encrypt, you should encounter no issues. However, this could be a single point of failure. Unfortunately, it is not possible to run multiple instances of Traefik 2.0 with Let’s Encrypt enabled, because there is no way to ensure that the correct instance of Traefik receives the challenge request, and subsequent responses. Previous versions of Traefik used a KV store to attempt to achieve this, but due to sub-optimal performance that feature was dropped in 2.0.

    If you need Let’s Encrypt with high availability in a Kubernetes environment, we recommend using which includes distributed Let’s Encrypt as a supported feature.

    If you want to keep using Traefik Proxy, LetsEncrypt HA can be achieved by using a Certificate Controller such as Cert-Manager. When using Cert-Manager to manage certificates, it creates secrets in your namespaces that can be referenced as TLS secrets in your .

    Optional, Default=””

    The Kubernetes server endpoint URL.

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

    The access token is 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 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 tries 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.

    File (YAML)

    1. providers:
    2.   kubernetesIngress:
    3.     # ...

    File (TOML)

    1. [providers.kubernetesIngress]
    2.   endpoint = "http://localhost:8080"
    3.   # ...

    CLI

    1. --providers.kubernetesingress.endpoint=http://localhost:8080

    token

    Optional, Default=””

    Bearer token used for the Kubernetes client configuration.

    File (YAML)

    1. providers:
    3.     token: "mytoken"
    4.     # ...

    File (TOML)

    1. [providers.kubernetesIngress]
    2.   token = "mytoken"
    3.   # ...

    CLI

    1. --providers.kubernetesingress.token=mytoken

    certAuthFilePath

    Optional, Default=””

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

    File (YAML)

    1. providers:
    2.   kubernetesIngress:
    3.     certAuthFilePath: "/my/ca.crt"
    4.     # ...
    1. [providers.kubernetesIngress]
    2.   certAuthFilePath = "/my/ca.crt"
    3.   # ...

    CLI

    1. --providers.kubernetesingress.certauthfilepath=/my/ca.crt

    Optional, Default: []

    Array of namespaces to watch. If left empty, Traefik watches all namespaces.

    File (YAML)

    1. providers:
    2.   kubernetesIngress:
    3.     namespaces:
    4.       - "default"
    5.       - "production"
    6.     # ...

    File (TOML)

    CLI

    1. --providers.kubernetesingress.namespaces=default,production

    labelSelector

    Optional, Default: “”

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

    See label-selectors for details.

    File (YAML)

    1. providers:
    2.   kubernetesIngress:
    3.     labelSelector: "app=traefik"
    4.     # ...

    File (TOML)

    1. [providers.kubernetesIngress]
    2.   labelSelector = "app=traefik"
    3.   # ...

    CLI

    1. --providers.kubernetesingress.labelselector="app=traefik"

    ingressClass

    Optional, Default: “”

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

    If the parameter is set, 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.

    Kubernetes 1.18+

    If the Kubernetes cluster version is 1.18+, the new IngressClass resource can be leveraged to identify Ingress objects that should be processed. In that case, Traefik will look for an IngressClass in the cluster with the controller value equal to traefik.io/ingress-controller.

    In addition to the controller value matching mechanism, the property ingressClass (if set) will be used to select IngressClasses by applying a strict matching on their name.

    Please see this article for more information or the example below.

    IngressClass

    1. apiVersion: networking.k8s.io/v1beta1
    2. kind: IngressClass
    3. metadata:
    4.   name: traefik-lb
    5. spec:
    6.   controller: traefik.io/ingress-controller

    Ingress

    1. apiVersion: networking.k8s.io/v1beta1
    2. kind: Ingress
    3. metadata:
    4.   name: example-ingress
    5. spec:
    6.   ingressClassName: traefik-lb
    7.   rules:
    8.   - host: "*.example.com"
    9.     http:
    10.       paths:
    11.       - path: /example
    12.         backend:
    13.           serviceName: example-service
    14.           servicePort: 80

    Kubernetes 1.19+

    If the Kubernetes cluster version is 1.19+, prefer using the networking.k8s.io/v1 of Ingress and IngressClass.

    IngressClass

    1. apiVersion: networking.k8s.io/v1
    2. kind: IngressClass
    3. metadata:
    4.   name: traefik-lb
    5. spec:
    6.   controller: traefik.io/ingress-controller

    Ingress

    1. apiVersion: networking.k8s.io/v1
    2. kind: Ingress
    3. metadata:
    4.   name: example-ingress
    5. spec:
    6.   rules:
    7.   - host: "*.example.com"
    8.     http:
    10.       - path: /example
    11.         pathType: Exact
    12.         backend:
    13.           service:
    14.             name: example-service
    15.             port:
    16.                 number: 80

    File (YAML)

    1. providers:
    2.   kubernetesIngress:
    3.     ingressClass: "traefik-internal"
    4.     # ...

    File (TOML)

    1. [providers.kubernetesIngress]
    2.   ingressClass = "traefik-internal"
    3.   # ...

    CLI

    1. --providers.kubernetesingress.ingressclass=traefik-internal

    hostname

    Optional, Default: “”

    Hostname used for Kubernetes Ingress endpoints.

    File (YAML)

    1. providers:
    2.   kubernetesIngress:
    3.     ingressEndpoint:
    4.       hostname: "example.net"
    5.     # ...
    1. [providers.kubernetesIngress.ingressEndpoint]
    2.   hostname = "example.net"
    3.   # ...

    CLI

    1. --providers.kubernetesingress.ingressendpoint.hostname=example.net

    ip

    Optional, Default: “”

    This IP will get copied to Ingress status.loadbalancer.ip, and currently only supports one IP value (IPv4 or IPv6).

    File (YAML)

    File (TOML)

    1. [providers.kubernetesIngress.ingressEndpoint]
    2.   ip = "1.2.3.4"
    3.   # ...

    CLI

    1. --providers.kubernetesingress.ingressendpoint.ip=1.2.3.4

    publishedService

    Optional, Default: “”

    The Kubernetes service to copy status from. When using third parties tools like External-DNS, this option can be used to copy the service loadbalancer.status (containing the service’s endpoints IPs) to the ingresses.

    Format: namespace/servicename.

    File (YAML)

    1. providers:
    2.   kubernetesIngress:
    3.     ingressEndpoint:
    4.       publishedService: "namespace/foo-service"
    5.     # ...

    File (TOML)

    1. [providers.kubernetesIngress.ingressEndpoint]
    2.   publishedService = "namespace/foo-service"
    3.   # ...

    CLI

    1. --providers.kubernetesingress.ingressendpoint.publishedservice=namespace/foo-service

    throttleDuration

    Optional, Default: 0

    The throttleDuration option defines how often the provider is allowed to handle events from Kubernetes. This prevents a Kubernetes cluster that updates many times per second from continuously changing your Traefik configuration.

    If left empty, the provider does not apply any throttling and does not drop any Kubernetes events.

    The value of throttleDuration should be provided in seconds or as a valid duration format, see .

    File (YAML)

    1. providers:
    2.   kubernetesIngress:
    3.     throttleDuration: "10s"
    4.     # ...

    File (TOML)

    1. [providers.kubernetesIngress]
    2.   throttleDuration = "10s"
    3.   # ...

    CLI

    1. --providers.kubernetesingress.throttleDuration=10s

    allowEmptyServices

    Optional, Default: false

    If the parameter is set to true, it allows the creation of an empty if the targeted Kubernetes service has no endpoints available. This results in 503 HTTP responses instead of 404 ones.

    File (YAML)

    1. providers:
    2.   kubernetesIngress:
    3.     allowEmptyServices: true
    4.     # ...

    File (TOML)

    1. [providers.kubernetesIngress]
    2.   allowEmptyServices = true
    3.   # ...

    CLI

    1. --providers.kubernetesingress.allowEmptyServices=true

    Optional, Default: false

    If the parameter is set to true, Ingresses are able to reference ExternalName services.

    File (YAML)

    1. providers:
    2.   kubernetesIngress:
    3.     allowExternalNameServices: true
    4.     # ...

    File (TOML)

    1. [providers.kubernetesIngress]
    2.   allowExternalNameServices = true
    3.   # ...

    CLI

    Further

    To learn more about the various aspects of the Ingress specification that Traefik supports, many examples of Ingresses definitions are located in the test examples of the Traefik repository.

    Using Traefik for Business Applications?

    Traefik Enterprise simplifies the discovery, security, and deployment of APIs and microservices across any environment. See it in action in .