2017-08-26 10:12:44 +00:00
# Kubernetes Ingress Backend
2017-08-25 19:32:33 +00:00
2017-09-11 17:10:04 +00:00
Træfik can be configured to use Kubernetes Ingress as a backend configuration.
2017-11-28 12:36:03 +00:00
See also [Kubernetes user guide ](/user-guide/kubernetes ).
2017-09-11 17:10:04 +00:00
## Configuration
2017-08-25 19:32:33 +00:00
```toml
################################################################
# Kubernetes Ingress configuration backend
################################################################
2017-09-11 17:10:04 +00:00
# Enable Kubernetes Ingress configuration backend.
2017-08-25 19:32:33 +00:00
[kubernetes]
2017-09-11 17:10:04 +00:00
# Kubernetes server endpoint.
2017-08-25 19:32:33 +00:00
#
2017-09-11 17:10:04 +00:00
# Optional for in-cluster configuration, required otherwise.
2017-08-25 19:32:33 +00:00
# Default: empty
#
# endpoint = "http://localhost:8080"
# Bearer token used for the Kubernetes client configuration.
#
# Optional
# Default: empty
#
# token = "my token"
2017-09-11 17:10:04 +00:00
# Path to the certificate authority file.
# Used for the Kubernetes client configuration.
2017-08-25 19:32:33 +00:00
#
# Optional
# Default: empty
#
# certAuthFilePath = "/my/ca.crt"
# Array of namespaces to watch.
#
# Optional
# Default: all namespaces (empty array).
#
# namespaces = ["default", "production"]
2018-01-15 08:40:05 +00:00
# Ingress label selector to filter Ingress objects that should be processed.
2017-08-25 19:32:33 +00:00
#
# Optional
# Default: empty (process all Ingresses)
#
# labelselector = "A and not B"
2017-09-11 17:10:04 +00:00
# Disable PassHost Headers.
#
# Optional
# Default: false
#
# disablePassHostHeaders = true
2017-11-20 01:12:03 +00:00
# Enable PassTLSCert Headers.
#
# Optional
# Default: false
#
# enablePassTLSCert = true
2017-11-26 00:02:03 +00:00
# Override default configuration template.
#
# Optional
# Default: <built-in template>
#
# filename = "kubernetes.tmpl"
2017-08-25 19:32:33 +00:00
```
2017-09-11 17:10:04 +00:00
### `endpoint`
2018-01-15 08:40:05 +00:00
The Kubernetes server endpoint as URL.
2017-09-11 17:10:04 +00:00
2018-01-15 08:40:05 +00:00
When deployed into Kubernetes, Traefik will read the environment variables `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT` to construct the endpoint.
2017-09-11 17:10:04 +00:00
2018-01-15 08:40:05 +00:00
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.
2017-09-11 17:10:04 +00:00
2018-01-15 08:40:05 +00:00
The endpoint may be specified to override the environment variable values inside a cluster.
2017-09-11 17:10:04 +00:00
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.
2018-01-15 08:40:05 +00:00
Specifically, it may be set to the URL used by `kubectl proxy` to connect to a Kubernetes cluster using the granted autentication and authorization of the associated kubeconfig.
2017-09-11 17:10:04 +00:00
### `labelselector`
2018-01-15 08:40:05 +00:00
By default, Traefik processes all Ingress objects in the configured namespaces.
A label selector can be defined to filter on specific Ingress objects only.
2017-09-11 17:10:04 +00:00
See [label-selectors ](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors ) for details.
## Annotations
2018-01-15 08:40:05 +00:00
### General annotations
The following general annotations are applicable on the Ingress object:
2017-08-25 19:32:33 +00:00
2018-01-15 08:40:05 +00:00
- `traefik.frontend.rule.type: PathPrefixStrip`
2017-09-11 17:10:04 +00:00
Override the default frontend rule type. Default: `PathPrefix` .
2017-10-09 12:16:03 +00:00
- `traefik.frontend.priority: "3"`
2017-09-11 17:10:04 +00:00
Override the default frontend rule priority.
2017-12-15 10:48:03 +00:00
- `traefik.frontend.redirect.entryPoint: https` :
2017-11-18 12:50:03 +00:00
Enables Redirect to another entryPoint for that frontend (e.g. HTTPS).
2017-12-15 10:48:03 +00:00
- `traefik.frontend.redirect.regex: ^http://localhost/(.*)` :
Redirect to another URL for that frontend. Must be set with `traefik.frontend.redirect.replacement` .
- `traefik.frontend.redirect.replacement: http://mydomain/$1` :
Redirect to another URL for that frontend. Must be set with `traefik.frontend.redirect.regex` .
2018-01-15 08:40:05 +00:00
- `traefik.frontend.entryPoints: http,https`
2017-11-20 01:12:03 +00:00
Override the default frontend endpoints.
2018-01-15 08:40:05 +00:00
- `traefik.frontend.passTLSCert: true`
2017-11-20 01:12:03 +00:00
Override the default frontend PassTLSCert value. Default: `false` .
2018-01-09 10:56:02 +00:00
- `ingress.kubernetes.io/rewrite-target: /users`
Replaces each matched Ingress path with the specified one, and adds the old path to the `X-Replaced-Path` header.
2018-01-15 08:40:05 +00:00
- `ingress.kubernetes.io/whitelist-source-range: "1.2.3.0/24, fe80::/16"`
A comma-separated list of IP ranges permitted for access. all source IPs are permitted if the list is empty or a single range is ill-formatted.
2017-08-25 19:32:33 +00:00
2017-12-15 10:48:03 +00:00
!!! note
Please note that `traefik.frontend.redirect.regex` and `traefik.frontend.redirect.replacement` do not have to be set if `traefik.frontend.redirect.entryPoint` is defined for the redirection (they will not be used in this case).
2018-01-15 08:40:05 +00:00
The following annotations are applicable on the Service object associated with a particular Ingress object:
2017-12-15 10:48:03 +00:00
2018-01-15 08:40:05 +00:00
- `traefik.backend.loadbalancer.method=drr`
Override the default `wrr` load balancer algorithm.
- `traefik.backend.loadbalancer.stickiness=true`
Enable backend sticky sessions.
- `traefik.backend.loadbalancer.stickiness.cookieName=NAME`
Manually set the cookie name for sticky sessions.
- `traefik.backend.loadbalancer.sticky=true`
Enable backend sticky sessions (DEPRECATED).
- `traefik.backend.circuitbreaker: <expression>`
Set the circuit breaker expression for the backend.
2017-08-25 19:32:33 +00:00
2018-01-15 08:40:05 +00:00
### Security annotations
2017-11-28 12:36:03 +00:00
2018-01-15 08:40:05 +00:00
The following security annotations are applicable on the Ingress object:
2017-11-28 12:36:03 +00:00
2018-01-15 08:40:05 +00:00
| Annotation | Description |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2017-11-28 12:36:03 +00:00
| `ingress.kubernetes.io/allowed-hosts:EXPR` | Provides a list of allowed hosts that requests will be processed. Format: `Host1,Host2` |
2018-01-15 08:40:05 +00:00
| `ingress.kubernetes.io/custom-request-headers:EXPR` | Provides the container with custom request headers that will be appended to each request forwarded to the container. Format: < code > HEADER:value|| HEADER2:value2</ code > |
2017-12-04 10:40:03 +00:00
| `ingress.kubernetes.io/custom-response-headers:EXPR` | Appends the headers to each response returned by the container, before forwarding the response to the client. Format: < code > HEADER:value|| HEADER2:value2</ code > |
2018-01-15 08:40:05 +00:00
| `ingress.kubernetes.io/proxy-headers:EXPR` | Provides a list of headers that the proxied hostname may be stored. Format: `HEADER1,HEADER2` |
2017-11-28 12:36:03 +00:00
| `ingress.kubernetes.io/ssl-redirect:true` | Forces the frontend to redirect to SSL if a non-SSL request is sent. |
| `ingress.kubernetes.io/ssl-temporary-redirect:true` | Forces the frontend to redirect to SSL if a non-SSL request is sent, but by sending a 302 instead of a 301. |
| `ingress.kubernetes.io/ssl-host:HOST` | This setting configures the hostname that redirects will be based on. Default is "", which is the same host as the request. |
2017-12-04 10:40:03 +00:00
| `ingress.kubernetes.io/ssl-proxy-headers:EXPR` | Header combinations that would signify a proper SSL Request (Such as `X-Forwarded-For:https` ). Format: < code > HEADER:value|| HEADER2:value2</ code > |
2017-11-28 12:36:03 +00:00
| `ingress.kubernetes.io/hsts-max-age:315360000` | Sets the max-age of the HSTS header. |
2018-01-29 15:48:05 +00:00
| `ingress.kubernetes.io/hsts-include-subdomains:true` | Adds the IncludeSubdomains section of the STS header. |
2017-11-28 12:36:03 +00:00
| `ingress.kubernetes.io/hsts-preload:true` | Adds the preload flag to the HSTS header. |
| `ingress.kubernetes.io/force-hsts:false` | Adds the STS header to non-SSL requests. |
| `ingress.kubernetes.io/frame-deny:false` | Adds the `X-Frame-Options` header with the value of `DENY` . |
| `ingress.kubernetes.io/custom-frame-options-value:VALUE` | Overrides the `X-Frame-Options` header with the custom value. |
| `ingress.kubernetes.io/content-type-nosniff:true` | Adds the `X-Content-Type-Options` header with the value `nosniff` . |
| `ingress.kubernetes.io/browser-xss-filter:true` | Adds the X-XSS-Protection header with the value `1; mode=block` . |
| `ingress.kubernetes.io/content-security-policy:VALUE` | Adds CSP Header with the custom value. |
| `ingress.kubernetes.io/public-key:VALUE` | Adds pinned HTST public key header. |
| `ingress.kubernetes.io/referrer-policy:VALUE` | Adds referrer policy header. |
| `ingress.kubernetes.io/is-development:false` | This will cause the `AllowedHosts` , `SSLRedirect` , and `STSSeconds` /`STSIncludeSubdomains` options to be ignored during development.< br > When deploying to production, be sure to set this to false. |
2017-08-25 19:32:33 +00:00
### Authentication
2018-01-15 08:40:05 +00:00
Is possible to add additional authentication annotations to the Ingress object.
The source of the authentication is a Secret object that contains the credentials.
2017-08-25 19:32:33 +00:00
- `ingress.kubernetes.io/auth-type` : `basic`
2018-01-15 08:40:05 +00:00
Contains the authentication type. The only permitted type is `basic` .
- `ingress.kubernetes.io/auth-secret` : `mysecret`
Contains the username and password with access to the paths defined in the Ingress object.
2017-08-25 19:32:33 +00:00
2018-01-15 08:40:05 +00:00
The secret must be created in the same namespace as the Ingress object.
2017-08-25 19:32:33 +00:00
2018-01-15 08:40:05 +00:00
The following limitations hold:
2017-08-25 19:32:33 +00:00
2018-01-15 08:40:05 +00:00
- The realm is not configurable; the only supported (and default) value is `traefik` .
- The Secret must contain a single file only.
