diff --git a/docs/content/https/acme.md b/docs/content/https/acme.md index 2daa108f7..38c56443c 100644 --- a/docs/content/https/acme.md +++ b/docs/content/https/acme.md @@ -56,6 +56,8 @@ You can configure Traefik to use an ACME provider (like Let's Encrypt) for autom --certificatesResolvers.sample.acme.httpChallenge.entryPoint=web ``` +!!! important "Defining a certificates resolver does not result in all routers automatically using it. Each router that is supposed to use the resolver must [reference](../routing/routers/index.md#certresolver) it." + ??? note "Configuration Reference" There are many available options for ACME. @@ -84,6 +86,8 @@ If there are less than 30 days remaining before the certificate expires, Traefik ## The Different ACME Challenges +!!! important "Defining a certificates resolver does not result in all routers automatically using it. Each router that is supposed to use the resolver must [reference](../routing/routers/index.md#certresolver) it." + ### `tlsChallenge` Use the `TLS-ALPN-01` challenge to generate and renew ACME certificates by provisioning a TLS certificate. diff --git a/docs/content/https/tls.md b/docs/content/https/tls.md index 9dcf660cc..b1ea03216 100644 --- a/docs/content/https/tls.md +++ b/docs/content/https/tls.md @@ -13,7 +13,9 @@ See the [Let's Encrypt](./acme.md) page. To add / remove TLS certificates, even when Traefik is already running, their definition can be added to the [dynamic configuration](../getting-started/configuration-overview.md), in the `[[tls.certificates]]` section: -```toml tab="TOML" +```toml tab="File (TOML)" +# Dynamic configuration + [[tls.certificates]] certFile = "/path/to/domain.cert" keyFile = "/path/to/domain.key" @@ -23,7 +25,9 @@ To add / remove TLS certificates, even when Traefik is already running, their de keyFile = "/path/to/other-domain.key" ``` -```yaml tab="YAML" +```yaml tab="File (YAML)" +# Dynamic configuration + tls: certificates: - certFile: /path/to/domain.cert @@ -32,21 +36,26 @@ tls: keyFile: /path/to/other-domain.key ``` -!!! important "File Provider Only" +!!! important "Restriction" In the above example, we've used the [file provider](../providers/file.md) to handle these definitions. It is the only available method to configure the certificates (as well as the options and the stores). + However, in [Kubernetes](../providers/kubernetes-crd.md), the certificates can and must be provided by [secrets](../providers/kubernetes-crd.md#tls). ## Certificates Stores In Traefik, certificates are grouped together in certificates stores, which are defined as such: -```toml tab="TOML" +```toml tab="File (TOML)" +# Dynamic configuration + [tls.stores] [tls.stores.default] ``` -```yaml tab="YAML" +```yaml tab="File (YAML)" +# Dynamic configuration + tls: stores: default: {} @@ -59,7 +68,9 @@ tls: In the `tls.certificates` section, a list of stores can then be specified to indicate where the certificates should be stored: -```toml tab="TOML" +```toml tab="File (TOML)" +# Dynamic configuration + [[tls.certificates]] certFile = "/path/to/domain.cert" keyFile = "/path/to/domain.key" @@ -72,7 +83,9 @@ In the `tls.certificates` section, a list of stores can then be specified to ind keyFile = "/path/to/other-domain.key" ``` -```yaml tab="YAML" +```yaml tab="File (YAML)" +# Dynamic configuration + tls: certificates: - certFile: /path/to/domain.cert @@ -94,7 +107,9 @@ tls: Traefik can use a default certificate for connections without a SNI, or without a matching domain. This default certificate should be defined in a TLS store: -```toml tab="TOML" +```toml tab="File (TOML)" +# Dynamic configuration + [tls.stores] [tls.stores.default] [tls.stores.default.defaultCertificate] @@ -102,7 +117,9 @@ This default certificate should be defined in a TLS store: keyFile = "path/to/cert.key" ``` -```yaml tab="YAML" +```yaml tab="File (YAML)" +# Dynamic configuration + tls: stores: default: @@ -119,7 +136,9 @@ The TLS options allow one to configure some parameters of the TLS connection. ### Minimum TLS Version -```toml tab="TOML" +```toml tab="File (TOML)" +# Dynamic configuration + [tls.options] [tls.options.default] @@ -129,7 +148,9 @@ The TLS options allow one to configure some parameters of the TLS connection. minVersion = "VersionTLS13" ``` -```yaml tab="YAML" +```yaml tab="File (YAML)" +# Dynamic configuration + tls: options: default: @@ -139,6 +160,105 @@ tls: minVersion: VersionTLS13 ``` +```yaml tab="Kubernetes" +apiVersion: traefik.containo.us/v1alpha1 +kind: TLSOption +metadata: + name: default + namespace: default + +spec: + minVersion: VersionTLS12 + +--- +apiVersion: traefik.containo.us/v1alpha1 +kind: TLSOption +metadata: + name: mintls13 + namespace: default + +spec: + minVersion: VersionTLS13 +``` + +### Cipher Suites + +See [cipherSuites](https://godoc.org/crypto/tls#pkg-constants) for more information. + +```toml tab="File (TOML)" +# Dynamic configuration + +[tls.options] + [tls.options.default] + cipherSuites = [ + "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", + "TLS_RSA_WITH_AES_256_GCM_SHA384" + ] +``` + +```yaml tab="File (YAML)" +# Dynamic configuration + +tls: + options: + default: + cipherSuites: + - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + - TLS_RSA_WITH_AES_256_GCM_SHA384 +``` + +```yaml tab="Kubernetes" +apiVersion: traefik.containo.us/v1alpha1 +kind: TLSOption +metadata: + name: default + namespace: default + +spec: + cipherSuites: + - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + - TLS_RSA_WITH_AES_256_GCM_SHA384 +``` + +!!! important "TLS 1.3" + + Cipher suites defined for TLS 1.2 and below cannot be used in TLS 1.3, and vice versa. () + With TLS 1.3, the cipher suites are not configurable (all supported cipher suites are safe in this case). + + +### Strict SNI Checking + +With strict SNI checking, Traefik won't allow connections from clients connections +that do not specify a server_name extension. + +```toml tab="File (TOML)" +# Dynamic configuration + +[tls.options] + [tls.options.default] + sniStrict = true +``` + +```yaml tab="File (YAML)" +# Dynamic configuration + +tls: + options: + default: + sniStrict: true +``` + +```yaml tab="Kubernetes" +apiVersion: traefik.containo.us/v1alpha1 +kind: TLSOption +metadata: + name: default + namespace: default + +spec: + sniStrict: true +``` + ### Client Authentication (mTLS) Traefik supports mutual authentication, through the `clientAuth` section. @@ -153,7 +273,9 @@ The `clientAuth.clientAuthType` option governs the behaviour as follows: - `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" +```toml tab="File (TOML)" +# Dynamic configuration + [tls.options] [tls.options.default] [tls.options.default.clientAuth] @@ -162,7 +284,9 @@ The `clientAuth.clientAuthType` option governs the behaviour as follows: clientAuthType = "RequireAndVerifyClientCert" ``` -```yaml tab="YAML" +```yaml tab="File (YAML)" +# Dynamic configuration + tls: options: default: @@ -174,42 +298,16 @@ tls: clientAuthType: RequireAndVerifyClientCert ``` -### Cipher Suites +```yaml tab="Kubernetes" +apiVersion: traefik.containo.us/v1alpha1 +kind: TLSOption +metadata: + name: default + namespace: default -See [cipherSuites](https://godoc.org/crypto/tls#pkg-constants) for more information. - -```toml tab="TOML" -[tls.options] - [tls.options.default] - cipherSuites = [ - "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", - "TLS_RSA_WITH_AES_256_GCM_SHA384" - ] -``` - -```yaml tab="YAML" -tls: - options: - default: - cipherSuites: - - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 - - TLS_RSA_WITH_AES_256_GCM_SHA384 -``` - -### Strict SNI Checking - -With strict SNI checking, Traefik won't allow connections from clients connections -that do not specify a server_name extension. - -```toml tab="TOML" -[tls.options] - [tls.options.default] - sniStrict = true -``` - -```yaml tab="YAML" -tls: - options: - default: - sniStrict: true +spec: + clientAuth: + secretNames: + - secretCA + clientAuthType: RequireAndVerifyClientCert ```