From d0f8c1834d2bbf4a77d35a0bb514a6498b364d2c Mon Sep 17 00:00:00 2001 From: Ludovic Fernandez Date: Mon, 9 Mar 2020 13:22:06 +0100 Subject: [PATCH] Update migration documentation --- docs/content/https/acme.md | 2 +- docs/content/migration/v1-to-v2.md | 291 ++++++++--------------------- 2 files changed, 82 insertions(+), 211 deletions(-) diff --git a/docs/content/https/acme.md b/docs/content/https/acme.md index b4c4aa50e..46da105b8 100644 --- a/docs/content/https/acme.md +++ b/docs/content/https/acme.md @@ -319,7 +319,7 @@ For example, `CF_API_EMAIL_FILE=/run/secrets/traefik_cf-api-email` could be used | [Linode](https://www.linode.com) | `linode` | `LINODE_API_KEY` | [Additional configuration](https://go-acme.github.io/lego/dns/linode) | | [Linode v4](https://www.linode.com) | `linodev4` | `LINODE_TOKEN` | [Additional configuration](https://go-acme.github.io/lego/dns/linodev4) | | [Liquid Web](https://www.liquidweb.com/) | `liquidweb` | `LIQUID_WEB_PASSWORD`, `LIQUID_WEB_USERNAME`, `LIQUID_WEB_ZONE` | [Additional configuration](https://go-acme.github.io/lego/dns/liquidweb) | -| manual | - | none, but you need to run Traefik interactively [^4], turn on debug log to see instructions and press Enter. | | +| manual | `manual` | none, but you need to run Traefik interactively [^4], turn on debug log to see instructions and press Enter. | | | [MyDNS.jp](https://www.mydns.jp/) | `mydnsjp` | `MYDNSJP_MASTER_ID`, `MYDNSJP_PASSWORD` | [Additional configuration](https://go-acme.github.io/lego/dns/mydnsjp) | | [Namecheap](https://www.namecheap.com) | `namecheap` | `NAMECHEAP_API_USER`, `NAMECHEAP_API_KEY` | [Additional configuration](https://go-acme.github.io/lego/dns/namecheap) | | [name.com](https://www.name.com/) | `namedotcom` | `NAMECOM_USERNAME`, `NAMECOM_API_TOKEN`, `NAMECOM_SERVER` | [Additional configuration](https://go-acme.github.io/lego/dns/namedotcom) | diff --git a/docs/content/migration/v1-to-v2.md b/docs/content/migration/v1-to-v2.md index 880e2748c..32ee64c34 100644 --- a/docs/content/migration/v1-to-v2.md +++ b/docs/content/migration/v1-to-v2.md @@ -322,9 +322,12 @@ Then, a [router's TLS field](../routing/routers/index.md#tls) can refer to one o ## HTTP to HTTPS Redirection is Now Configured on Routers Previously on Traefik v1, the redirection was applied on an entry point or on a frontend. -With Traefik v2 it is applied on a [Router](../routing/routers/index.md). +With Traefik v2 it is applied on an entry point or a [Router](../routing/routers/index.md). -To apply a redirection, one of the redirect middlewares, [RedirectRegex](../middlewares/redirectregex.md) or [RedirectScheme](../middlewares/redirectscheme.md), has to be configured and added to the router middlewares list. +To apply a redirection: + +- on an entry point, the [HTTP redirection](../routing/entrypoints.md#redirection) has to be configured. +- on a router, one of the redirect middlewares, [RedirectRegex](../middlewares/redirectregex.md) or [RedirectScheme](../middlewares/redirectscheme.md), has to be configured and added to the router middlewares list. !!! example "Global HTTP to HTTPS redirection" @@ -352,90 +355,28 @@ To apply a redirection, one of the redirect middlewares, [RedirectRegex](../midd !!! info "v2" - ```yaml tab="Docker" - # ... - traefik: - image: traefik:v2.2 - command: - - --entrypoints.web.address=:80 - - --entrypoints.websecure.address=:443 - - --providers.docker=true - ports: - - 80:80 - - 443:443 - labels: - traefik.http.routers.http_catchall.rule: HostRegexp(`{any:.+}`) - traefik.http.routers.http_catchall.entrypoints: web - traefik.http.routers.http_catchall.middlewares: https_redirect - traefik.http.middlewares.https_redirect.redirectscheme.scheme: https - traefik.http.middlewares.https_redirect.redirectscheme.permanent: true - volumes: - - /var/run/docker.sock:/var/run/docker.sock - ``` + ```bash tab="CLI" + ## static configuration - ```yaml tab="K8s IngressRoute" - # The entry points web (port 80) and websecure (port 443) must be defined the static configuration. - apiVersion: traefik.containo.us/v1alpha1 - kind: IngressRoute - metadata: - name: http_catchall - namespace: traefik - spec: - entryPoints: - - web - routes: - - match: HostRegexp(`{any:.+}`) - kind: Rule - services: - # the noop service will be never called - - name: noop@internal - middlewares: - - name: https_redirect - # if the Middleware has distinct namespace - namespace: traefik - - --- - apiVersion: traefik.containo.us/v1alpha1 - kind: Middleware - metadata: - name: https_redirect - namespace: traefik - spec: - redirectScheme: - scheme: https - permanent: true + --entrypoints.web.address=:80 + --entrypoints.web.http.redirections.entrypoint.to=websecure + --entrypoints.web.http.redirections.entrypoint.scheme=https + --entrypoints.websecure.address=:443 + --providers.docker=true ``` ```toml tab="File (TOML)" # traefik.toml ## static configuration - [entryPoints] - [entryPoints.web] - address = 80 - [entryPoints.websecure] - address = 443 - - [providers.file] - directory = "/dynamic/" - - ##--------------------## - - # /dynamic/redirect.toml - ## dynamic configuration - - [http.routers] - [http.routers.http_catchall] - entryPoints = ["web"] - middlewares = ["https_redirect"] - rule = "HostRegexp(`{any:.+}`)" - # the noop service will be never called - service = "noop@internal" - - [http.middlewares] - [http.middlewares.https_redirect.redirectScheme] + [entryPoints.web] + address = 80 + [entryPoints.web.http.redirections.entryPoint] + to = "websecure" scheme = "https" - permanent = true + + [entryPoints.websecure] + address = 443 ``` ```yaml tab="File (YAML)" @@ -445,34 +386,14 @@ To apply a redirection, one of the redirect middlewares, [RedirectRegex](../midd entryPoints: web: address: 80 + http: + redirections: + entrypoint: + to: websecure + scheme: https + websecure: address: 443 - - providers: - file: - directory: /dynamic/ - - ##--------------------## - - # /dynamic/redirect.yml - ## dynamic configuration - - http: - routers: - http_catchall: - entryPoints: - - web - middlewares: - - https_redirect - rule: "HostRegexp(`{any:.+}`)" - # the noop service will be never called - service: noop@internal - - middlewares: - https_redirect: - redirectScheme: - scheme: https - permanent: true ``` !!! example "HTTP to HTTPS redirection per domain" @@ -480,26 +401,24 @@ To apply a redirection, one of the redirect middlewares, [RedirectRegex](../midd !!! info "v1" ```toml tab="File (TOML)" - # static configuration - defaultEntryPoints = ["web", "websecure"] - [entryPoints] [entryPoints.web] address = ":80" - [entryPoints.web.redirect] - entryPoint = "websecure" [entryPoints.websecure] address = ":443" [entryPoints.websecure.tls] - [[entryPoints.websecure.tls.certificates]] - certFile = "examples/traefik.crt" - keyFile = "examples/traefik.key" - ``` - - ```bash tab="CLI" - --entrypoints=Name:web Address::80 Redirect.EntryPoint:websecure - --entryPoints='Name:websecure Address::443 TLS:path/to/my.cert,path/to/my.key' + + [file] + + [frontends] + [frontends.frontend1] + entryPoints = ["web", "websecure"] + [frontends.frontend1.routes] + [frontends.frontend1.routes.route0] + rule = "Host:foo.com" + [frontends.frontend1.redirect] + entryPoint = "websecure" ``` !!! info "v2" @@ -565,17 +484,6 @@ To apply a redirection, one of the redirect middlewares, [RedirectRegex](../midd ``` ```toml tab="File (TOML)" - ## static configuration - # traefik.toml - - [entryPoints.web] - address = ":80" - - [entryPoints.websecure] - address = ":443" - - ##---------------------## - ## dynamic configuration # dynamic-conf.toml @@ -591,36 +499,14 @@ To apply a redirection, one of the redirect middlewares, [RedirectRegex](../midd service = "my-service" entrypoints = ["websecure"] [http.routers.router1.tls] - - [http.services] - [[http.services.my-service.loadBalancer.servers]] - url = "http://10.10.10.1:80" - [[http.services.my-service.loadBalancer.servers]] - url = "http://10.10.10.2:80" [http.middlewares] [http.middlewares.https_redirect.redirectScheme] scheme = "https" permanent = true - - [[tls.certificates]] - certFile = "/path/to/domain.cert" - keyFile = "/path/to/domain.key" ``` ```yaml tab="File (YAML)" - ## static configuration - # traefik.yml - - entryPoints: - web: - address: ":80" - - websecure: - address: ":443" - - ##---------------------## - ## dynamic configuration # dynamic-conf.yml @@ -641,23 +527,11 @@ To apply a redirection, one of the redirect middlewares, [RedirectRegex](../midd service: my-service tls: {} - services: - my-service: - loadBalancer: - servers: - - url: http://10.10.10.1:80 - - url: http://10.10.10.2:80 - middlewares: https_redirect: redirectScheme: scheme: https permanent: true - - tls: - certificates: - - certFile: /app/certs/server/server.pem - keyFile: /app/certs/server/server.pem ``` ## Strip and Rewrite Path Prefixes @@ -670,8 +544,8 @@ after the routing step with [router rule `PathPrefix`](../routing/routers/index. Use Case: Incoming requests to `http://company.org/admin` are forwarded to the webapplication "admin", with the path `/admin` stripped, e.g. to `http://:/`. In this case, you must: -* First, configure a router named `admin` with a rule matching at least the path prefix with the `PathPrefix` keyword, -* Then, define a middleware of type [`stripprefix`](../middlewares/stripprefix.md), which removes the prefix `/admin`, associated to the router `admin`. +- First, configure a router named `admin` with a rule matching at least the path prefix with the `PathPrefix` keyword, +- Then, define a middleware of type [`stripprefix`](../middlewares/stripprefix.md), which removes the prefix `/admin`, associated to the router `admin`. !!! example "Strip Path Prefix When Forwarding to Backend" @@ -787,10 +661,10 @@ with the path `/admin` stripped, e.g. to `http://:/`. In this case, yo Instead of removing the path prefix with the [`stripprefix` middleware](../../middlewares/stripprefix/), you can also: - * Add a path prefix with the [`addprefix` middleware](../../middlewares/addprefix/) - * Replace the complete path of the request with the [`replacepath` middleware](../../middlewares/replacepath/) - * ReplaceRewrite path using Regexp with the [`replacepathregex` middleware](../../middlewares/replacepathregex/) - * And a lot more on the [`middlewares` page](../../middlewares/overview/) + - Add a path prefix with the [`addprefix` middleware](../../middlewares/addprefix/) + - Replace the complete path of the request with the [`replacepath` middleware](../../middlewares/replacepath/) + - ReplaceRewrite path using Regexp with the [`replacepathregex` middleware](../../middlewares/replacepathregex/) + - And a lot more on the [`middlewares` page](../../middlewares/overview/) ## ACME (LetsEncrypt) @@ -817,8 +691,7 @@ with the path `/admin` stripped, e.g. to `http://:/`. In this case, yo storage = "acme.json" entryPoint = "websecure" onHostRule = true - [acme.httpChallenge] - entryPoint = "web" + [acme.tlsChallenge] ``` ```bash tab="CLI" @@ -829,7 +702,7 @@ with the path `/admin` stripped, e.g. to `http://:/`. In this case, yo --acme.storage=acme.json --acme.entryPoint=websecure --acme.onHostRule=true - --acme.httpchallenge.entrypoint=http + --acme.tlschallenge=true ``` !!! info "v2" @@ -842,13 +715,13 @@ with the path `/admin` stripped, e.g. to `http://:/`. In this case, yo [entryPoints.websecure] address = ":443" + [entryPoints.websecure.http.tls] + certResolver = "myresolver" [certificatesResolvers.myresolver.acme] email = "your-email@your-domain.org" storage = "acme.json" - [certificatesResolvers.myresolver.acme.httpChallenge] - # used during the challenge - entryPoint = "web" + [certificatesResolvers.myresolver.acme.tlsChallenge] ``` ```yaml tab="File (YAML)" @@ -858,23 +731,24 @@ with the path `/admin` stripped, e.g. to `http://:/`. In this case, yo websecure: address: ":443" + http: + tls: + certResolver: myresolver certificatesResolvers: myresolver: acme: email: your-email@your-domain.org storage: acme.json - httpChallenge: - # used during the challenge - entryPoint: web + tlsChallenge: {} ``` ```bash tab="CLI" - --entryPoints.web.address=:80 - --entryPoints.websecure.address=:443 - --certificatesResolvers.myresolver.acme.email=your-email@your-domain.org - --certificatesResolvers.myresolver.acme.storage=acme.json - --certificatesResolvers.myresolver.acme.httpChallenge.entryPoint=web + --entrypoints.web.address=:80 + --entrypoints.websecure.address=:443 + --certificatesresolvers.myresolver.acme.email=your-email@your-domain.org + --certificatesresolvers.myresolver.acme.storage=acme.json + --certificatesresolvers.myresolver.acme.tlschallenge=true ``` ## Traefik Logs @@ -1123,14 +997,11 @@ Each root item has been moved to a related section or removed. ## Dashboard You need to activate the API to access the [dashboard](../operations/dashboard.md). -As the dashboard access is now secured by default you can either: -* define a [specific router](../operations/api.md#configuration) with the `api@internal` service and one authentication middleware like the following example -* or use the [insecure](../operations/api.md#insecure) option of the API +To activate the dashboard, you can either: -!!! info "Dashboard with k8s and dedicated router" - - As `api@internal` is not a Kubernetes service, you have to use the file provider or the `insecure` API option. +- use the [secure mode](../operations/dashboard.md#secure-mode) with the `api@internal` service like in the following examples +- or use the [insecure mode](../operations/api.md#insecure) !!! example "Activate and access the dashboard" @@ -1164,7 +1035,7 @@ As the dashboard access is now secured by default you can either: # dynamic configuration labels: - "traefik.http.routers.api.rule=Host(`traefik.docker.localhost`)" - - "traefik.http.routers.api.entrypoints=websecured" + - "traefik.http.routers.api.entrypoints=websecure" - "traefik.http.routers.api.service=api@internal" - "traefik.http.routers.api.middlewares=myAuth" - "traefik.http.routers.api.tls" @@ -1242,28 +1113,28 @@ As the dashboard access is now secured by default you can either: Supported [providers](../providers/overview.md), for now: -* [ ] Azure Service Fabric -* [x] Consul -* [x] Consul Catalog -* [x] Docker -* [ ] DynamoDB -* [ ] ECS -* [x] Etcd -* [ ] Eureka -* [x] File -* [x] Kubernetes Ingress (without annotations) -* [x] Kubernetes IngressRoute -* [x] Marathon -* [ ] Mesos -* [x] Rancher -* [x] Redis -* [x] Rest -* [x] Zookeeper +- [ ] Azure Service Fabric +- [x] Consul +- [x] Consul Catalog +- [x] Docker +- [ ] DynamoDB +- [ ] ECS +- [x] Etcd +- [ ] Eureka +- [x] File +- [x] Kubernetes Ingress +- [x] Kubernetes IngressRoute +- [x] Marathon +- [ ] Mesos +- [x] Rancher +- [x] Redis +- [x] Rest +- [x] Zookeeper ## Some Tips You Should Know -* Different sources of static configuration (file, CLI flags, ...) cannot be [mixed](../getting-started/configuration-overview.md#the-static-configuration). -* Now, configuration elements can be referenced between different providers by using the provider namespace notation: `@`. +- Different sources of static configuration (file, CLI flags, ...) cannot be [mixed](../getting-started/configuration-overview.md#the-static-configuration). +- Now, configuration elements can be referenced between different providers by using the provider namespace notation: `@`. For instance, a router named `myrouter` in a File Provider can refer to a service named `myservice` defined in Docker Provider with the following notation: `myservice@docker`. -* Middlewares are applied in the same order as their declaration in router. -* If you have any questions feel free to join our [community forum](https://community.containo.us). +- Middlewares are applied in the same order as their declaration in router. +- If you have any questions feel free to join our [community forum](https://community.containo.us).