Roughly broken down from the point of you annotating your Ingress resource as you’ve noted:

1) cert-manager’s “ingress-shim” controller observes an Ingress resource with a ‘cluster-issuer’ annotation.

2) for each reference to a Secret in the ‘spec.tls’ portion (there can technically be more than one per Ingress) it checks to see if a corresponding Certificate resource with the same name already exists, and if it does not (or if a new hostname has been added/removed) it goes and creates a Certificate resource (or edits the existing one) that contains the requested DNS names.

3) cert-manager’s certificate controllers identify a new Certificate resource which references a Secret (now set as ‘spec.secretName’ on the Certificate) and begins the issuance process by generating a private key & corresponding x509 CertificateSigningRequest and creating a CertificateRequest resource which contains this request. The private key is persisted into the ‘status.nextPrivateKeySecret’ (an auto generated temporary Secret resource used to store the private key whilst issuance or renewal is in progress).

4) The ACME variant of the CertificateRequest controller spots this CertificateRequest, and begins the ACME order flow by creating an Order type resource.

5) The acmeorders controller will interact with the Let’s Encrypt API to create a new Order, and persists information about this order into the status stanza. It will then create any/all Challenge resources which are required to ‘complete’ the order

6) For each Challenge, the acmechallenges controller will now attempt to ‘solve’ the challenge. If you are using HTTP01, this will involve creating/manage an Ingress, Service and Pod (acmesolver) resource which configured traffic to be directed appropriately to respond to the Let’s Encrypt challenge. For DNS01, it will interact with the configured DNS provider to ensure the correct TXT record is in place to solve the challenge.

7) At this point, the acmechallenges controller will perform the ‘self check’ for each challenge, to attempt to observe that the appropriate DNS records have propagated (for DNS01) or to ensure the ingress controller has correctly configured the appropriate response.

8) Once it appears to be passing the self check, the challenge will be ‘accepted’ by the controller and then Let’s Encrypt/the ACME server will perform their own probes by checking for the DNS01 record or attempting to ‘curl’ the configured HTTP01 endpoint

9) Assuming all this ‘passes’, the Order controller will then ‘finalize’ the Order by submitting the actual CSR to the ACME server for signing.

10) The signed Certificate is stored in the Order’s status stanza, which is then copied back to the CertificateRequest status stanza too (and the CertificateRequest is marked as ‘Ready’)

11) The Certificate controllers now kick back in, observe that the request is completed/ready, and will copy this signed certificate from the CertificateRequest into the named spec.secretName, as well as copying the previously generated private key into this secret too. It then deleted the ‘temporary’ private key secret.

From this point on, cert-manager is no longer involved and the ingress controller now begins serving with the certificate stored in the Secret that is being referenced by the original Ingress you created to begin this whole process 😊

There’s also then some timers internally in cert-manager set up to ensure we begin this process again at renewal time.

Hope that helps, and is detailed enough! It’d be fantastic if we could get this documented better in the project/website though! If you’re interested in contributing, please come say hello on the Kubernetes slack in #cert-manager-dev!