From a28df9e23d53140beda6f4d8645eafde4d4b9ac5 Mon Sep 17 00:00:00 2001 From: Tim Ramlot <42113979+inteon@users.noreply.github.com> Date: Fri, 13 Oct 2023 18:20:29 +0200 Subject: [PATCH 1/3] reorganise 'Certificate resource' page Signed-off-by: Tim Ramlot <42113979+inteon@users.noreply.github.com> --- content/docs/usage/certificate.md | 284 ++++++++++++++++-------------- 1 file changed, 147 insertions(+), 137 deletions(-) diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md index 3882fba3c36..9b0bf9b4f33 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -6,10 +6,14 @@ description: 'cert-manager usage: Certificates' > **apiVersion:** cert-manager.io/v1 > **kind:** Certificate -In cert-manager, the [`Certificate`](../concepts/certificate.md) resource -represents a human readable definition of a certificate request that is to be -honored by an issuer which is to be kept up-to-date. This is the usual way that -you will interact with cert-manager to request signed certificates. +In cert-manager, the `Certificate` resource represents a human readable definition +of a certificate request. cert-manager uses this input to generate a private key +and [`CertificateRequest`](./certificaterequest.md) resource in order to obtain +a signed certificate from an [`Issuer`](../configuration/README.md) or +[`ClusterIssuer`](../configuration/README.md). The signed certificate and private +key are then stored in the specified `Secret` resource. cert-manager will ensure +that the certificate is [auto-renewed before it expires](#renewal-reissuance) and +[re-issued if requested](#non-renewal-reissuance). In order to issue any certificates, you'll need to configure an [`Issuer`](../configuration/README.md) or [`ClusterIssuer`](../configuration/README.md) @@ -121,7 +125,7 @@ A full list of the fields supported on the Certificate resource can be found in the [API reference documentation](../reference/api-docs.md#cert-manager.io/v1.CertificateSpec). -## X.509 key usages and extended key usages +### X.509 key usages and extended key usages cert-manager supports requesting certificates that have a number of [custom key usages](https://tools.ietf.org/html/rfc5280#section-4.2.1.3) and [extended key @@ -138,8 +142,141 @@ certificate does not match the current key usage set. An exhaustive list of supported key usages can be found in the [API reference documentation](../reference/api-docs.md#cert-manager.io/v1.KeyUsage). + +### Additional Certificate Output Formats + +
+ +⛔️ The additional certificate output formats feature is currently in an +_experimental_ alpha state, and is subject to breaking changes or complete +removal in future releases. This feature is only enabled by adding it to the +`--feature-gates` flag on the cert-manager controller and webhook components: + +```bash +--feature-gates=AdditionalCertificateOutputFormats=true +``` + +
+ +`additionalOutputFormats` is a field on the Certificate `spec` that allows +specifying additional supplementary formats of issued certificates and their +private key. There are currently two supported additional output formats: +`CombinedPEM` and `DER`. Both output formats can be specified on the same +Certificate. + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +spec: + ... + secretName: my-cert-tls + additionalOutputFormats: + - type: CombinedPEM + - type: DER + +# Results in: + +apiVersion: v1 +kind: Secret +metadata: + name: my-cert-tls +type: kubernetes.io/tls +data: + ca.crt: + tls.key: + tls.crt: + tls-combined.pem: + key.der: +``` + +#### `CombinedPEM` + +The `CombinedPEM` type will create a new key entry in the resulting +Certificate's Secret `tls-combined.pem`. This entry will contain the PEM encoded +private key, followed by at least one new line character, followed by the PEM +encoded signed certificate chain- + +```text + + "\n" + +``` + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-cert-tls +type: kubernetes.io/tls +data: + tls-combined.pem: + ... +``` + +#### `DER` + +The `DER` type will create a new key entry in the resulting Certificate's Secret +`key.der`. This entry will contain the DER binary format of the private key. + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-cert-tls +type: kubernetes.io/tls +data: + key.der: + ... +``` + +## Issuance triggers + + +### Renewal-triggered reissuance + +cert-manager will automatically renew `Certificate`s. It will calculate _when_ to renew a `Certificate` based on the issued X.509 certificate's duration and a 'renewBefore' value which specifies _how long_ before expiry a certificate should be renewed. + +`spec.duration` and `spec.renewBefore` fields on a `Certificate` can be used to specify an X.509 certificate's duration and a 'renewBefore' value. Default value for `spec.duration` is 90 days. Some issuers might be configured to only issue certificates with a set duration, so the actual duration may be different. +Minimum value for `spec.duration` is 1 hour and minimum value for `spec.renewBefore` is 5 minutes. +It is also required that `spec.duration` > `spec.renewBefore`. + +Once an X.509 certificate has been issued, cert-manager will calculate the renewal time for the `Certificate`. By default this will be 2/3 through the X.509 certificate's duration. If `spec.renewBefore` has been set, it will be `spec.renewBefore` amount of time before expiry. cert-manager will set `Certificate`'s `status.RenewalTime` to the time when the renewal will be attempted. + + + +### Non-renewal-triggered reissuance + +Setting the `rotationPolicy: Always` won't rotate the private key immediately. +In order to rotate the private key, the certificate objects must be reissued. A +certificate object is reissued under the following circumstances: + +- when the X.509 certificate is nearing expiry, which is when the Certificate's + `status.renewalTime` is reached; +- when a change is made to one of the following fields on the Certificate's + spec: `commonName`, `dnsNames`, `ipAddresses`, `uris`, `emailAddresses`, + `subject`, `isCA`, `usages`, `duration` or `issuerRef`; +- when a reissuance is manually triggered with the following: + ```sh + cmctl renew cert-1 + ``` + Note that the above command requires [cmctl](../reference/cmctl.md#renew). + +
+ +**❌** Deleting the Secret resource associated with a Certificate resource is +**not a recommended solution** for manually rotating the private key. The +recommended way to manually rotate the private key is to trigger the reissuance +of the Certificate resource with the following command (requires +[`cmctl`](../reference/cmctl.md#renew)): + +```sh +cmctl renew cert-1 +``` + +
+ +## Issuance behavior + -## Temporary Certificates while Issuing +### Temporary Certificates while Issuing When requesting certificates [using the ingress-shim](./ingress.md), the component `ingress-gce`, if used, requires that a temporary certificate is @@ -161,13 +298,12 @@ Adding the following annotation on an ingress will automatically set "issue-temp ``` -## Rotation of the private key +### Rotation of the private key By default, the private key won't be rotated automatically. Using the setting `rotationPolicy: Always`, the private key Secret associated with a Certificate -object can be configured to be rotated as soon as an action triggers the -reissuance of the Certificate object (see -[Actions that will trigger a rotation of the private key](#actions-triggering-private-key-rotation) below). +object can be configured to be rotated as soon as an the Certificate is reissued (see +[Issuance triggers](#issuance-triggers)). With `rotationPolicy: Always`, cert-manager waits until the Certificate object is correctly signed before overwriting the `tls.key` file in the @@ -207,39 +343,7 @@ spec: rotationPolicy: Always # 🔰 Here. ``` - -### Actions that will trigger a rotation of the private key - -Setting the `rotationPolicy: Always` won't rotate the private key immediately. -In order to rotate the private key, the certificate objects must be reissued. A -certificate object is reissued under the following circumstances: - -- when the X.509 certificate is nearing expiry, which is when the Certificate's - `status.renewalTime` is reached; -- when a change is made to one of the following fields on the Certificate's - spec: `commonName`, `dnsNames`, `ipAddresses`, `uris`, `emailAddresses`, - `subject`, `isCA`, `usages`, `duration` or `issuerRef`; -- when a reissuance is manually triggered with the following: - ```sh - cmctl renew cert-1 - ``` - Note that the above command requires [cmctl](../reference/cmctl.md#renew). - -
- -**❌** Deleting the Secret resource associated with a Certificate resource is -**not a recommended solution** for manually rotating the private key. The -recommended way to manually rotate the private key is to trigger the reissuance -of the Certificate resource with the following command (requires -[`cmctl`](../reference/cmctl.md#renew)): - -```sh -cmctl renew cert-1 -``` - -
- -### The `rotationPolicy` setting +#### The `rotationPolicy` setting The possible values for `rotationPolicy` are: @@ -280,100 +384,6 @@ The `Secret` needs to be manually deleted if it is no longer needed. If you would prefer the `Secret` to be deleted automatically when the `Certificate` is deleted, you need to configure your installation to pass the `--enable-certificate-owner-ref` flag to the controller. -## Renewal - -cert-manager will automatically renew `Certificate`s. It will calculate _when_ to renew a `Certificate` based on the issued X.509 certificate's duration and a 'renewBefore' value which specifies _how long_ before expiry a certificate should be renewed. - -`spec.duration` and `spec.renewBefore` fields on a `Certificate` can be used to specify an X.509 certificate's duration and a 'renewBefore' value. Default value for `spec.duration` is 90 days. Some issuers might be configured to only issue certificates with a set duration, so the actual duration may be different. -Minimum value for `spec.duration` is 1 hour and minimum value for `spec.renewBefore` is 5 minutes. -It is also required that `spec.duration` > `spec.renewBefore`. - -Once an X.509 certificate has been issued, cert-manager will calculate the renewal time for the `Certificate`. By default this will be 2/3 through the X.509 certificate's duration. If `spec.renewBefore` has been set, it will be `spec.renewBefore` amount of time before expiry. cert-manager will set `Certificate`'s `status.RenewalTime` to the time when the renewal will be attempted. - -## Additional Certificate Output Formats - -
- -⛔️ The additional certificate output formats feature is currently in an -_experimental_ alpha state, and is subject to breaking changes or complete -removal in future releases. This feature is only enabled by adding it to the -`--feature-gates` flag on the cert-manager controller and webhook components: - -```bash ---feature-gates=AdditionalCertificateOutputFormats=true -``` - -
- -`additionalOutputFormats` is a field on the Certificate `spec` that allows -specifying additional supplementary formats of issued certificates and their -private key. There are currently two supported additional output formats: -`CombinedPEM` and `DER`. Both output formats can be specified on the same -Certificate. - -```yaml -apiVersion: cert-manager.io/v1 -kind: Certificate -spec: - ... - secretName: my-cert-tls - additionalOutputFormats: - - type: CombinedPEM - - type: DER - -# Results in: - -apiVersion: v1 -kind: Secret -metadata: - name: my-cert-tls -type: kubernetes.io/tls -data: - ca.crt: - tls.key: - tls.crt: - tls-combined.pem: - key.der: -``` - -#### `CombinedPEM` - -The `CombinedPEM` type will create a new key entry in the resulting -Certificate's Secret `tls-combined.pem`. This entry will contain the PEM encoded -private key, followed by at least one new line character, followed by the PEM -encoded signed certificate chain- - -```text - + "\n" + -``` - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: my-cert-tls -type: kubernetes.io/tls -data: - tls-combined.pem: - ... -``` - -#### `DER` - -The `DER` type will create a new key entry in the resulting Certificate's Secret -`key.der`. This entry will contain the DER binary format of the private key. - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: my-cert-tls -type: kubernetes.io/tls -data: - key.der: - ... -``` - ## Inner workings diagram for developers From 5c342f44aef13f1e32bbb0df3944c2378f152576 Mon Sep 17 00:00:00 2001 From: Tim Ramlot <42113979+inteon@users.noreply.github.com> Date: Wed, 18 Oct 2023 12:29:33 +0200 Subject: [PATCH 2/3] improve reissuance titles & content Signed-off-by: Tim Ramlot <42113979+inteon@users.noreply.github.com> --- content/docs/usage/certificate.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md index 9b0bf9b4f33..fae7d74cebc 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -230,7 +230,7 @@ data: ## Issuance triggers -### Renewal-triggered reissuance +### Reissuance triggered by expiry (renewal) cert-manager will automatically renew `Certificate`s. It will calculate _when_ to renew a `Certificate` based on the issued X.509 certificate's duration and a 'renewBefore' value which specifies _how long_ before expiry a certificate should be renewed. @@ -242,14 +242,10 @@ Once an X.509 certificate has been issued, cert-manager will calculate the renew -### Non-renewal-triggered reissuance +### Reissuance triggered by user actions -Setting the `rotationPolicy: Always` won't rotate the private key immediately. -In order to rotate the private key, the certificate objects must be reissued. A -certificate object is reissued under the following circumstances: +A certificate object is reissued under the following circumstances: -- when the X.509 certificate is nearing expiry, which is when the Certificate's - `status.renewalTime` is reached; - when a change is made to one of the following fields on the Certificate's spec: `commonName`, `dnsNames`, `ipAddresses`, `uris`, `emailAddresses`, `subject`, `isCA`, `usages`, `duration` or `issuerRef`; From beca28894e68c4f63d812a57cc1b1b4f08f9a219 Mon Sep 17 00:00:00 2001 From: Tim Ramlot <42113979+inteon@users.noreply.github.com> Date: Wed, 25 Oct 2023 15:47:35 +0200 Subject: [PATCH 3/3] link to details about reissuance & flatten title structure Signed-off-by: Tim Ramlot <42113979+inteon@users.noreply.github.com> --- content/docs/usage/certificate.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/docs/usage/certificate.md b/content/docs/usage/certificate.md index fae7d74cebc..b3998619f68 100644 --- a/content/docs/usage/certificate.md +++ b/content/docs/usage/certificate.md @@ -249,6 +249,7 @@ A certificate object is reissued under the following circumstances: - when a change is made to one of the following fields on the Certificate's spec: `commonName`, `dnsNames`, `ipAddresses`, `uris`, `emailAddresses`, `subject`, `isCA`, `usages`, `duration` or `issuerRef`; + A more detailed explanation can be found on the [FAQ page](../faq/README.md#when-do-certs-get-re-issued). - when a reissuance is manually triggered with the following: ```sh cmctl renew cert-1 @@ -269,10 +270,8 @@ cmctl renew cert-1 -## Issuance behavior - -### Temporary Certificates while Issuing +## Issuance behavior: Temporary Certificates while Issuing When requesting certificates [using the ingress-shim](./ingress.md), the component `ingress-gce`, if used, requires that a temporary certificate is @@ -294,7 +293,7 @@ Adding the following annotation on an ingress will automatically set "issue-temp ``` -### Rotation of the private key +## Issuance behavior: Rotation of the private key By default, the private key won't be rotated automatically. Using the setting `rotationPolicy: Always`, the private key Secret associated with a Certificate