Traefik & Kubernetes¶
The Kubernetes Ingress Controller.
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.
Requirements¶
Traefik follows the Kubernetes support policy, and supports at least the latest three minor versions of Kubernetes. General functionality cannot be guaranteed for older versions.
Routing Configuration¶
See the dedicated section in routing.
Enabling and Using the Provider¶
You can enable the provider in the static configuration:
providers:
kubernetesIngress: {}
[providers.kubernetesIngress]
--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.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: foo
namespace: production
spec:
rules:
- host: example.net
http:
paths:
- path: /bar
pathType: Exact
backend:
service:
name: service1
port:
number: 80
- path: /foo
pathType: Exact
backend:
service:
name: service1
port:
number: 80
LetsEncrypt Support with the Ingress Provider¶
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. Early versions (v1.x) 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 Traefik Enterprise 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 ingress objects.
Provider Configuration¶
endpoint
¶
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.
providers:
kubernetesIngress:
endpoint: "http://localhost:8080"
# ...
[providers.kubernetesIngress]
endpoint = "http://localhost:8080"
# ...
--providers.kubernetesingress.endpoint=http://localhost:8080
token
¶
Optional, Default=""
Bearer token used for the Kubernetes client configuration.
providers:
kubernetesIngress:
token: "mytoken"
# ...
[providers.kubernetesIngress]
token = "mytoken"
# ...
--providers.kubernetesingress.token=mytoken
certAuthFilePath
¶
Optional, Default=""
Path to the certificate authority file. Used for the Kubernetes client configuration.
providers:
kubernetesIngress:
certAuthFilePath: "/my/ca.crt"
# ...
[providers.kubernetesIngress]
certAuthFilePath = "/my/ca.crt"
# ...
--providers.kubernetesingress.certauthfilepath=/my/ca.crt
namespaces
¶
Optional, Default: []
Array of namespaces to watch. If left empty, Traefik watches all namespaces.
providers:
kubernetesIngress:
namespaces:
- "default"
- "production"
# ...
[providers.kubernetesIngress]
namespaces = ["default", "production"]
# ...
--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.
providers:
kubernetesIngress:
labelSelector: "app=traefik"
# ...
[providers.kubernetesIngress]
labelSelector = "app=traefik"
# ...
--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.
Example
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: traefik-lb
spec:
controller: traefik.io/ingress-controller
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
spec:
ingressClassName: traefik-lb
rules:
- host: "*.example.com"
http:
paths:
- path: /example
pathType: Exact
backend:
service:
name: example-service
port:
number: 80
providers:
kubernetesIngress:
ingressClass: "traefik-internal"
# ...
[providers.kubernetesIngress]
ingressClass = "traefik-internal"
# ...
--providers.kubernetesingress.ingressclass=traefik-internal
disableIngressClassLookup
¶
Optional, Default: false
Deprecated
The Kubernetes Ingress provider option disableIngressClassLookup
has been deprecated in v3.1, and will be removed in the next major version.
Please use the disableClusterScopeResources
option instead.
If the parameter is set to true
,
Traefik will not discover IngressClasses in the cluster.
By doing so, it alleviates the requirement of giving Traefik the rights to look IngressClasses up.
Furthermore, when this option is set to true
,
Traefik is not able to handle Ingresses with IngressClass references,
therefore such Ingresses will be ignored.
Please note that annotations are not affected by this option.
providers:
kubernetesIngress:
disableIngressClassLookup: true
# ...
[providers.kubernetesIngress]
disableIngressClassLookup = true
# ...
--providers.kubernetesingress.disableingressclasslookup=true
disableClusterScopeResources
¶
Optional, Default: false
When this parameter is set to true
,
Traefik will not discover cluster scope resources (IngressClass
and Nodes
).
By doing so, it alleviates the requirement of giving Traefik the rights to look up for cluster resources.
Furthermore, Traefik will not handle Ingresses with IngressClass references, therefore such Ingresses will be ignored (please note that annotations are not affected by this option).
This will also prevent from using the NodePortLB
options on services.
providers:
kubernetesIngress:
disableClusterScopeResources: true
# ...
[providers.kubernetesIngress]
disableClusterScopeResources = true
# ...
--providers.kubernetesingress.disableClusterScopeResources=true
ingressEndpoint
¶
hostname
¶
Optional, Default: ""
Hostname used for Kubernetes Ingress endpoints.
providers:
kubernetesIngress:
ingressEndpoint:
hostname: "example.net"
# ...
[providers.kubernetesIngress.ingressEndpoint]
hostname = "example.net"
# ...
--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).
providers:
kubernetesIngress:
ingressEndpoint:
ip: "1.2.3.4"
# ...
[providers.kubernetesIngress.ingressEndpoint]
ip = "1.2.3.4"
# ...
--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
.
providers:
kubernetesIngress:
ingressEndpoint:
publishedService: "namespace/foo-service"
# ...
[providers.kubernetesIngress.ingressEndpoint]
publishedService = "namespace/foo-service"
# ...
--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 time.ParseDuration.
providers:
kubernetesIngress:
throttleDuration: "10s"
# ...
[providers.kubernetesIngress]
throttleDuration = "10s"
# ...
--providers.kubernetesingress.throttleDuration=10s
allowEmptyServices
¶
Optional, Default: false
If the parameter is set to true
,
it allows the creation of an empty servers load balancer if the targeted Kubernetes service has no endpoints available.
This results in 503
HTTP responses instead of 404
ones.
providers:
kubernetesIngress:
allowEmptyServices: true
# ...
[providers.kubernetesIngress]
allowEmptyServices = true
# ...
--providers.kubernetesingress.allowEmptyServices=true
allowExternalNameServices
¶
Optional, Default: false
If the parameter is set to true
,
Ingresses are able to reference ExternalName services.
providers:
kubernetesIngress:
allowExternalNameServices: true
# ...
[providers.kubernetesIngress]
allowExternalNameServices = true
# ...
--providers.kubernetesingress.allowexternalnameservices=true
nativeLBByDefault
¶
Optional, Default: false
Defines whether to use Native Kubernetes load-balancing mode by default.
For more information, please check out the traefik.ingress.kubernetes.io/service.nativelb
service annotation documentation.
providers:
kubernetesIngress:
nativeLBByDefault: true
# ...
[providers.kubernetesIngress]
nativeLBByDefault = true
# ...
--providers.kubernetesingress.nativeLBByDefault=true
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 OSS in Production? Consider Adding Advanced Capabilities.
Add API Gateway or API Management capabilities seamlessly to your existing Traefik deployments. No rip and replace. No learning curve.