traefik/docs/content/providers/kubernetes-ingress.md

502 lines
13 KiB
Markdown
Raw Normal View History

---
title: "Traefik Kubernetes Ingress Documentation"
description: "Understand the requirements, routing configuration, and how to set up Traefik Proxy as your Kubernetes Ingress Controller. Read the technical documentation."
---
# Traefik & Kubernetes
The Kubernetes Ingress Controller.
{: .subtitle }
The Traefik Kubernetes Ingress provider is a Kubernetes Ingress controller; that is to say,
it manages access to cluster services by supporting the [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) specification.
## Requirements
Traefik supports `1.14+` Kubernetes clusters.
## Routing Configuration
See the dedicated section in [routing](../routing/providers/kubernetes-ingress.md).
## Enabling and Using the Provider
2021-02-11 18:04:03 +00:00
You can enable the provider in the static configuration:
```yaml tab="File (YAML)"
providers:
kubernetesIngress: {}
```
```toml tab="File (TOML)"
[providers.kubernetesIngress]
```
```bash tab="CLI"
2019-07-22 07:58:04 +00:00
--providers.kubernetesingress=true
```
The provider then watches for incoming ingresses events, such as the example below,
and derives the corresponding dynamic configuration from it,
2021-02-11 18:04:03 +00:00
which in turn creates the resulting routers, services, handlers, etc.
```yaml tab="Ingress"
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: foo
namespace: production
spec:
rules:
2020-03-13 21:50:05 +00:00
- host: example.net
2019-09-23 15:00:06 +00:00
http:
paths:
- path: /bar
pathType: Exact
2019-09-23 15:00:06 +00:00
backend:
service:
name: service1
port:
number: 80
2019-09-23 15:00:06 +00:00
- path: /foo
pathType: Exact
2019-09-23 15:00:06 +00:00
backend:
service:
name: service1
port:
number: 80
```
```yaml tab="Ingress v1beta1 (deprecated)"
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: foo
namespace: production
spec:
rules:
- host: example.net
http:
paths:
- path: /bar
backend:
serviceName: service1
servicePort: 80
- path: /foo
backend:
serviceName: service1
servicePort: 80
```
## LetsEncrypt Support with the Ingress Provider
2020-02-17 10:04:04 +00:00
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.
2021-02-11 18:04:03 +00:00
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](https://doc.traefik.io/traefik/v1.7/configuration/acme/#storage) to attempt to achieve this,
2021-02-11 18:04:03 +00:00
but due to sub-optimal performance that feature was dropped in 2.0.
2021-02-11 18:04:03 +00:00
If you need Let's Encrypt with high availability in a Kubernetes environment,
we recommend using [Traefik Enterprise](https://traefik.io/traefik-enterprise/) which includes distributed Let's Encrypt as a supported feature.
2021-02-11 18:04:03 +00:00
If you want to keep using Traefik Proxy,
LetsEncrypt HA can be achieved by using a Certificate Controller such as [Cert-Manager](https://cert-manager.io/docs/).
2020-02-17 10:04:04 +00:00
When using Cert-Manager to manage certificates,
2021-02-11 18:04:03 +00:00
it creates secrets in your namespaces that can be referenced as TLS secrets in your [ingress objects](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls).
2019-09-23 12:32:04 +00:00
## Provider Configuration
### `endpoint`
2021-02-11 18:04:03 +00:00
_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.
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
2020-09-23 09:38:03 +00:00
endpoint: "http://localhost:8080"
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress]
endpoint = "http://localhost:8080"
# ...
```
```bash tab="CLI"
--providers.kubernetesingress.endpoint=http://localhost:8080
```
### `token`
2021-02-11 18:04:03 +00:00
_Optional, Default=""_
Bearer token used for the Kubernetes client configuration.
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
2020-09-23 09:38:03 +00:00
token: "mytoken"
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress]
token = "mytoken"
# ...
```
```bash tab="CLI"
--providers.kubernetesingress.token=mytoken
```
### `certAuthFilePath`
2021-02-11 18:04:03 +00:00
_Optional, Default=""_
Path to the certificate authority file.
Used for the Kubernetes client configuration.
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
certAuthFilePath: "/my/ca.crt"
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress]
certAuthFilePath = "/my/ca.crt"
# ...
```
```bash tab="CLI"
--providers.kubernetesingress.certauthfilepath=/my/ca.crt
```
### `namespaces`
2021-02-11 18:04:03 +00:00
_Optional, Default: []_
Array of namespaces to watch.
If left empty, watches all namespaces if the value of `namespaces`.
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
namespaces:
2019-09-23 15:00:06 +00:00
- "default"
- "production"
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress]
namespaces = ["default", "production"]
# ...
```
```bash tab="CLI"
--providers.kubernetesingress.namespaces=default,production
```
### `labelSelector`
2021-02-11 18:04:03 +00:00
_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](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors) for details.
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
labelSelector: "app=traefik"
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress]
labelSelector = "app=traefik"
# ...
```
```bash tab="CLI"
--providers.kubernetesingress.labelselector="app=traefik"
```
### `ingressClass`
2021-02-11 18:04:03 +00:00
_Optional, Default: ""_
Value of `kubernetes.io/ingress.class` annotation that identifies Ingress objects to be processed.
2021-02-11 18:04:03 +00:00
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.
??? info "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.
2021-02-11 18:04:03 +00:00
2020-09-01 08:18:03 +00:00
Please see [this article](https://kubernetes.io/blog/2020/04/02/improvements-to-the-ingress-api-in-kubernetes-1.18/) for more information or the example below.
```yaml tab="IngressClass"
apiVersion: networking.k8s.io/v1beta1
kind: IngressClass
2021-02-11 18:04:03 +00:00
metadata:
2020-09-01 08:18:03 +00:00
name: traefik-lb
2021-02-11 18:04:03 +00:00
spec:
2020-09-01 08:18:03 +00:00
controller: traefik.io/ingress-controller
```
2021-02-11 18:04:03 +00:00
2020-09-01 08:18:03 +00:00
```yaml tab="Ingress"
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
2020-09-01 08:18:03 +00:00
metadata:
name: example-ingress
2020-09-01 08:18:03 +00:00
spec:
ingressClassName: traefik-lb
2020-09-01 08:18:03 +00:00
rules:
- host: "*.example.com"
http:
paths:
- path: /example
2020-09-01 08:18:03 +00:00
backend:
serviceName: example-service
2020-09-01 08:18:03 +00:00
servicePort: 80
```
??? info "Kubernetes 1.19+"
If the Kubernetes cluster version is 1.19+,
prefer using the `networking.k8s.io/v1` [apiVersion](https://v1-19.docs.kubernetes.io/docs/setup/release/notes/#api-change) of `Ingress` and `IngressClass`.
```yaml tab="IngressClass"
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: traefik-lb
spec:
controller: traefik.io/ingress-controller
```
```yaml tab="Ingress"
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
```
2021-02-11 18:04:03 +00:00
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
ingressClass: "traefik-internal"
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress]
ingressClass = "traefik-internal"
# ...
```
2021-02-11 18:04:03 +00:00
```bash tab="CLI"
--providers.kubernetesingress.ingressclass=traefik-internal
```
### `ingressEndpoint`
#### `hostname`
2021-02-11 18:04:03 +00:00
_Optional, Default: ""_
Hostname used for Kubernetes Ingress endpoints.
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
ingressEndpoint:
2020-03-13 21:50:05 +00:00
hostname: "example.net"
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress.ingressEndpoint]
hostname = "example.net"
# ...
```
```bash tab="CLI"
2020-03-13 21:50:05 +00:00
--providers.kubernetesingress.ingressendpoint.hostname=example.net
```
#### `ip`
2021-02-11 18:04:03 +00:00
_Optional, Default: ""_
IP used for Kubernetes Ingress endpoints.
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
ingressEndpoint:
ip: "1.2.3.4"
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress.ingressEndpoint]
ip = "1.2.3.4"
# ...
```
```bash tab="CLI"
--providers.kubernetesingress.ingressendpoint.ip=1.2.3.4
```
#### `publishedService`
2021-02-11 18:04:03 +00:00
_Optional, Default: ""_
Published Kubernetes Service to copy status from.
Format: `namespace/servicename`.
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
ingressEndpoint:
publishedService: "namespace/foo-service"
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress.ingressEndpoint]
publishedService = "namespace/foo-service"
# ...
```
```bash tab="CLI"
--providers.kubernetesingress.ingressendpoint.publishedservice=namespace/foo-service
```
2019-08-30 10:16:04 +00:00
### `throttleDuration`
2021-02-11 18:04:03 +00:00
_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](https://golang.org/pkg/time/#ParseDuration).
2019-08-30 10:16:04 +00:00
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
throttleDuration: "10s"
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress]
throttleDuration = "10s"
# ...
```
2019-08-30 10:16:04 +00:00
```bash tab="CLI"
--providers.kubernetesingress.throttleDuration=10s
2019-08-30 10:16:04 +00:00
```
### `allowEmptyServices`
_Optional, Default: false
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
allowEmptyServices: true
# ...
```
2021-06-22 12:05:57 +00:00
```toml tab="File (TOML)"
[providers.kubernetesIngress]
allowEmptyServices = true
# ...
```
```bash tab="CLI"
--providers.kubernetesingress.allowEmptyServices=true
```
Allow the creation of services if there are no endpoints available.
This results in `503` http responses instead of `404`.
### `allowExternalNameServices`
_Optional, Default: false_
If the parameter is set to `true`, Ingresses are able to reference ExternalName services.
```yaml tab="File (YAML)"
providers:
kubernetesIngress:
allowExternalNameServices: true
# ...
```
```toml tab="File (TOML)"
[providers.kubernetesIngress]
allowExternalNameServices = true
# ...
```
```bash tab="CLI"
--providers.kubernetesingress.allowexternalnameservices=true
```
### Further
2021-02-11 18:04:03 +00:00
To learn more about the various aspects of the Ingress specification that Traefik supports,
2022-01-24 16:58:04 +00:00
many examples of Ingresses definitions are located in the test [examples](https://github.com/traefik/traefik/tree/v2.6/pkg/provider/kubernetes/ingress/fixtures) of the Traefik repository.