diff --git a/.spelling b/.spelling index 34740373cd5..edbd997ae5a 100644 --- a/.spelling +++ b/.spelling @@ -246,6 +246,8 @@ prepended retweets JetstackHQ acme-dns +andreas-p +renewBefore # As per https://tools.ietf.org/html/rfc5280, the spelling "X.509" is the # correct spelling. The spelling "x509" and "X509" are incorrect. diff --git a/content/en/docs/faq/_index.md b/content/en/docs/faq/_index.md index 559328c75df..027d1134b45 100644 --- a/content/en/docs/faq/_index.md +++ b/content/en/docs/faq/_index.md @@ -52,7 +52,7 @@ spec: ### If `renewBefore` or `duration` is not defined, what will be the default value? cert-manager will default to a `duration` of [90 days](https://github.com/jetstack/cert-manager/blob/v1.2.0/pkg/apis/certmanager/v1/const.go#L26) with a `renewBefore` of [30 days](https://github.com/jetstack/cert-manager/blob/v1.2.0/pkg/apis/certmanager/v1/const.go#L32). -If `renewBefore` is not set and the duration of the signed certificate is shorter or equal to 30 days, the `renewBefore` time will be set to 2/3 of the signed certificate validity duration. +The renewal time of the certificate will be calculated using the formula `min(duration / 3, renewBefore)`, see [renewal](../usage/certificate/#renewal) for more detail. When setting `duration` it is recommended to also set `renewBefore`, if `renewBefore` is longer than `duration` you will receive an error. ## Miscellaneous diff --git a/content/en/docs/release-notes/_index.md b/content/en/docs/release-notes/_index.md index f6f78c0c2a9..f4c4c992b1e 100644 --- a/content/en/docs/release-notes/_index.md +++ b/content/en/docs/release-notes/_index.md @@ -9,6 +9,7 @@ no_list: true Here you will find a link to all release notes for each version release of cert-manager: +- [`v1.4`](./release-notes-1.4/) - [`v1.3`](./release-notes-1.3/) - [`v1.2`](./release-notes-1.2/) - [`v1.1`](./release-notes-1.1/) diff --git a/content/en/docs/release-notes/release-notes-1.4.md b/content/en/docs/release-notes/release-notes-1.4.md new file mode 100644 index 00000000000..0f191fc187f --- /dev/null +++ b/content/en/docs/release-notes/release-notes-1.4.md @@ -0,0 +1,24 @@ +--- +title: "Release Notes" +linkTitle: "v1.4" +weight: 800 +type: "docs" +--- + +Special thanks to the external contributors who contributed to this release: + +* [@andreas-p](https://github.com/andreas-p) + +# Deprecated Features and Breaking Changes + +## Certificate renewal period calculation + +There have been slight changes in the renewal period calculation for +certificates. Renewal time (`rt`) is now calculated using formula `rt = notAfter - +rb` where `rb = min(renewBefore, cert duration / 3)`. (See [docs](/docs/usage/certificate/#renewal) for more +detailed explanation). Previously this was calculated using formula `rt = +notAfter - rb` where `if cert duration < renewBefore; then rb = cert duration +/ 3; else rb = renewBefore`. This change fixes a bug where, if a certificate's +duration is very slightly larger than `renewBefore` period, then a cert gets +renewed at `notAfter - renewBefore` which can lead to a continuous renewal loop, +see [`cert-manager#3897`](https://github.com/jetstack/cert-manager/issues/3897). \ No newline at end of file diff --git a/content/en/docs/usage/certificate.md b/content/en/docs/usage/certificate.md index dd4675ce284..6e54e78b5fc 100644 --- a/content/en/docs/usage/certificate.md +++ b/content/en/docs/usage/certificate.md @@ -16,7 +16,7 @@ In order to issue any certificates, you'll need to configure an ## Creating Certificate Resources -A `Certificate` resource specifies fields that are used to generated certificate +A `Certificate` resource specifies fields that are used to generate certificate signing requests which are then fulfilled by the issuer type you have referenced. `Certificates` specify which issuer they want to obtain the certificate from by specifying the `certificate.spec.issuerRef` field. @@ -91,15 +91,6 @@ The `Certificate` will be issued using the issuer named `ca-issuer` in the > from functioning correctly > [`#1269`](https://github.com/jetstack/cert-manager/issues/1269). -> Note: Take care when setting the `renewBefore` field to be very close to the -> `duration` as this can lead to a renewal loop, where the `Certificate` is always -> in the renewal period. Some `Issuers` set the `notBefore` field on their -> issued X.509 certificates before the issue time to fix clock-skew issues, -> leading to the working duration of a certificate to be less than the full -> duration of the certificate. For example, Let's Encrypt sets it to be one hour -> before issue time, so the actual *working duration* of the certificate is 89 -> days, 23 hours (the *full duration* remains 90 days). - A full list of the fields supported on the Certificate resource can be found in the [API reference documentation](../../reference/api-docs/#cert-manager.io/v1alpha2.CertificateSpec) @@ -173,3 +164,13 @@ This means that deleting a `Certificate` won't take down any services that are c 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 issued certificates. It will calculate _when_ to renew a certificate based on 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 custom duration and 'renewBefore' values for a certificate. Default values for these fields are 90 days and 30 days respectively. 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` so if you set `spec.duration` to a value smaller than 30 days (720 hours) you will also need to set `spec.renewBefore` to some smaller value. + +Once a certificate has been issued, `cert-manager` will calculate _how long_ before expiry a cert should be renewed using the formula `min(spec.renewBefore, actual_duration / 3)` and use this value to calculate _when_ a certificate should be renewed. `Certifcate`'s `status.RenewalTime` field will then be set to the time when renewal will be attempted. \ No newline at end of file