Document ACME delayed challenge acceptance

[wallrj]

Preview:

• https://deploy-preview-2101--cert-manager.netlify.app/docs/configuration/acme/#skip-the-self-check-with-waitinsteadofselfcheck
• https://deploy-preview-2101--cert-manager.netlify.app/docs/troubleshooting/acme/#http01-troubleshooting
• https://deploy-preview-2101--cert-manager.netlify.app/docs/releases/release-notes/release-notes-1.21#skip-the-self-check-with-waitinsteadofselfcheck

Summary

This PR documents the ACME waitInsteadOfSelfCheck solver option for the next minor cert-manager release.

It is documentation for cert-manager/cert-manager#8858, which supersedes cert-manager/cert-manager#8794 after review feedback that the feature should model an explicit self-check bypass rather than a hybrid self-check-plus-delay fallback. cert-manager/cert-manager#8858 is itself a follow-up to the earlier closed attempt in cert-manager/cert-manager#5006.

The docs explain:

• what problem this feature solves;
• when the option may be useful;
• the behavior when waitInsteadOfSelfCheck is set (self-check is skipped; cert-manager waits the configured duration from status.presentedAt before asking the ACME server to validate);
• that a value of 0 is permitted (skip the self-check and ask the ACME server to validate immediately, relying on the server's own validation retries per RFC 8555 section 8.2), and that negative durations are rejected by the validating webhook;
• an example Issuer / ClusterIssuer configuration;
• that the field is available on either http01 or dns01 solver entries;
• that the feature is available in cert-manager >= v1.21.0;
• how this fits into ACME troubleshooting; and
• a short release-note entry for the 1.21 docs.

Part of cert-manager/cert-manager#1292.

Cross-reference: cert-manager/cert-manager#8858.

[cert-manager-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hjoshi123 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[netlify]

✅ Deploy Preview for cert-manager ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	99e4988
🔍 Latest deploy log	https://app.netlify.com/projects/cert-manager/deploys/6a326c2a9823cd0008fb2193
😎 Deploy Preview	https://deploy-preview-2101--cert-manager.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[wallrj-cyberark]

The docs are clear and well-placed. Three points below, in descending order of priority.

On Copilot's finding about the YAML: the waitInsteadOfSelfCheck: 30s entry is at the correct indentation — it is a sibling of http01: within the solver list item, not nested inside it, which matches the API type definition. The text already says "You can set this field on either an http01 or dns01 solver entry", which makes the placement clear. No change needed there.

[wallrj-cyberark]

The DNS01 paragraph inserted immediately before this line (207–208) leaves If this does work check if your cluster can see it too. as a non-sequitur. That sentence was originally the continuation of the opening HTTP01 paragraph (First of all check if you can see the challenge URL from the public internet…), but after the insertion it reads as a follow-on to the DNS01 note.

Suggested fix: add a blank line between line 207 and this line so that If this does work… clearly starts a new paragraph and the reader understands this refers back to the challenge URL visibility check, not the DNS01 scenario:

 A similar issue can also affect DNS01 if cert-manager can only query internal
 DNS views while the ACME server validates against the public TXT record.
+
 If this does work check if your cluster can see it too.

[wallrj-cyberark]

Done — added a blank line in 777bd7d.

[wallrj-cyberark]

As noted in the code review of the implementation PR, setting waitInsteadOfSelfCheck: 0s causes cert-manager to accept the challenge on the first reconcile after presentation — with no self-check and no wait — because the deadline is PresentedAt + 0 = PresentedAt, which is always in the past. This may be intentional for users who want a pure bypass, but it is not mentioned anywhere in the docs.

If the implementation PR adds a validation marker to reject zero/negative durations, this becomes moot. Otherwise, consider adding a brief note here, e.g.:

Setting this field to 0s skips the self-check and accepts immediately after presentation.

Users who write waitInsteadOfSelfCheck: 0s expecting some kind of no-op would be surprised to find their challenges accepted without any check.

[wallrj-cyberark]

This was already addressed in the existing text (lines 138–143) which documents the 0 value behaviour and notes that negative durations are rejected by the validating webhook.

[wallrj-cyberark]

Nit: adding a DNS01 example (or a short mention of the equivalent YAML) would help readers who are in a split-horizon DNS scenario. The current text says the field works on either solver type, but the example only shows HTTP01. A comment like # or under dns01: instead of http01: next to waitInsteadOfSelfCheck: 30s in the code block would be a low-effort addition.

[wallrj-cyberark]

Done — added a YAML comment in the example noting dns01: as an alternative in 777bd7d.