Merge TLSOption/TLSStore CRD documentation page
This commit is contained in:
Nicolas Mengin
GitHub
parent
9dfcded534
commit
3a7d331967
5 changed files with 4 additions and 16 deletions
|
|
@ -0,0 +1,83 @@
|
|||
---
|
||||
title: "TLSOption"
|
||||
description: "TLS Options in Traefik Proxy"
|
||||
---
|
||||
|
||||
The TLS options allow you to configure some parameters of the TLS connection in Traefik.
|
||||
|
||||
Before creating `TLSOption` objects or referencing TLS options in the [`IngressRoute`](../http/ingressroute.md) / [`IngressRouteTCP`](../tcp/ingressroutetcp.md) objects, you need to apply the [Traefik Kubernetes CRDs](https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions) to your Kubernetes cluster.
|
||||
|
||||
!!! tip "References and namespaces"
|
||||
If the optional namespace attribute is not set, the configuration will be applied with the namespace of the `IngressRoute`/`IngressRouteTCP`.
|
||||
|
||||
Additionally, when the definition of the TLS option is from another provider, the cross-provider [syntax](../../../../install-configuration/providers/overview.md#provider-namespace) (`middlewarename@provider`) should be used to refer to the TLS option. Specifying a namespace attribute in this case would not make any sense, and will be ignored.
|
||||
|
||||
!!! important "TLSOption in Kubernetes"
|
||||
|
||||
When using the `TLSOption` resource in Kubernetes, one might setup a default set of options that,
|
||||
if not explicitly overwritten, should apply to all ingresses.
|
||||
To achieve that, you'll have to create a `TLSOption` resource with the name `default`.
|
||||
There may exist only one `TLSOption` with the name `default` (across all namespaces) - otherwise they will be dropped.
|
||||
To explicitly use a different `TLSOption` (and using the Kubernetes Ingress resources)
|
||||
you'll have to add an annotation to the Ingress in the following form:
|
||||
`traefik.ingress.kubernetes.io/router.tls.options: <resource-namespace>-<resource-name>@kubernetescrd`
|
||||
|
||||
## Configuration Example
|
||||
|
||||
```yaml tab="TLSOption"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: TLSOption
|
||||
metadata:
|
||||
name: mytlsoption
|
||||
namespace: default
|
||||
|
||||
spec:
|
||||
minVersion: VersionTLS12
|
||||
sniStrict: true
|
||||
cipherSuites:
|
||||
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
|
||||
- TLS_RSA_WITH_AES_256_GCM_SHA384
|
||||
clientAuth:
|
||||
secretNames:
|
||||
- secret-ca1
|
||||
- secret-ca2
|
||||
clientAuthType: VerifyClientCertIfGiven
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Default | Required |
|
||||
|:----------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------|:---------|
|
||||
| <a id="opt-minVersion" href="#opt-minVersion" title="#opt-minVersion">`minVersion`</a> | Minimum TLS version that is acceptable. | "VersionTLS12" | No |
|
||||
| <a id="opt-maxVersion" href="#opt-maxVersion" title="#opt-maxVersion">`maxVersion`</a> | Maximum TLS version that is acceptable.<br />We do not recommend setting this option to disable TLS 1.3. | | No |
|
||||
| <a id="opt-cipherSuites" href="#opt-cipherSuites" title="#opt-cipherSuites">`cipherSuites`</a> | List of supported [cipher suites](https://godoc.org/crypto/tls#pkg-constants) for TLS versions up to TLS 1.2.<br />[Cipher suites defined for TLS 1.2 and below cannot be used in TLS 1.3, and vice versa.](https://tools.ietf.org/html/rfc8446)<br />With TLS 1.3, [the cipher suites are not configurable](https://golang.org/doc/go1.12#tls_1_3) (all supported cipher suites are safe in this case). | | No |
|
||||
| <a id="opt-curvePreferences" href="#opt-curvePreferences" title="#opt-curvePreferences">`curvePreferences`</a> | List of the elliptic curves references that will be used in an ECDHE handshake.<br />Use curves names from [`crypto`](https://godoc.org/crypto/tls#CurveID) or the [RFC](https://tools.ietf.org/html/rfc8446#section-4.2.7).<br />See [CurveID](https://godoc.org/crypto/tls#CurveID) for more information. | | No |
|
||||
| <a id="opt-clientAuth-secretNames" href="#opt-clientAuth-secretNames" title="#opt-clientAuth-secretNames">`clientAuth.secretNames`</a> | Client Authentication (mTLS) option.<br />List of names of the referenced Kubernetes [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) (in TLSOption namespace).<br /> The secret must contain a certificate under either a `tls.ca` or a `ca.crt` key. | | No |
|
||||
| <a id="opt-clientAuth-clientAuthType" href="#opt-clientAuth-clientAuthType" title="#opt-clientAuth-clientAuthType">`clientAuth.clientAuthType`</a> | Client Authentication (mTLS) option.<br />Client authentication type to apply. Available values [here](#client-authentication-mtls). | | No |
|
||||
| <a id="opt-sniStrict" href="#opt-sniStrict" title="#opt-sniStrict">`sniStrict`</a> | Allow rejecting connections from clients connections that do not specify a server_name extension.<br />The [default certificate](../../../http/tls/tls-certificates.md#default-certificate) is never served is the option is enabled. | false | No |
|
||||
| <a id="opt-alpnProtocols" href="#opt-alpnProtocols" title="#opt-alpnProtocols">`alpnProtocols`</a> | List of supported application level protocols for the TLS handshake, in order of preference.<br />If the client supports ALPN, the selected protocol will be one from this list, and the connection will fail if there is no mutually supported protocol. | "h2, http/1.1, acme-tls/1" | No |
|
||||
| <a id="opt-disableSessiontTickets" href="#opt-disableSessiontTickets" title="#opt-disableSessiontTickets">`disableSessiontTickets`</a> | Allow disabling the use of session tickets, forcing every client to perform a full TLS handshake instead of resuming sessions. | false | No |
|
||||
|
||||
### Client Authentication (mTLS)
|
||||
|
||||
The `clientAuth.clientAuthType` option governs the behavior 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` or in `clientAuth.secretNames`.
|
||||
- `VerifyClientCertIfGiven`: if a certificate is provided, verifies if it is signed by a CA listed in `clientAuth.caFiles` or in `clientAuth.secretNames`. Otherwise proceeds without any certificate.
|
||||
- `RequireAndVerifyClientCert`: requires a certificate, which must be signed by a CA listed in `clientAuth.caFiles` or in `clientAuth.secretNames`.
|
||||
|
||||
!!! note "CA Secret"
|
||||
The CA secret must contain a base64 encoded certificate under either a `tls.ca` or a `ca.crt` key.
|
||||
|
||||
### Default TLS Option
|
||||
|
||||
When no TLS options are specified in an `IngressRoute`/`IngressRouteTCP`, the `default` option is used.
|
||||
The default behavior is summed up in the table below:
|
||||
|
||||
| Configuration | Behavior |
|
||||
|:--------------------------|:------------------------------------------------------------|
|
||||
| <a id="opt-No-default-TLS-Option" href="#opt-No-default-TLS-Option" title="#opt-No-default-TLS-Option">No `default` TLS Option</a> | Default internal set of TLS Options by default. |
|
||||
| <a id="opt-One-default-TLS-Option" href="#opt-One-default-TLS-Option" title="#opt-One-default-TLS-Option">One `default` TLS Option</a> | Custom TLS Options applied by default. |
|
||||
| <a id="opt-Many-default-TLS-Option" href="#opt-Many-default-TLS-Option" title="#opt-Many-default-TLS-Option">Many `default` TLS Option</a> | Error log + Default internal set of TLS Options by default. |
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
title: "TLSStore"
|
||||
description: "TLS Store in Traefik Proxy"
|
||||
---
|
||||
|
||||
In Traefik, certificates are grouped together in certificates stores.
|
||||
|
||||
`TLSStore` is the CRD implementation of a [Traefik TLS Store](../../../http/tls/tls-certificates.md#certificates-stores).
|
||||
|
||||
Before creating `TLSStore` objects, you need to apply the [Traefik Kubernetes CRDs](https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions) to your Kubernetes cluster.
|
||||
|
||||
!!! Tip "Default TLS Store"
|
||||
Traefik currently only uses the TLS Store named "default". This default `TLSStore` should be in a namespace discoverable by Traefik. Since it is used by default on `IngressRoute` and `IngressRouteTCP` objects, there never is a need to actually reference it. This means that you cannot have two stores that are named default in different Kubernetes namespaces. As a consequence, with respect to TLS stores, the only change that makes sense (and only if needed) is to configure the default `TLSStore`.
|
||||
|
||||
## Configuration Example
|
||||
|
||||
```yaml tab="TLSStore"
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: TLSStore
|
||||
metadata:
|
||||
name: default
|
||||
|
||||
spec:
|
||||
defaultCertificate:
|
||||
secretName: supersecret
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Field | Description | Required |
|
||||
|:---------------------------------------|:-------------------------|:---------|
|
||||
| <a id="opt-certificatesn-secretName" href="#opt-certificatesn-secretName" title="#opt-certificatesn-secretName">`certificates[n].secretName`</a> | List of Kubernetes [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/), each of them holding a key/certificate pair to add to the store. | No |
|
||||
| <a id="opt-defaultCertificate-secretName" href="#opt-defaultCertificate-secretName" title="#opt-defaultCertificate-secretName">`defaultCertificate.secretName`</a> | Name of the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) served for connections without a SNI, or without a matching domain. If no default certificate is provided, Traefik will use the generated one. Do not use if the option `defaultGeneratedCert` is set. | No |
|
||||
| <a id="opt-defaultGeneratedCert-resolver" href="#opt-defaultGeneratedCert-resolver" title="#opt-defaultGeneratedCert-resolver">`defaultGeneratedCert.resolver`</a> | Name of the ACME resolver to use to generate the default certificate.<br /> Do not use if the option `defaultCertificate` is set. | No |
|
||||
| <a id="opt-defaultGeneratedCert-domain-main" href="#opt-defaultGeneratedCert-domain-main" title="#opt-defaultGeneratedCert-domain-main">`defaultGeneratedCert.domain.main`</a> | Main domain used to generate the default certificate.<br /> Do not use if the option `defaultCertificate` is set. | No |
|
||||
| <a id="opt-defaultGeneratedCert-domain-sans" href="#opt-defaultGeneratedCert-domain-sans" title="#opt-defaultGeneratedCert-domain-sans">`defaultGeneratedCert.domain.sans`</a> | List of [Subject Alternative Name](https://en.wikipedia.org/wiki/Subject_Alternative_Name) used to generate the default certificate.<br /> Do not use if the option `defaultCertificate` is set. | No |
|
||||
|
||||
!!! note "DefaultCertificate vs DefaultGeneratedCert"
|
||||
If both `defaultCertificate` and `defaultGeneratedCert` are set, the TLS certificate contained in `defaultCertificate.secretName` is served. The ACME default certificate is not generated.
|
||||
Loading…
Add table
Add a link
Reference in a new issue