From 232c113dae46cd026227aa50da7a7f06389094af Mon Sep 17 00:00:00 2001 From: Ludovic Fernandez Date: Mon, 9 Sep 2019 10:36:08 +0200 Subject: [PATCH] Misc documentation fixes --- .semaphoreci/setup.sh | 2 +- docs/content/https/tls.md | 12 +- docs/content/middlewares/forwardauth.md | 10 +- docs/content/middlewares/overview.md | 4 +- docs/content/middlewares/redirectregex.md | 4 +- docs/content/middlewares/stripprefix.md | 6 +- docs/content/middlewares/stripprefixregex.md | 4 +- docs/content/migration/v1-to-v2.md | 9 ++ docs/content/operations/ping.md | 2 +- docs/content/providers/docker.md | 114 ++++++++++++++++++- docs/content/providers/marathon.md | 109 +++++++++++++++--- docs/content/providers/rancher.md | 4 +- docs/content/routing/entrypoints.md | 4 +- 13 files changed, 242 insertions(+), 42 deletions(-) diff --git a/.semaphoreci/setup.sh b/.semaphoreci/setup.sh index f087c644d..c3cb1ebc9 100755 --- a/.semaphoreci/setup.sh +++ b/.semaphoreci/setup.sh @@ -18,7 +18,7 @@ echo ${SHOULD_TEST} #if [ -n "$SHOULD_TEST" ]; then sudo -E apt-get -yq update; fi #if [ -n "$SHOULD_TEST" ]; then sudo -E apt-get -yq --no-install-suggests --no-install-recommends --force-yes install docker-ce=${DOCKER_VERSION}*; fi if [ -n "$SHOULD_TEST" ]; then docker version; fi -export GO_VERSION=1.13 +export GO_VERSION=1.12 if [ -f "./go.mod" ]; then GO_VERSION="$(grep '^go .*' go.mod | awk '{print $2}')"; export GO_VERSION; fi #if [ "${GO_VERSION}" == '1.13' ]; then export GO_VERSION=1.13rc2; fi echo "Selected Go version: ${GO_VERSION}" diff --git a/docs/content/https/tls.md b/docs/content/https/tls.md index 21cbe5835..9dcf660cc 100644 --- a/docs/content/https/tls.md +++ b/docs/content/https/tls.md @@ -141,17 +141,17 @@ tls: ### Client Authentication (mTLS) -Traefik supports mutual authentication, through the `ClientAuth` section. +Traefik supports mutual authentication, through the `clientAuth` section. -For authentication policies that require verification of the client certificate, the certificate authority for the certificate should be set in `ClientAuth.caFiles`. +For authentication policies that require verification of the client certificate, the certificate authority for the certificate should be set in `clientAuth.caFiles`. -The `ClientAuth.clientAuthType` option governs the behaviour as follows: +The `clientAuth.clientAuthType` option governs the behaviour as follows: - `NoClientCert`: disregards any client certificate. - `RequestClientCert`: asks for a certificate but proceeds anyway if none is provided. -- `RequireAnyClientCert`: requires a certificate but does not verify if it is signed by a CA listed in `ClientAuth.caFiles`. -- `VerifyClientCertIfGiven`: if a certificate is provided, verifies if it is signed by a CA listed in `ClientAuth.caFiles`. Otherwise proceeds without any certificate. -- `RequireAndVerifyClientCert`: requires a certificate, which must be signed by a CA listed in `ClientAuth.caFiles`. +- `RequireAnyClientCert`: requires a certificate but does not verify if it is signed by a CA listed in `clientAuth.caFiles`. +- `VerifyClientCertIfGiven`: if a certificate is provided, verifies if it is signed by a CA listed in `clientAuth.caFiles`. Otherwise proceeds without any certificate. +- `RequireAndVerifyClientCert`: requires a certificate, which must be signed by a CA listed in `clientAuth.caFiles`. ```toml tab="TOML" [tls.options] diff --git a/docs/content/middlewares/forwardauth.md b/docs/content/middlewares/forwardauth.md index 3bd35b84f..9b9f7678e 100644 --- a/docs/content/middlewares/forwardauth.md +++ b/docs/content/middlewares/forwardauth.md @@ -206,7 +206,7 @@ The `tls` option is the TLS configuration from Traefik to the authentication ser #### `tls.ca` -TODO +TODO add description. ```yaml tab="Docker" labels: @@ -266,7 +266,7 @@ http: #### `tls.caOptional` -TODO +TODO add description. ```yaml tab="Docker" labels: @@ -316,7 +316,7 @@ http: #### `tls.cert` -TODO +TODO add description. ```yaml tab="Docker" labels: @@ -385,7 +385,7 @@ http: #### `tls.key` -TODO +TODO add description. ```yaml tab="Docker" labels: @@ -454,7 +454,7 @@ http: #### `tls.insecureSkipVerify` -TODO +TODO add description. ```yaml tab="Docker" labels: diff --git a/docs/content/middlewares/overview.md b/docs/content/middlewares/overview.md index a69ccddca..fc90847dd 100644 --- a/docs/content/middlewares/overview.md +++ b/docs/content/middlewares/overview.md @@ -66,7 +66,7 @@ spec: ```json tab="Marathon" "labels": { "traefik.http.middlewares.foo-add-prefix.addprefix.prefix": "/foo", - "traefik.http.router.router1.middlewares": "foo-add-prefix@marathon" + "traefik.http.routers.router1.middlewares": "foo-add-prefix@marathon" } ``` @@ -76,7 +76,7 @@ labels: # Create a middleware named `foo-add-prefix` - "traefik.http.middlewares.foo-add-prefix.addprefix.prefix=/foo" # Apply the middleware named `foo-add-prefix` to the router named `router1` - - "traefik.http.router.router1.middlewares=foo-add-prefix@rancher" + - "traefik.http.routers.router1.middlewares=foo-add-prefix@rancher" ``` ```toml tab="File (TOML)" diff --git a/docs/content/middlewares/redirectregex.md b/docs/content/middlewares/redirectregex.md index 2d1a19d76..c34da5133 100644 --- a/docs/content/middlewares/redirectregex.md +++ b/docs/content/middlewares/redirectregex.md @@ -11,6 +11,7 @@ RegexRedirect redirect a request from an url to another with regex matching and ```yaml tab="Docker" # Redirect with domain replacement +# Note: all dollar signs need to be doubled for escaping. labels: - "traefik.http.middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)" - "traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$${1}" @@ -37,9 +38,10 @@ spec: ```yaml tab="Rancher" # Redirect with domain replacement +# Note: all dollar signs need to be doubled for escaping. labels: - "traefik.http.middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)" -- "traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/${1}" +- "traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$${1}" ``` ```toml tab="File (TOML)" diff --git a/docs/content/middlewares/stripprefix.md b/docs/content/middlewares/stripprefix.md index 8b2fe0ab2..14e1df748 100644 --- a/docs/content/middlewares/stripprefix.md +++ b/docs/content/middlewares/stripprefix.md @@ -12,7 +12,7 @@ Remove the specified prefixes from the URL path. ```yaml tab="Docker" # Strip prefix /foobar and /fiibar labels: -- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar, /fiibar" +- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar" ``` ```yaml tab="Kubernetes" @@ -30,14 +30,14 @@ spec: ```json tab="Marathon" "labels": { - "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes": "/foobar, /fiibar" + "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes": "/foobar,/fiibar" } ``` ```yaml tab="Rancher" # Strip prefix /foobar and /fiibar labels: -- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar, /fiibar" +- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar" ``` ```toml tab="File (TOML)" diff --git a/docs/content/middlewares/stripprefixregex.md b/docs/content/middlewares/stripprefixregex.md index 4daee17c4..f73184650 100644 --- a/docs/content/middlewares/stripprefixregex.md +++ b/docs/content/middlewares/stripprefixregex.md @@ -9,7 +9,7 @@ Remove the matching prefixes from the URL path. ```yaml tab="Docker" labels: -- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/", +- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/" ``` ```yaml tab="Kubernetes" @@ -31,7 +31,7 @@ spec: ```yaml tab="Rancher" labels: -- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/", +- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/" ``` ```toml tab="File (TOML)" diff --git a/docs/content/migration/v1-to-v2.md b/docs/content/migration/v1-to-v2.md index a1564a9fc..ba0742c0f 100644 --- a/docs/content/migration/v1-to-v2.md +++ b/docs/content/migration/v1-to-v2.md @@ -8,6 +8,15 @@ which require one to update their configuration when they migrate from v1 to v2. The goal of this page is to recapitulate all of these changes, and in particular to give examples, feature by feature, of how the configuration looked like in v1, and how it now looks like in v2. +!!! Note "Migration Helper" + + We created a tool to help during the migration: [traefik-migration-tool](https://github.com/containous/traefik-migration-tool) + + This tool allows to: + + - convert `Ingress` to Traefik `IngressRoute` resources. + - convert `acme.json` file from v1 to v2 format. + ## Frontends and Backends Are Dead...
... Long Live Routers, Middlewares, and Services During the transition from v1 to v2, a number of internal pieces and components of Traefik were rewritten and reorganized. diff --git a/docs/content/operations/ping.md b/docs/content/operations/ping.md index 6298a3e7d..26c03fca4 100644 --- a/docs/content/operations/ping.md +++ b/docs/content/operations/ping.md @@ -5,7 +5,7 @@ Checking the Health of Your Traefik Instances ## Configuration Examples -!!! example "Enabling /ping" +To enable the API handler: ```toml tab="File (TOML)" [ping] diff --git a/docs/content/providers/docker.md b/docs/content/providers/docker.md index 5e45f6cf4..a7e2fab9b 100644 --- a/docs/content/providers/docker.md +++ b/docs/content/providers/docker.md @@ -388,7 +388,7 @@ Constraints is an expression that Traefik matches against the container's labels That is to say, if none of the container's labels match the expression, no route for the container is created. If the expression is empty, all detected containers are included. -The expression syntax is based on the `Label("key", "value")`, and `LabelRegexp("key", "value")` functions, as well as the usual boolean logic, as shown in examples below. +The expression syntax is based on the `Label("key", "value")`, and `LabelRegex("key", "value")` functions, as well as the usual boolean logic, as shown in examples below. ??? example "Constraints Expression Examples" @@ -419,11 +419,121 @@ The expression syntax is based on the `Label("key", "value")`, and `LabelRegexp( ```toml # Includes only containers having a label with key `a.label.name` and a value matching the `a.+` regular expression. - constraints = "LabelRegexp(`a.label.name`, `a.+`)" + constraints = "LabelRegex(`a.label.name`, `a.+`)" ``` See also [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). +### `tls` + +_Optional_ + +#### `tls.ca` + +TODO add description. + +```toml tab="File (TOML)" +[providers.docker.tls] + ca = "path/to/ca.crt" +``` + +```yaml tab="File (YAML)" +providers: + docker: + tls: + ca: path/to/ca.crt +``` + +```bash tab="CLI" +--providers.docker.tls.ca=path/to/ca.crt +``` + +#### `tls.caOptional` + +TODO add description. + +```toml tab="File (TOML)" +[providers.docker.tls] + caOptional = true +``` + +```yaml tab="File (YAML)" +providers: + docker: + tls: + caOptional: true +``` + +```bash tab="CLI" +--providers.docker.tls.caOptional=true +``` + +#### `tls.cert` + +TODO add description. + +```toml tab="File (TOML)" +[providers.docker.tls] + cert = "path/to/foo.cert" + key = "path/to/foo.key" +``` + +```yaml tab="File (YAML)" +providers: + docker: + tls: + cert: path/to/foo.cert + key: path/to/foo.key +``` + +```bash tab="CLI" +--providers.docker.tls.cert=path/to/foo.cert +--providers.docker.tls.key=path/to/foo.key +``` + +#### `tls.key` + +TODO add description. + +```toml tab="File (TOML)" +[providers.docker.tls] + cert = "path/to/foo.cert" + key = "path/to/foo.key" +``` + +```yaml tab="File (YAML)" +providers: + docker: + tls: + cert: path/to/foo.cert + key: path/to/foo.key +``` + +```bash tab="CLI" +--providers.docker.tls.cert=path/to/foo.cert +--providers.docker.tls.key=path/to/foo.key +``` + +#### `tls.insecureSkipVerify` + +TODO add description. + +```toml tab="File (TOML)" +[providers.docker.tls] + insecureSkipVerify = true +``` + +```yaml tab="File (YAML)" +providers: + docker: + tls: + insecureSkipVerify: true +``` + +```bash tab="CLI" +--providers.docker.tls.insecureSkipVerify=true +``` + ## Routing Configuration Options ### General diff --git a/docs/content/providers/marathon.md b/docs/content/providers/marathon.md index 762b7a0f7..b7064c869 100644 --- a/docs/content/providers/marathon.md +++ b/docs/content/providers/marathon.md @@ -398,37 +398,116 @@ when waiting for the first response header from a Marathon master. Can be provided in a format supported by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration), or directly as a number of seconds. -### `TLS` +### `tls` _Optional_ +#### `tls.ca` + +TODO add description. + +```toml tab="File (TOML)" +[providers.marathon.tls] + ca = "path/to/ca.crt" +``` + +```yaml tab="File (YAML)" +providers: + marathon: + tls: + ca: path/to/ca.crt +``` + +```bash tab="CLI" +--providers.marathon.tls.ca=path/to/ca.crt +``` + +#### `tls.caOptional` + +TODO add description. + +```toml tab="File (TOML)" +[providers.marathon.tls] + caOptional = true +``` + +```yaml tab="File (YAML)" +providers: + marathon: + tls: + caOptional: true +``` + +```bash tab="CLI" +--providers.marathon.tls.caOptional=true +``` + +#### `tls.cert` + +TODO add description. + +```toml tab="File (TOML)" +[providers.marathon.tls] + cert = "path/to/foo.cert" + key = "path/to/foo.key" +``` + +```yaml tab="File (YAML)" +providers: + marathon: + tls: + cert: path/to/foo.cert + key: path/to/foo.key +``` + +```bash tab="CLI" +--providers.marathon.tls.cert=path/to/foo.cert +--providers.marathon.tls.key=path/to/foo.key +``` + +#### `tls.key` + +TODO add description. + +```toml tab="File (TOML)" +[providers.marathon.tls] + cert = "path/to/foo.cert" + key = "path/to/foo.key" +``` + +```yaml tab="File (YAML)" +providers: + marathon: + tls: + cert: path/to/foo.cert + key: path/to/foo.key +``` + +```bash tab="CLI" +--providers.marathon.tls.cert=path/to/foo.cert +--providers.marathon.tls.key=path/to/foo.key +``` + +#### `tls.insecureSkipVerify` + +TODO add description. + ```toml tab="File (TOML)" [providers.marathon.tls] - ca = "/etc/ssl/ca.crt" - cert = "/etc/ssl/marathon.cert" - key = "/etc/ssl/marathon.key" insecureSkipVerify = true ``` ```yaml tab="File (YAML)" providers: - marathon + marathon: tls: - ca: "/etc/ssl/ca.crt" - cert: "/etc/ssl/marathon.cert" - key: "/etc/ssl/marathon.key" - insecureSkipVerify: true + insecureSkipVerify: true ``` ```bash tab="CLI" ---providers.marathon.tls.ca="/etc/ssl/ca.crt" ---providers.marathon.tls.cert="/etc/ssl/marathon.cert" ---providers.marathon.tls.key="/etc/ssl/marathon.key" ---providers.marathon.tls.insecureskipverify=true +--providers.marathon.tls.insecureSkipVerify=true ``` -TLS client configuration. [tls/#Config](https://golang.org/pkg/crypto/tls/#Config). - ### `tlsHandshakeTimeout` _Optional, Default=5s_ diff --git a/docs/content/providers/rancher.md b/docs/content/providers/rancher.md index f3aa97121..5931476bc 100644 --- a/docs/content/providers/rancher.md +++ b/docs/content/providers/rancher.md @@ -239,7 +239,7 @@ Constraints is an expression that Traefik matches against the container's labels That is to say, if none of the container's labels match the expression, no route for the container is created. If the expression is empty, all detected containers are included. -The expression syntax is based on the `Label("key", "value")`, and `LabelRegexp("key", "value")` functions, as well as the usual boolean logic, as shown in examples below. +The expression syntax is based on the `Label("key", "value")`, and `LabelRegex("key", "value")` functions, as well as the usual boolean logic, as shown in examples below. ??? example "Constraints Expression Examples" @@ -270,7 +270,7 @@ The expression syntax is based on the `Label("key", "value")`, and `LabelRegexp( ```toml # Includes only containers having a label with key `a.label.name` and a value matching the `a.+` regular expression. - constraints = "LabelRegexp(`a.label.name`, `a.+`)" + constraints = "LabelRegex(`a.label.name`, `a.+`)" ``` See also [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery). diff --git a/docs/content/routing/entrypoints.md b/docs/content/routing/entrypoints.md index df8d9e676..f51412c8a 100644 --- a/docs/content/routing/entrypoints.md +++ b/docs/content/routing/entrypoints.md @@ -149,7 +149,7 @@ If the proxyprotocol header is passed, then the version is determined automatica entryPoints: web: address: ":80" - proxyProtocol + proxyProtocol: trustedIPs: - "127.0.0.1/32" - "192.168.1.7" @@ -213,7 +213,7 @@ You can configure Traefik to trust the forwarded headers information (`X-Forward entryPoints: web: address: ":80" - forwardedHeaders + forwardedHeaders: trustedIPs: - "127.0.0.1/32" - "192.168.1.7"