diff --git a/design/20220118.certificate-issuance-exponential-backoff.md b/design/20220118.certificate-issuance-exponential-backoff.md index b1ccb69ac..d63a2f8e6 100644 --- a/design/20220118.certificate-issuance-exponential-backoff.md +++ b/design/20220118.certificate-issuance-exponential-backoff.md @@ -73,7 +73,7 @@ Currently failed issuances are retried once an hour without a backoff or time li Exponential backoff will be implemented by exponentially increasing the delays between a failed issuance ([`Issuing` condition set to false in `certificates-issuing` controller](https://github.com/jetstack/cert-manager/blob/196d0011ca46037186a826365bcd6316d9b9462a/pkg/controller/certificates/issuing/issuing_controller.go#L341)) and a new issuance ([`Issuing` condition set to true in `certificates-trigger` controller](https://github.com/jetstack/cert-manager/blob/d5503c2ed2df272ec1bd94ebd223408fad29df1f/pkg/controller/certificates/trigger/trigger_controller.go#L184)). From a user perspective, this will correspond to the delay between a `CertificateRequest` having failed and new `CertificateRequest`s being created. -A new `IssuanceAttempts` status field will be added to `Certificate` that will be used to record the number of failed issuances for this [revision](https://github.com/jetstack/cert-manager/blob/5019aaacfcaa4da2cba32218fdf583eede00f224/pkg/apis/certmanager/v1/types_certificate.go#L411-L426). +A new `IssuanceAttempts` status field will be added to `Certificate` that will be used to record the number of consecutive failed issuances. Similarly to [`status.LastFailureTime`](https://github.com/jetstack/cert-manager/blob/196d0011ca46037186a826365bcd6316d9b9462a/pkg/apis/certmanager/v1/types_certificate.go#L385-L391), `status.IssuanceAttempts` field will only be set for a `Certificate` whose issuance is currently failing and will be removed after a successful issuance. `IssuanceAttempts` will be set by [`certificates-issuing` controller](https://github.com/jetstack/cert-manager/tree/ce1424162ea4f363bdb7aa4f201432ec63da1145/pkg/controller/certificates/issuing) after a failed issuance by either bumping the already existing value by 1 or setting it to 1 (first failure). In case of a succeeded issuance, `certificates-issuing` controller will ensure that `status.IssuanceAttempts` is not set. @@ -91,7 +91,7 @@ type CertificateStatus { // ... // NEW FIELDS - // IssuanceAttempts represents the number of times certificate issuance has been attempted and failed during this revision. + // IssuanceAttempts represents the number of consecutive failed issuances. // This field is used to calculate the backoff period after which issuance will be attempted again. IssuanceAttempts int `json:issuanceAttempts,omitempty` } @@ -103,7 +103,7 @@ Large part of the these examples show what is already the _current_ behaviour, t #### Issuance fails then succeeds: -1. A `CertificateRequest` with [revision number](https://github.com/jetstack/cert-manager/blob/196d0011ca46037186a826365bcd6316d9b9462a/pkg/apis/certmanager/v1/types_certificate.go#L409-L424) 20 fails. This is the 3rd failed issuance for this revision +1. A `CertificateRequest` fails. This is the 3rd failed issuance in a row 2. `certificates-issuing` controller reconciles the failed `CertificateRequest`, bumps the `status.IssuanceAttempts` by 1 as well as updating the `status.LastFailureTime` to the time when `CertificateRequest` failed and setting the [`Issuing` condition](https://github.com/jetstack/cert-manager/blob/196d0011ca46037186a826365bcd6316d9b9462a/pkg/apis/certmanager/v1/types_certificate.go#L480-L495) to false ([here-ish](https://github.com/jetstack/cert-manager/blob/196d0011ca46037186a826365bcd6316d9b9462a/pkg/controller/certificates/issuing/issuing_controller.go#L326-L351)) @@ -117,7 +117,7 @@ Large part of the these examples show what is already the _current_ behaviour, t #### Manually triggered reissuance succeeds -1. A `CertificateRequest` with revision 20 fails. This is the 3rd failed issuance for revision 20 +1. A `CertificateRequest` fails. This is the 3rd failed issuance in a row 2. `certificates-issuing` controller reconciles the failed `CertificateRequest`, bumps the `status.IssuanceAttempts` by 1 as well as updating the `status.LastFailureTime` to the time when `CertificateRequest` failed and setting the `Issuing` condition to false @@ -133,7 +133,7 @@ Large part of the these examples show what is already the _current_ behaviour, t #### Manually triggered reissuance fails -1. A `CertificateRequest` with revision 20 fails. This is the 3rd failed issuance for revision 20 +1. A `CertificateRequest` fails. This is the 3rd failed issuance in a row. 2. `certificates-issuing` controller reconciles the failed `CertificateRequest`, bumps the `status.IssuanceAttempts` by 1 as well as updating the `status.LastFailureTime` to the time when `CertificateRequest` failed and setting the `Issuing` condition to false @@ -152,7 +152,7 @@ Large part of the these examples show what is already the _current_ behaviour, t (These examples are based on what the statuses already look like after a failed/succeeded issuance. The only change is the `issuanceAttempts` field) -1. A `Certificate` where issuance has failed 3 times for revision 20: +1. A `Certificate` where issuance has failed 3 times in a row: ``` Status: Conditions: @@ -173,14 +173,14 @@ Status: RenewalTime: IssuanceAttempts: 3 LastFailureTime: # Last failed issuance (i.e when a `CertificateRequest` failed) - Revision: 19 # The latest succeeded revision. Currently we are attempting revision 20 + Revision: 19 Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning IssuanceFailed 4s cert-manager Certificate issuance has failed. It will be retried in 4 hours. ``` -2. A `Certificate` where the latest issuance for revision 20 succeeded and no issuances are being attempted now: +2. A `Certificate` where the latest issuance succeeded and no issuances are being attempted now: ``` Status: Conditions: