traefik/docs/content/migration/v2.md

338 lines
6.7 KiB
Markdown
Raw Normal View History

2019-12-12 16:06:05 +00:00
# Migration: Steps needed between the versions
## v2.x to v2.2.2
### Domain fronting
In `v2.2.2` we introduced the ability to avoid [Domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) for [https routers](../routing/routers/index.md#rule) configured with ```Host(`something`)``` but we disabled it for compatibility reasons by default.
Nothing special is required to keep the previous behavior.
However, a new flag is available as a global option to disable domain fronting.
!!! example "Disabling Domain Fronting for All Routers"
```toml tab="File (TOML)"
# Static configuration
[global]
# Disabling domain fronting
insecureSNI = false
```
```yaml tab="File (YAML)"
# Static configuration
global:
# Disabling domain fronting
insecureSNI: false
```
```bash tab="CLI"
# Disabling domain fronting
--global.insecureSNI=false
```
To fine tune the HTTPS routing with Domain Fronting disabled, two new HTTP rules `HostSNI` and `HostHeader` are available.
2019-12-12 16:06:05 +00:00
## v2.0 to v2.1
### Kubernetes CRD
In v2.1, a new Kubernetes CRD called `TraefikService` was added.
While updating an installation to v2.1,
one should apply that CRD, and update the existing `ClusterRole` definition to allow Traefik to use that CRD.
2019-12-12 16:06:05 +00:00
To add that CRD and enhance the permissions, following definitions need to be applied to the cluster.
```yaml tab="TraefikService"
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: traefikservices.traefik.containo.us
spec:
group: traefik.containo.us
version: v1alpha1
names:
kind: TraefikService
plural: traefikservices
singular: traefikservice
scope: Namespaced
```
```yaml tab="ClusterRole"
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1beta1
metadata:
name: traefik-ingress-controller
rules:
- apiGroups:
- ""
resources:
- services
- endpoints
- secrets
verbs:
- get
- list
- watch
- apiGroups:
- extensions
resources:
- ingresses
verbs:
- get
- list
- watch
- apiGroups:
- extensions
resources:
- ingresses/status
verbs:
- update
- apiGroups:
- traefik.containo.us
resources:
- middlewares
2020-03-05 10:48:04 +00:00
- ingressroutes
- traefikservices
- ingressroutetcps
- tlsoptions
2019-12-12 16:06:05 +00:00
verbs:
- get
- list
- watch
2020-03-05 10:48:04 +00:00
```
After having both resources applied, Traefik will work properly.
## v2.1 to v2.2
### Headers middleware: accessControlAllowOrigin
`accessControlAllowOrigin` is deprecated.
This field will be removed in future 2.x releases.
Please configure your allowed origins in `accessControlAllowOriginList` instead.
### Kubernetes CRD
In v2.2, new Kubernetes CRDs called `TLSStore` and `IngressRouteUDP` were added.
While updating an installation to v2.2,
one should apply that CRDs, and update the existing `ClusterRole` definition to allow Traefik to use that CRDs.
To add that CRDs and enhance the permissions, following definitions need to be applied to the cluster.
```yaml tab="TLSStore"
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: tlsstores.traefik.containo.us
spec:
group: traefik.containo.us
version: v1alpha1
names:
kind: TLSStore
plural: tlsstores
singular: tlsstore
scope: Namespaced
```
```yaml tab="IngressRouteUDP"
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: ingressrouteudps.traefik.containo.us
spec:
group: traefik.containo.us
version: v1alpha1
names:
kind: IngressRouteUDP
plural: ingressrouteudps
singular: ingressrouteudp
scope: Namespaced
```
```yaml tab="ClusterRole"
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1beta1
metadata:
name: traefik-ingress-controller
rules:
2019-12-12 16:06:05 +00:00
- apiGroups:
2020-03-05 10:48:04 +00:00
- ""
2019-12-12 16:06:05 +00:00
resources:
2020-03-05 10:48:04 +00:00
- services
- endpoints
- secrets
2019-12-12 16:06:05 +00:00
verbs:
- get
- list
- watch
- apiGroups:
2020-03-05 10:48:04 +00:00
- extensions
2019-12-12 16:06:05 +00:00
resources:
2020-03-05 10:48:04 +00:00
- ingresses
2019-12-12 16:06:05 +00:00
verbs:
- get
- list
- watch
- apiGroups:
2020-03-05 10:48:04 +00:00
- extensions
2019-12-12 16:06:05 +00:00
resources:
2020-03-05 10:48:04 +00:00
- ingresses/status
2019-12-12 16:06:05 +00:00
verbs:
2020-03-05 10:48:04 +00:00
- update
2019-12-12 16:06:05 +00:00
- apiGroups:
- traefik.containo.us
resources:
2020-03-05 10:48:04 +00:00
- middlewares
- ingressroutes
2019-12-12 16:06:05 +00:00
- traefikservices
2020-03-05 10:48:04 +00:00
- ingressroutetcps
- ingressrouteudps
- tlsoptions
- tlsstores
2019-12-12 16:06:05 +00:00
verbs:
- get
- list
- watch
2020-03-05 10:48:04 +00:00
2019-12-12 16:06:05 +00:00
```
After having both resources applied, Traefik will work properly.
### Kubernetes Ingress
To enable HTTPS, it is not sufficient anymore to only rely on a TLS section in the Ingress.
#### Expose an Ingress on 80 and 443
Define the default TLS configuration on the HTTPS entry point.
```yaml tab="Ingress"
kind: Ingress
apiVersion: networking.k8s.io/v1beta1
metadata:
name: example
spec:
tls:
- secretName: myTlsSecret
rules:
- host: example.com
http:
paths:
- path: "/foo"
backend:
serviceName: example-com
servicePort: 80
```
Entry points definition and enable Ingress provider:
```yaml tab="File (YAML)"
# Static configuration
entryPoints:
web:
address: :80
websecure:
address: :443
http:
tls: {}
providers:
kubernetesIngress: {}
```
```toml tab="File (TOML)"
# Static configuration
[entryPoints.web]
address = ":80"
[entryPoints.websecure]
address = ":443"
[entryPoints.websecure.http]
[entryPoints.websecure.http.tls]
[providers.kubernetesIngress]
```
```bash tab="CLI"
# Static configuration
--entryPoints.web.address=:80
--entryPoints.websecure.address=:443
--entryPoints.websecure.http.tls=true
--providers.kubernetesIngress=true
```
#### Use TLS only on one Ingress
Define the TLS restriction with annotations.
```yaml tab="Ingress"
kind: Ingress
apiVersion: networking.k8s.io/v1beta1
metadata:
name: example-tls
annotations:
traefik.ingress.kubernetes.io/router.entrypoints: websecure
traefik.ingress.kubernetes.io/router.tls: "true"
spec:
tls:
- secretName: myTlsSecret
rules:
- host: example.com
http:
paths:
- path: ""
backend:
serviceName: example-com
servicePort: 80
```
Entry points definition and enable Ingress provider:
```yaml tab="File (YAML)"
# Static configuration
entryPoints:
web:
address: :80
websecure:
address: :443
providers:
kubernetesIngress: {}
```
```toml tab="File (TOML)"
# Static configuration
[entryPoints.web]
address = ":80"
[entryPoints.websecure]
address = ":443"
[providers.kubernetesIngress]
```
```bash tab="CLI"
# Static configuration
--entryPoints.web.address=:80
--entryPoints.websecure.address=:443
--providers.kubernetesIngress=true
```