From f69982aa9d54673d488b987374a0d5527c52d89f Mon Sep 17 00:00:00 2001 From: Kevin Pollet Date: Thu, 2 Dec 2021 15:42:06 +0100 Subject: [PATCH] docs: uniformize client TLS config documentation --- docs/content/middlewares/http/forwardauth.md | 38 +++++++++++++------ docs/content/providers/consul-catalog.md | 18 ++++----- docs/content/providers/consul.md | 36 ++++++++++++------ docs/content/providers/docker.md | 34 +++++++++++------ docs/content/providers/etcd.md | 36 ++++++++++++------ docs/content/providers/http.md | 38 +++++++++++++------ docs/content/providers/marathon.md | 40 +++++++++++++------- docs/content/providers/redis.md | 36 ++++++++++++------ docs/content/providers/zookeeper.md | 36 ++++++++++++------ 9 files changed, 209 insertions(+), 103 deletions(-) diff --git a/docs/content/middlewares/http/forwardauth.md b/docs/content/middlewares/http/forwardauth.md index 9b21e0279..6c81076b2 100644 --- a/docs/content/middlewares/http/forwardauth.md +++ b/docs/content/middlewares/http/forwardauth.md @@ -349,12 +349,16 @@ http: ### `tls` -The `tls` option is the TLS configuration from Traefik to the authentication server. +_Optional_ -#### `tls.ca` +Defines the TLS configuration used for the secure connection to the authentication server. -Certificate Authority used for the secured connection to the authentication server, -defaults to the system bundle. +#### `ca` + +_Optional_ + +`ca` is the path to the certificate authority used for the secured connection to the authentication server, +it defaults to the system bundle. ```yaml tab="Docker" labels: @@ -417,13 +421,15 @@ http: ca = "path/to/local.crt" ``` -#### `tls.caOptional` +#### `caOptional` -The value of `tls.caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to the authentication server. +_Optional_ + +The value of `caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to the authentication server. !!! warning "" - If `tls.ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. + If `ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. When this option is set to `true`, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid. @@ -479,9 +485,12 @@ http: caOptional = true ``` -#### `tls.cert` +#### `cert` -The public certificate used for the secure connection to the authentication server. +_Optional_ + +`cert` is the path to the public certificate used for the secure connection to the authentication server. +When using this option, setting the `key` option is required. ```yaml tab="Docker" labels: @@ -554,9 +563,12 @@ http: For security reasons, the field does not exist for Kubernetes IngressRoute, and one should use the `secret` field instead. -#### `tls.key` +#### `key` -The private certificate used for the secure connection to the authentication server. +_Optional_ + +`key` is the path to the private key used for the secure connection to the authentication server. +When using this option, setting the `cert` option is required. ```yaml tab="Docker" labels: @@ -629,7 +641,9 @@ http: For security reasons, the field does not exist for Kubernetes IngressRoute, and one should use the `secret` field instead. -#### `tls.insecureSkipVerify` +#### `insecureSkipVerify` + +_Optional, Default=false_ If `insecureSkipVerify` is `true`, the TLS connection to the authentication server accepts any certificate presented by the server regardless of the hostnames it covers. diff --git a/docs/content/providers/consul-catalog.md b/docs/content/providers/consul-catalog.md index 1e4a1bedb..22be954bb 100644 --- a/docs/content/providers/consul-catalog.md +++ b/docs/content/providers/consul-catalog.md @@ -362,14 +362,14 @@ providers: _Optional_ -Defines TLS options for Consul server endpoint. +Defines the TLS configuration used for the secure connection to Consul Catalog. ##### `ca` _Optional_ -Certificate Authority used for the secure connection to Consul, -defaults to the system bundle. +`ca` is the path to the certificate authority used for the secure connection to Consul Catalog, +it defaults to the system bundle. ```yaml tab="File (YAML)" providers: @@ -392,11 +392,11 @@ providers: _Optional_ -The value of `tls.caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Consul. +The value of `caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Consul Catalog. !!! warning "" - If `tls.ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. + If `ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. When this option is set to `true`, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid. @@ -423,8 +423,7 @@ providers: _Optional_ -`cert` is the path to the public certificate to use for Consul communication. - +`cert` is the path to the public certificate used for the secure connection to Consul Catalog. When using this option, setting the `key` option is required. ```yaml tab="File (YAML)" @@ -451,8 +450,7 @@ providers: _Optional_ -`key` is the path to the private key for Consul communication. - +`key` is the path to the private key used for the secure connection to Consul Catalog. When using this option, setting the `cert` option is required. ```yaml tab="File (YAML)" @@ -477,7 +475,7 @@ providers: ##### `insecureSkipVerify` -_Optional_ +_Optional, Default=false_ If `insecureSkipVerify` is `true`, the TLS connection to Consul accepts any certificate presented by the server regardless of the hostnames it covers. diff --git a/docs/content/providers/consul.md b/docs/content/providers/consul.md index d101c7e69..e11d48e39 100644 --- a/docs/content/providers/consul.md +++ b/docs/content/providers/consul.md @@ -104,10 +104,14 @@ providers: _Optional_ -#### `tls.ca` +Defines the TLS configuration used for the secure connection to Consul. -Certificate Authority used for the secure connection to Consul, -defaults to the system bundle. +#### `ca` + +_Optional_ + +`ca` is the path to the certificate authority used for the secure connection to Consul, +it defaults to the system bundle. ```yaml tab="File (YAML)" providers: @@ -125,13 +129,15 @@ providers: --providers.consul.tls.ca=path/to/ca.crt ``` -#### `tls.caOptional` +#### `caOptional` -The value of `tls.caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Consul. +_Optional_ + +The value of `caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Consul. !!! warning "" - If `tls.ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. + If `ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. When this option is set to `true`, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid. @@ -153,9 +159,12 @@ providers: --providers.consul.tls.caOptional=true ``` -#### `tls.cert` +#### `cert` -Public certificate used for the secure connection to Consul. +_Optional_ + +`cert` is the path to the public certificate used for the secure connection to Consul. +When using this option, setting the `key` option is required. ```yaml tab="File (YAML)" providers: @@ -176,9 +185,12 @@ providers: --providers.consul.tls.key=path/to/foo.key ``` -#### `tls.key` +#### `key` -Private certificate used for the secure connection to Consul. +_Optional_ + +`key` is the path to the private key used for the secure connection to Consul. +When using this option, setting the `cert` option is required. ```yaml tab="File (YAML)" providers: @@ -199,7 +211,9 @@ providers: --providers.consul.tls.key=path/to/foo.key ``` -#### `tls.insecureSkipVerify` +#### `insecureSkipVerify` + +_Optional, Default=false_ If `insecureSkipVerify` is `true`, the TLS connection to Consul accepts any certificate presented by the server regardless of the hostnames it covers. diff --git a/docs/content/providers/docker.md b/docs/content/providers/docker.md index f69401e4d..326501cd9 100644 --- a/docs/content/providers/docker.md +++ b/docs/content/providers/docker.md @@ -613,10 +613,14 @@ providers: _Optional_ -#### `tls.ca` +Defines the TLS configuration used for the secure connection to Docker. -Certificate Authority used for the secure connection to Docker, -defaults to the system bundle. +#### `ca` + +_Optional_ + +`ca` is the path to the certificate authority used for the secure connection to Docker, +it defaults to the system bundle. ```yaml tab="File (YAML)" providers: @@ -634,13 +638,15 @@ providers: --providers.docker.tls.ca=path/to/ca.crt ``` -#### `tls.caOptional` +#### `caOptional` -The value of `tls.caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Docker. +_Optional_ + +The value of `caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Docker. !!! warning "" - If `tls.ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. + If `ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. When this option is set to `true`, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid. @@ -662,9 +668,10 @@ providers: --providers.docker.tls.caOptional=true ``` -#### `tls.cert` +#### `cert` -Public certificate used for the secure connection to Docker. +`cert` is the path to the public certificate used for the secure connection to Docker. +When using this option, setting the `key` option is required. ```yaml tab="File (YAML)" providers: @@ -685,9 +692,12 @@ providers: --providers.docker.tls.key=path/to/foo.key ``` -#### `tls.key` +#### `key` -Private certificate used for the secure connection to Docker. +_Optional_ + +`key` is the path to the private key used for the secure connection Docker. +When using this option, setting the `cert` option is required. ```yaml tab="File (YAML)" providers: @@ -708,7 +718,9 @@ providers: --providers.docker.tls.key=path/to/foo.key ``` -#### `tls.insecureSkipVerify` +#### `insecureSkipVerify` + +_Optional, Default=false_ If `insecureSkipVerify` is `true`, the TLS connection to Docker accepts any certificate presented by the server regardless of the hostnames it covers. diff --git a/docs/content/providers/etcd.md b/docs/content/providers/etcd.md index 8df549ca3..d7c2e67b2 100644 --- a/docs/content/providers/etcd.md +++ b/docs/content/providers/etcd.md @@ -104,10 +104,14 @@ providers: _Optional_ -#### `tls.ca` +Defines the TLS configuration used for the secure connection to etcd. -Certificate Authority used for the secure connection to etcd, -defaults to the system bundle. +#### `ca` + +_Optional_ + +`ca` is the path to the certificate authority used for the secure connection to etcd, +it defaults to the system bundle. ```yaml tab="File (YAML)" providers: @@ -125,13 +129,15 @@ providers: --providers.etcd.tls.ca=path/to/ca.crt ``` -#### `tls.caOptional` +#### `caOptional` -The value of `tls.caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to etcd. +_Optional_ + +The value of `caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to etcd. !!! warning "" - If `tls.ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. + If `ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. When this option is set to `true`, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid. @@ -153,9 +159,12 @@ providers: --providers.etcd.tls.caOptional=true ``` -#### `tls.cert` +#### `cert` -Public certificate used for the secure connection to etcd. +_Optional_ + +`cert` is the path to the public certificate used for the secure connection to etcd. +When using this option, setting the `key` option is required. ```yaml tab="File (YAML)" providers: @@ -176,9 +185,12 @@ providers: --providers.etcd.tls.key=path/to/foo.key ``` -#### `tls.key` +#### `key` -Private certificate used for the secure connection to etcd. +_Optional_ + +`key` is the path to the private key used for the secure connection to etcd. +When using this option, setting the `cert` option is required. ```yaml tab="File (YAML)" providers: @@ -199,7 +211,9 @@ providers: --providers.etcd.tls.key=path/to/foo.key ``` -#### `tls.insecureSkipVerify` +#### `insecureSkipVerify` + +_Optional, Default=false_ If `insecureSkipVerify` is `true`, the TLS connection to etcd accepts any certificate presented by the server regardless of the hostnames it covers. diff --git a/docs/content/providers/http.md b/docs/content/providers/http.md index f70c2d059..dd72be317 100644 --- a/docs/content/providers/http.md +++ b/docs/content/providers/http.md @@ -55,7 +55,7 @@ providers: _Optional, Default="5s"_ -Defines the polling timeout when connecting to the configured endpoint. +Defines the polling timeout when connecting to the endpoint. ```yaml tab="File (YAML)" providers: @@ -76,10 +76,14 @@ providers: _Optional_ -#### `tls.ca` +Defines the TLS configuration used for the secure connection to the endpoint. -Certificate Authority used for the secure connection to the configured endpoint, -defaults to the system bundle. +#### `ca` + +_Optional_ + +`ca` is the path to the certificate authority used for the secure connection to the endpoint, +it defaults to the system bundle. ```yaml tab="File (YAML)" providers: @@ -97,13 +101,15 @@ providers: --providers.http.tls.ca=path/to/ca.crt ``` -#### `tls.caOptional` +#### `caOptional` -The value of `tls.caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to the configured endpoint. +_Optional_ + +The value of `caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to the endpoint. !!! warning "" - If `tls.ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. + If `ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. When this option is set to `true`, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid. @@ -125,9 +131,12 @@ providers: --providers.http.tls.caOptional=true ``` -#### `tls.cert` +#### `cert` -Public certificate used for the secure connection to the configured endpoint. +_Optional_ + +`cert` is the path to the public certificate used for the secure connection to the endpoint. +When using this option, setting the `key` option is required. ```yaml tab="File (YAML)" providers: @@ -148,9 +157,12 @@ providers: --providers.http.tls.key=path/to/foo.key ``` -#### `tls.key` +#### `key` -Private certificate used for the secure connection to the configured endpoint. +_Optional_ + +`key` is the path to the private key used for the secure connection to the endpoint. +When using this option, setting the `cert` option is required. ```yaml tab="File (YAML)" providers: @@ -171,7 +183,9 @@ providers: --providers.http.tls.key=path/to/foo.key ``` -#### `tls.insecureSkipVerify` +#### `insecureSkipVerify` + +_Optional, Default=false_ If `insecureSkipVerify` is `true`, the TLS connection to the endpoint accepts any certificate presented by the server regardless of the hostnames it covers. diff --git a/docs/content/providers/marathon.md b/docs/content/providers/marathon.md index 290aa500c..51571ddb2 100644 --- a/docs/content/providers/marathon.md +++ b/docs/content/providers/marathon.md @@ -404,10 +404,12 @@ providers: _Optional_ -#### `tls.ca` +Defines the TLS configuration used for the secure connection to Marathon. -Certificate Authority used for the secure connection to Marathon, -defaults to the system bundle. +#### `ca` + +`ca` is the path to the certificate authority used for the secure connection to Marathon, +it defaults to the system bundle. ```yaml tab="File (YAML)" providers: @@ -425,13 +427,15 @@ providers: --providers.marathon.tls.ca=path/to/ca.crt ``` -#### `tls.caOptional` +#### `caOptional` -The value of `tls.caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Marathon. +_Optional_ + +The value of `caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Marathon. !!! warning "" - If `tls.ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. + If `ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. When this option is set to `true`, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid. @@ -453,9 +457,12 @@ providers: --providers.marathon.tls.caOptional=true ``` -#### `tls.cert` +#### `cert` -Public certificate used for the secure connection to Marathon. +_Optional_ + +`cert` is the path to the public certificate used for the secure connection to Marathon. +When using this option, setting the `key` option is required. ```yaml tab="File (YAML)" providers: @@ -476,9 +483,12 @@ providers: --providers.marathon.tls.key=path/to/foo.key ``` -#### `tls.key` +#### `key` -Private certificate used for the secure connection to Marathon. +_Optional_ + +`key` is the path to the private key used for the secure connection to Marathon. +When using this option, setting the `cert` option is required. ```yaml tab="File (YAML)" providers: @@ -499,7 +509,9 @@ providers: --providers.marathon.tls.key=path/to/foo.key ``` -#### `tls.insecureSkipVerify` +#### `insecureSkipVerify` + +_Optional, Default=false_ If `insecureSkipVerify` is `true`, the TLS connection to Marathon accepts any certificate presented by the server regardless of the hostnames it covers. @@ -532,18 +544,18 @@ see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration). ```yaml tab="File (YAML)" providers: marathon: - responseHeaderTimeout: "10s" + tlsHandshakeTimeout: "10s" # ... ``` ```toml tab="File (TOML)" [providers.marathon] - responseHeaderTimeout = "10s" + tlsHandshakeTimeout = "10s" # ... ``` ```bash tab="CLI" ---providers.marathon.responseHeaderTimeout=10s +--providers.marathon.tlsHandshakeTimeout=10s # ... ``` diff --git a/docs/content/providers/redis.md b/docs/content/providers/redis.md index 70607d2ae..629c10db0 100644 --- a/docs/content/providers/redis.md +++ b/docs/content/providers/redis.md @@ -104,10 +104,14 @@ providers: _Optional_ -#### `tls.ca` +Defines the TLS configuration used for the secure connection to Redis. -Certificate Authority used for the secure connection to Redis, -defaults to the system bundle. +#### `ca` + +_Optional_ + +`ca` is the path to the certificate authority used for the secure connection to Redis, +it defaults to the system bundle. ```yaml tab="File (YAML)" providers: @@ -125,13 +129,15 @@ providers: --providers.redis.tls.ca=path/to/ca.crt ``` -#### `tls.caOptional` +#### `caOptional` -The value of `tls.caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Redis. +_Optional_ + +The value of `caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Redis. !!! warning "" - If `tls.ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. + If `ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. When this option is set to `true`, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid. @@ -153,9 +159,12 @@ providers: --providers.redis.tls.caOptional=true ``` -#### `tls.cert` +#### `cert` -Public certificate used for the secure connection to Redis. +_Optional_ + +`cert` is the path to the public certificate used for the secure connection to Redis. +When using this option, setting the `key` option is required. ```yaml tab="File (YAML)" providers: @@ -176,9 +185,12 @@ providers: --providers.redis.tls.key=path/to/foo.key ``` -#### `tls.key` +#### `key` -Private certificate used for the secure connection to Redis. +_Optional_ + +`key` is the path to the private key used for the secure connection to Redis. +When using this option, setting the `cert` option is required. ```yaml tab="File (YAML)" providers: @@ -199,7 +211,9 @@ providers: --providers.redis.tls.key=path/to/foo.key ``` -#### `tls.insecureSkipVerify` +#### `insecureSkipVerify` + +_Optional, Default=false_ If `insecureSkipVerify` is `true`, the TLS connection to Redis accepts any certificate presented by the server regardless of the hostnames it covers. diff --git a/docs/content/providers/zookeeper.md b/docs/content/providers/zookeeper.md index b89daa6bf..3f84975f9 100644 --- a/docs/content/providers/zookeeper.md +++ b/docs/content/providers/zookeeper.md @@ -104,10 +104,14 @@ providers: _Optional_ -#### `tls.ca` +Defines the TLS configuration used for the secure connection to ZooKeeper. -Certificate Authority used for the secure connection to ZooKeeper, -defaults to the system bundle. +#### `ca` + +_Optional_ + +`ca` is the path to the certificate authority used for the secure connection to ZooKeeper, +it defaults to the system bundle. ```yaml tab="File (YAML)" providers: @@ -125,13 +129,15 @@ providers: --providers.zookeeper.tls.ca=path/to/ca.crt ``` -#### `tls.caOptional` +#### `caOptional` -The value of `tls.caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Zookeeper. +_Optional_ + +The value of `caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Zookeeper. !!! warning "" - If `tls.ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. + If `ca` is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified. When this option is set to `true`, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid. @@ -153,9 +159,12 @@ providers: --providers.zookeeper.tls.caOptional=true ``` -#### `tls.cert` +#### `cert` -Public certificate used for the secure connection to ZooKeeper. +_Optional_ + +`cert` is the path to the public certificate used for the secure connection to ZooKeeper. +When using this option, setting the `key` option is required. ```yaml tab="File (YAML)" providers: @@ -176,9 +185,12 @@ providers: --providers.zookeeper.tls.key=path/to/foo.key ``` -#### `tls.key` +#### `key` -Private certificate used for the secure connection to ZooKeeper. +_Optional_ + +`key` is the path to the private key used for the secure connection to ZooKeeper. +When using this option, setting the `cert` option is required. ```yaml tab="File (YAML)" providers: @@ -199,7 +211,9 @@ providers: --providers.zookeeper.tls.key=path/to/foo.key ``` -#### `tls.insecureSkipVerify` +#### `insecureSkipVerify` + +_Optional, Default=false_ If `insecureSkipVerify` is `true`, the TLS connection to Zookeeper accepts any certificate presented by the server regardless of the hostnames it covers.