ACME Orders and Challenges

cert-manager supports requesting certificates from ACME servers, including from Let’s Encrypt, with use of the ACME Issuer. These certificates are typically trusted on the public Internet by most computers. To successfully request a certificate, cert-manager must solve ACME Challenges which are completed in order to prove that the client owns the DNS addresses that are being requested.

In order to complete these challenges, cert-manager introduces two CustomResource types; Orders and Challenges.

Orders

Order resources are used by the ACME issuer to manage the lifecycle of an ACME ‘order’ for a signed TLS certificate. More details on ACME orders and domain validation can be found on the Let’s Encrypt website here. An order represents a single certificate request which will be created automatically once a new CertificateRequest resource referencing an ACME issuer has been created. CertificateRequest resources are created automatically by cert-manager once a Certificate resource is created, has its specification changed, or needs renewal.

As an end-user, you will never need to manually create an Order resource. Once created, an Order cannot be changed. Instead, a new Order resource must be created.

The Order resource encapsulates multiple ACME ‘challenges’ for that ‘order’, and as such, will manage one or more Challenge resources.

Challenges

Challenge resources are used by the ACME issuer to manage the lifecycle of an ACME ‘challenge’ that must be completed in order to complete an ‘authorization’ for a single DNS name/identifier.

When an Order resource is created, the order controller will create Challenge resources for each DNS name that is being authorized with the ACME server.

As an end-user, you will never need to manually create a Challenge resource. Once created, a Challenge cannot be changed. Instead, a new Challenge resource must be created.

Challenge Lifecycle

After a Challenge resource has been created, it will be initially queued for processing. Processing will not begin until the challenge has been ‘scheduled’ to start. This scheduling process prevents too many challenges being attempted at once, or multiple challenges for the same DNS name being attempted at once. For more information on how challenges are scheduled, read the challenge scheduling.

Once a challenge has been scheduled, it will first be ‘synced’ with the ACME server in order to determine its current state. If the challenge is already valid, its ‘state’ will be updated to ‘valid’, and will also set status.processing = false to ‘unschedule’ itself.

If the challenge is still ‘pending’, the challenge controller will ‘present’ the challenge using the configured solver, one of HTTP01 or DNS01. Once the challenge has been ‘presented’, it will set status.presented = true.

Once ‘presented’, the challenge controller will perform a ‘self check’ to ensure that the challenge has ‘propagated’ (i.e. the authoritative DNS servers have been updated to respond correctly, or the changes to the ingress resources have been observed and in-use by the ingress controller).

If the self check fails, cert-manager will retry the self check with a fixed 10 second retry interval. Challenges that do not ever complete the self check will continue retrying until the user intervenes by either retrying the Order (by deleting the Order resource) or amending the associated Certificate resource to resolve any configuration errors.

Once the self check is passing, the ACME ‘authorization’ associated with this challenge will be ‘accepted’.

The final state of the authorization after accepting it will be copied across to the Challenge’s status.state field, as well as the ‘error reason’ if an error occurred whilst the ACME server attempted to validate the challenge.

Once a Challenge has entered the valid, invalid, expired or revoked state, it will set status.processing = false to prevent any further processing of the ACME challenge, and to allow another challenge to be scheduled if there is a backlog of challenges to complete.

Challenge Scheduling

Instead of attempting to process all challenges at once, challenges are ‘scheduled’ by cert-manager.

This scheduler applies a cap on the maximum number of simultaneous challenges as well as disallows two challenges for the same DNS name and solver type (HTTP01 or DNS01) to be completed at once.

The maximum number of challenges that can be processed at a time is 60 as of ddff78.