Virtualization

How to Deploy cert-manager with Let’s Encrypt on Kubernetes: Automated TLS for Ingress Resources

Aseem Kishore
23 min read

The Back Room Tech is reader-supported. We may earn a commission when you buy through links on our site. Learn more.

This guide sets up cert-manager with Let’s Encrypt on Kubernetes so your Ingress resources get trusted TLS certificates that renew on their own. You’ll install a current stable release of cert-manager (check the releases page and pin the exact version you use), prove the whole flow against the Let’s Encrypt staging server, then switch to production. You’ll also learn the debugging model most tutorials skip: following the chain from Certificate to CertificateRequest to Order to Challenge.

The short version: install cert-manager with Helm or the static manifest. Create a staging ClusterIssuer, then add one annotation and a tls block to your Ingress. When kubectl describe certificate shows Ready: True, repeat with a production ClusterIssuer. If issuance stalls, run kubectl describe on each resource in the chain, top to bottom. The first one with a bad status or warning event holds the real error.

What Is cert-manager?

cert-manager is an open-source Kubernetes controller. It manages the full lifecycle of TLS certificates inside a cluster. It requests certificates from a Certificate Authority (CA), proves you own the domain, and stores the signed certificate in a Kubernetes Secret. It also renews certificates before they expire. Your Ingress controller reads that Secret. With the controller healthy and automatic renewal enabled, cert-manager handles reissuance; verify how your Ingress controller reloads changed certificates rather than assuming every deployment is interruption-free.

Let’s Encrypt is the usual pairing. It’s a free, automated CA that speaks ACME (Automatic Certificate Management Environment). Neither cert-manager nor Let’s Encrypt costs anything. Let’s Encrypt does enforce published rate limits, though. That’s why this guide starts on staging.

cert-manager has no GUI. Everything is Kubernetes YAML plus kubectl, Helm, and the optional cmctl CLI.

HTTP-01 vs DNS-01: Which Validation Do You Need?

Let’s Encrypt has to confirm that you control a domain before it signs a certificate for it. cert-manager supports two ways to do this:

HTTP-01DNS-01
How it proves ownershipServes a token at http://your-domain/.well-known/acme-challenge/...Creates a _acme-challenge TXT record in your DNS zone
Needs public port 80YesNo
Wildcard certs (*.example.com)Not supportedSupported
Works for private/VPN-only clustersNoYes
Extra setupNone beyond a working IngressDNS provider API credentials, plus a webhook for many providers

Use HTTP-01 for public services behind a load balancer. Use DNS-01 if you need wildcards or your cluster isn’t reachable from the internet. That second case covers homelabs behind a VPN or private VLAN. DNS-01 still needs a publicly registered domain you control and publicly queryable authoritative challenge TXT records; it does not make internal-only names eligible for a public certificate.

Prerequisites

  • A working Kubernetes cluster, plus a kubeconfig with cluster-admin rights. cert-manager installs CRDs (Custom Resource Definitions) and cluster-scoped RBAC.
  • kubectl installed and pointed at the correct context
  • Helm 3.x, if you choose the Helm install path
  • An Ingress controller already installed and serving traffic. This walkthrough uses Ingress resources; a Gateway API deployment needs its own configuration and is not a drop-in substitute.
  • For HTTP-01: a public DNS A/AAAA record, such as app.example.com, that points at your Ingress load balancer IP, with port 80 open from the internet
  • For DNS-01: API credentials for a DNS provider that cert-manager supports, either built in or through a webhook
  • Outbound HTTPS from the cluster to Let’s Encrypt’s ACME endpoints
  • A real email address for the ACME account, which Let’s Encrypt uses for account notices
RequirementDetails
cert-managerPin the exact version from the releases page before installing; this guide uses a <CERT_MANAGER_VERSION> placeholder in commands
Helm3.x (optional)
Workstation OSLinux (Ubuntu/Debian), macOS, or Windows 10/11 with PowerShell
Kubernetes versionCheck the supported releases page for compatibility with whichever cert-manager version you choose before installing

Note on versions: cert-manager ships often. Check the GitHub releases page for the current release before you install, and copy that exact version string into the commands below in place of <CERT_MANAGER_VERSION>. Pin the version either way, so a later helm upgrade can’t change it behind your back.

A Note on ingress-nginx and Controller Choice

Many older cert-manager examples assume ingress-nginx with an IngressClass of nginx. That includes parts of the official HTTP-01 tutorial. Before you build a new cluster on ingress-nginx, check the project’s current maintenance status on kubernetes.io and in the ingress-nginx repository. For new deployments, pick an actively maintained Ingress controller or a Gateway API implementation. cert-manager works with either.

This guide uses a placeholder, YOUR_INGRESS_CLASS, so you can plug in whatever you actually run. Find yours with this command:

kubectl get ingressclass

Example output (your names will differ):

NAME      CONTROLLER                      PARAMETERS   AGE
traefik   traefik.io/ingress-controller   <none>       41d

The value in the NAME column goes into ingressClassName.

Step-by-Step Guide

Step 1: Install kubectl, Helm, and cmctl on Your Workstation

kubectl and Helm do the install. cmctl is cert-manager’s optional CLI. It’s handy for checking status and forcing renewals. Keep it to those jobs. Its cmctl x install subcommand is experimental, so install with Helm or the static manifest instead.

Linux (Ubuntu 24.04 / Debian)

# --classic gives the snap full filesystem access, which kubectl and helm need to read ~/.kube/config
sudo snap install kubectl --classic
sudo snap install helm --classic

kubectl version --client
helm version

For cmctl, download the Linux binary from the cmctl releases on GitHub. Put it somewhere on your PATH, such as /usr/local/bin.

Ubuntu 24.04 terminal window showing successful output of kubectl version --client and helm version

macOS

brew install kubectl
brew install helm
brew install cmctl

kubectl version --client
helm version
macOS Terminal showing Homebrew installing kubectl and Helm, followed by consistent client version output.

Windows (PowerShell)

# -e forces an exact match on the package ID
winget install -e --id Kubernetes.kubectl
winget install -e --id Helm.Helm

kubectl version --client
helm version

Close and reopen PowerShell after installing so it picks up the new PATH. For cmctl, download the Windows build from the cmctl releases page.

Windows PowerShell window showing winget installing Kubernetes.kubectl and Helm.Helm, then version output

Windows tip: Every manifest here is saved to a file and applied with kubectl apply -f. That works the same in PowerShell, bash, and zsh, so you don’t need any cat <<EOF heredoc tricks.

Step 2: Confirm You’re Talking to the Right Cluster

This takes 10 seconds. It saves you from the classic mistake of installing into the wrong cluster.

kubectl config current-context
kubectl cluster-info

Expected output:

my-cluster
Kubernetes control plane is running at https://203.0.113.10:6443
CoreDNS is running at https://203.0.113.10:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

If the context is wrong, switch it with kubectl config use-context CONTEXT_NAME.

Step 3: Install cert-manager

Pick one of these methods. Helm is easier to upgrade later. The static manifest has fewer moving parts.

Option A: Helm

The current Helm installation documentation recommends its OCI registry. The Jetstack HTTP repository below remains a documented alternative, though new releases may arrive there later. These examples use that alternative consistently.

# --force-update refreshes the repo index if you added jetstack before
helm repo add jetstack https://charts.jetstack.io --force-update

# Confirm the chart version exists before pinning it
helm search repo jetstack/cert-manager --versions

Confirm that the version you plan to use shows up in the list with a matching APP VERSION. Then install:

# --namespace/--create-namespace put everything in a dedicated cert-manager namespace
# --version pins the chart so future runs don't silently upgrade
# --set crds.enabled=true installs the Certificate, Issuer, Order, Challenge, etc. CRDs with the chart (older chart releases used --set installCRDs=true instead)
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version <CERT_MANAGER_VERSION> \
  --set crds.enabled=true

On Windows PowerShell, put the command on one line or replace each \ with a backtick (` “).

Check the CRD flag for your version: Recent cert-manager Helm charts use crds.enabled=true to install CRDs; older chart releases used installCRDs=true. If Helm prints a deprecation warning for either flag, use the form the installation docs show for your pinned version.

Illustrative output (trimmed; timestamps and chart notes vary):

NAME: cert-manager
LAST DEPLOYED: Thu Oct 29 09:14:02 2026
NAMESPACE: cert-manager
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
cert-manager v1.21.3 has been deployed successfully!
Helm install command with crds.enabled=true and cert-manager v1.21.3 reporting deployed status.

Option B: Static Manifest

Replace <CERT_MANAGER_VERSION> below with the exact release tag, including its leading v (for example, v1.21.3), that you picked from the releases page:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<CERT_MANAGER_VERSION>/cert-manager.yaml

This single file includes the namespace, CRDs, RBAC, and the cert-manager, cainjector, and webhook components. You’ll see a long list of created lines ending with the webhook configuration.

Step 4: Verify the cert-manager Pods Are Running

kubectl get pods -n cert-manager

Expected output:

NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-6d5f8c9b7d-x2k4p              1/1     Running   0          58s
cert-manager-cainjector-7b9c6d8f4c-q8wzn   1/1     Running   0          58s
cert-manager-webhook-5c7d9f6b8b-m3tvh      1/1     Running   0          58s

The usual installation has these three components; pod names and workload layout can vary by release:

  • cert-manager: the main controller, which does the ACME work
  • cainjector: injects CA bundles into webhooks and API services
  • webhook: validates and mutates cert-manager resources when you apply them

Confirm that the webhook and cert-manager API are ready before creating an Issuer. A Pod’s Running phase alone does not establish readiness; use the API check below and investigate any failing readiness checks.

If you installed cmctl, it can confirm the API is actually ready. Check the cmctl reference for the current command syntax and flags:

cmctl check api

Expected output:

The cert-manager API is ready
Output of kubectl get pods -n cert-manager showing cert-manager, cert-manager-cainjector, and cert-manager-webhook pods all 1/1 Running

Step 5: Create a Let’s Encrypt Staging ClusterIssuer

A ClusterIssuer defines how to get certificates: which ACME server, which account key, and which solver. It’s cluster-scoped, so an Ingress in any namespace can use it. A namespaced Issuer does the same job inside one namespace.

Why staging first? Let’s Encrypt production limits are strict. The published limits allow up to 50 certificates per registered domain per 7 days. Let’s Encrypt also limits how often you can request a certificate for the exact same set of hostnames; check the current rate limits page for that specific number. A few rounds of “delete, retry, delete, retry” can lock a hostname out for days.

Staging runs the same ACME flow with far looser limits. Its certificates come from an untrusted test CA, which is fine while you’re debugging.

Let’s Encrypt has also signaled upcoming changes to rate limits and certificate lifetimes in a public announcement. Check the current numbers and dates there before you plan bulk issuance.

Save this as clusterissuer-staging.yaml. The staging directory URL below matches the current public staging endpoint; double-check it against the cert-manager ACME configuration docs if you hit connection errors:

# clusterissuer-staging.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    # Let's Encrypt STAGING directory — untrusted certs, relaxed rate limits
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: [email protected]
    # cert-manager generates an ACME account key and stores it in this Secret
    privateKeySecretRef:
      name: letsencrypt-staging-account-key
    solvers:
      - http01:
          ingress:
            # Must match `kubectl get ingressclass` exactly
            ingressClassName: YOUR_INGRESS_CLASS

Replace [email protected] and YOUR_INGRESS_CLASS, then apply the file:

kubectl apply -f clusterissuer-staging.yaml
kubectl get clusterissuer

Expected output:

NAME                  READY   AGE
letsencrypt-staging   True    12s

READY: True means cert-manager considers the issuer functional, which includes successfully registering (or reusing) an ACME account with the staging server. If it shows False, run kubectl describe clusterissuer letsencrypt-staging. The usual causes are a typo in the server URL or no outbound internet access.

Output of kubectl get clusterissuer showing letsencrypt-staging with READY column True

Step 6: Deploy a Test App and an Ingress with TLS (HTTP-01)

You need something to secure. A throwaway nginx Deployment works fine.

kubectl create namespace tls-demo
kubectl create deployment web --image=nginx --namespace tls-demo
kubectl expose deployment web --port=80 --namespace tls-demo

Before you continue, make sure DNS resolves to your Ingress load balancer:

nslookup app.example.com

The answer must match the external IP of your Ingress controller’s Service. If it doesn’t, HTTP-01 will fail. Nothing cert-manager does can fix that.

Now save the Ingress as ingress-web.yaml:

# ingress-web.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  namespace: tls-demo
  annotations:
    # Tells cert-manager's ingress-shim to create a Certificate for the tls block below
    cert-manager.io/cluster-issuer: letsencrypt-staging
spec:
  ingressClassName: YOUR_INGRESS_CLASS
  tls:
    - hosts:
        - app.example.com
      # cert-manager creates and keeps updating this Secret
      secretName: web-tls
  rules:
    - host: app.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80
kubectl apply -f ingress-web.yaml

The annotation key matters. Use cert-manager.io/cluster-issuer for a ClusterIssuer. Use cert-manager.io/issuer for a namespaced Issuer, which must live in the same namespace as the Ingress. A scope or name mismatch can prevent successful issuance. Inspect the Ingress and Certificate events rather than assuming it will fail silently.

During validation, cert-manager starts a temporary cm-acme-http-solver Pod. It also creates a temporary Ingress that routes /.well-known/acme-challenge/ to that Pod. Both go away when the Challenge succeeds. The HTTP-01 tutorial walks through this flow in more detail.

Step 7: Follow the Certificate → CertificateRequest → Order → Challenge Chain

This is the debugging model to remember. An ACME issuance commonly involves four resource types. An Order can have multiple Challenges and requests can be retried; use the chain to locate the failing stage:

ResourceWhat it representsLifetime
CertificateYour desired state: “I want a cert for these hosts, stored in this Secret, from this issuer”Permanent, created by you or by the Ingress annotation
CertificateRequestOne concrete attempt to get that cert, including the CSR (Certificate Signing Request)One per issuance or renewal
OrderThe ACME order opened with Let’s Encrypt for those hostnamesOne per CertificateRequest
ChallengeOne domain-validation task (HTTP-01 or DNS-01) per hostname in the OrderTemporary; cleanup timing depends on controller and resource state

Watch the whole chain at once:

kubectl get certificate,certificaterequest,order,challenge -n tls-demo

Output a few seconds into issuance:

NAME                                  READY   SECRET    AGE
certificate.cert-manager.io/web-tls   False   web-tls   20s

NAME                                           APPROVED   DENIED   READY   ISSUER                REQUESTOR                                         AGE
certificaterequest.cert-manager.io/web-tls-1   True                False   letsencrypt-staging   system:serviceaccount:cert-manager:cert-manager   20s

NAME                                              STATE     AGE
order.acme.cert-manager.io/web-tls-1-1234567890   pending   19s

NAME                                                          STATE     DOMAIN            AGE
challenge.acme.cert-manager.io/web-tls-1-1234567890-987654   pending   app.example.com   18s

When validation passes, the Order becomes valid; successful Challenge and Order resources can remain while finalization and cleanup complete. The Certificate then shows READY True. If something’s stuck, move down the chain until you find the resource that stopped moving. That’s where the real error lives.

Step 8: Verify the Staging Certificate

kubectl describe certificate web-tls -n tls-demo

Look for this section near the bottom:

Status:
  Conditions:
    Last Transition Time:  2026-10-29T09:21:44Z
    Message:               Certificate is up to date and has not expired
    Observed Generation:   1
    Reason:                Ready
    Status:                True
    Type:                  Ready
  Not After:               ...
  Not Before:              ...
  Renewal Time:            ...
Events:
  Type    Reason     Age   From                                       Message
  ----    ------     ----  ----                                       -------
  Normal  Issuing    90s   cert-manager-certificates-trigger          Issuing certificate as Secret does not exist
  Normal  Requested  90s   cert-manager-certificates-request-manager  Created new CertificateRequest resource "web-tls-1"
  Normal  Issuing    45s   cert-manager-certificates-issuing          The certificate has been successfully issued
Certificate web-tls in namespace tls-demo uses letsencrypt-staging and reports Ready True.

cmctl gives a more compact summary of the whole chain:

cmctl status certificate web-tls -n tls-demo

Then check what the Ingress is actually serving:

# -k skips trust verification (expected for staging); -v prints the TLS handshake details
curl -kv https://app.example.com

Inspect the certificate chain to confirm the staging CA; the displayed issuer text varies by tool and chain. A browser trust warning is expected for staging, but does not by itself prove the intended certificate is being served. Verify the issuer and hostname; unrelated certificate errors can also cause warnings. On Windows, use curl.exe -kv https://app.example.com so PowerShell doesn’t call its curl alias.

Step 9: Create the Production ClusterIssuer

Once staging reaches Ready: True, your DNS, firewall, Ingress class, and solver config are all proven. Now create the production issuer. Save it as clusterissuer-prod.yaml:

# clusterissuer-prod.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    # Let's Encrypt PRODUCTION directory — trusted certs, strict rate limits
    server: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
    # Use a separate account key Secret from staging
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
      - http01:
          ingress:
            ingressClassName: YOUR_INGRESS_CLASS
kubectl apply -f clusterissuer-prod.yaml
kubectl get clusterissuer
NAME                  READY   AGE
letsencrypt-prod      True    8s
letsencrypt-staging   True    14m

Keep a separate staging configuration for later tests if needed, and manage its account key and cluster scope under your normal credential policy.

Step 10: Switch the Ingress to Production

Edit ingress-web.yaml and change the annotation:

    cert-manager.io/cluster-issuer: letsencrypt-prod

Apply the updated Ingress, then inspect kubectl get certificate web-tls -n tls-demo -o yaml and confirm spec.issuerRef.name is letsencrypt-prod and kind is ClusterIssuer. If it still names staging, troubleshoot the annotation and ingress-shim before continuing.

With the effective issuer reference correct, check cmctl renew --help for your installed version and run cmctl renew web-tls -n tls-demo to request reissuance. Watch for a new CertificateRequest naming the production issuer and a successful Ready condition. The resulting certificate replaces the contents of web-tls; do not delete the Secret.

kubectl apply -f ingress-web.yaml
kubectl get certificate -n tls-demo --watch

Watch the chain with kubectl describe certificate web-tls -n tls-demo and kubectl describe certificaterequest -n tls-demo if you want to see the new request progress. Press Ctrl+C once READY flips to True.

Run curl -v https://app.example.com again, this time without -k. The handshake should now complete with a trusted Let’s Encrypt issuer.

If cert-manager does not pick up the change, check cmctl renew --help for your installed version, then request reissuance with cmctl renew web-tls -n tls-demo and watch the CertificateRequest and Certificate status rather than deleting the Secret. Reserve kubectl delete secret for disposable test services — on anything serving real traffic, removing the live Secret drops TLS back to the Ingress controller’s default/fallback certificate until the new one is issued.

From here on, renewal is automatic. cert-manager renews ahead of expiry and writes the new cert into the same Secret.

Let’s Encrypt has signaled it’s moving toward shorter certificate lifetimes over time; see the current announcement for specifics. Automated renewal matters more as that happens, and you don’t need to change anything in this setup to keep up.

Step 11 (Optional): DNS-01 for Wildcards and Private Clusters

Use DNS-01 when you need *.example.com, or when Let’s Encrypt can’t reach your cluster on port 80. That includes homelab services that are only reachable over WireGuard or Tailscale.

DNS-01 setup depends on your provider. cert-manager supports some DNS providers directly. Others need a community or vendor webhook that you install separately. The webhook’s own README lists the credentials and config fields it needs. Don’t guess those fields. Copy them from the provider’s documentation and the cert-manager docs.

The general shape looks like this. Every value in caps comes from your provider’s docs:

# clusterissuer-dns01-staging.yaml — structure only; fill values from your provider's webhook docs
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging-dns
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-staging-dns-account-key
    solvers:
      - selector:
          # Only use this solver for names in this zone
          dnsZones:
            - example.com
        dns01:
          webhook:
            groupName: YOUR_WEBHOOK_GROUP_NAME
            solverName: YOUR_WEBHOOK_SOLVER_NAME
            config: {}   # provider-specific — see the webhook's README

Then request a wildcard certificate directly with a Certificate resource:

# certificate-wildcard.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: wildcard-example-com
  namespace: tls-demo
spec:
  secretName: wildcard-example-com-tls
  issuerRef:
    name: letsencrypt-staging-dns
    # kind defaults to Issuer if omitted — set it explicitly for a ClusterIssuer
    kind: ClusterIssuer
  dnsNames:
    - example.com
    - "*.example.com"

The staging-first rule applies here too. Get Ready: True on staging, then switch issuerRef.name to a production DNS-01 issuer. While a DNS-01 Challenge is pending, check for the TXT record with nslookup -type=TXT _acme-challenge.example.com.

Configuration

These are the settings you’ll touch most often:

SettingWhereWhat it does
spec.acme.serverClusterIssuer/IssuerACME directory URL. Staging: https://acme-staging-v02.api.letsencrypt.org/directory. Production: https://acme-v02.api.letsencrypt.org/directory. Confirm current values against Let’s Encrypt’s documentation if issuance can’t reach the server. There is no default.
spec.acme.privateKeySecretRef.nameClusterIssuer/IssuerSecret that holds the ACME account key. Use a different one per issuer.
solvers[].http01.ingress.ingressClassNameClusterIssuer/IssuerIngressClass used for the temporary challenge Ingress. It must match kubectl get ingressclass.
solvers[].http01.ingress.nameClusterIssuer/IssuerEdits an existing named Ingress instead of creating a temporary one
cert-manager.io/cluster-issuerIngress annotationUses a ClusterIssuer for that Ingress’s tls block
cert-manager.io/issuerIngress annotationUses a namespaced Issuer in the same namespace
issuerRef.kindCertificateDefaults to Issuer. Set it to ClusterIssuer explicitly when needed.
tls[].secretNameIngressSecret that cert-manager creates and keeps updated

Annotation vs explicit Certificate. The Ingress annotation is the easiest path when one Ingress maps to one cert. Write a Certificate resource yourself for wildcards or for certs shared across Ingresses. It’s also the cleaner choice when you want the TLS lifecycle in a separate file from routing.

Gateway API. cert-manager can also issue certificates for Gateway API resources instead of classic Ingress. If you’re choosing a controller today, this is the forward-looking path. The setup differs from the Ingress annotation flow, so follow the Gateway section of the cert-manager docs for your version.

Tips and Troubleshooting

Quick Diagnostic Order

When a certificate isn’t Ready, run these in order. Stop at the first one that shows a warning:

kubectl describe certificate web-tls -n tls-demo
kubectl describe certificaterequest -n tls-demo
kubectl describe order -n tls-demo
kubectl describe challenge -n tls-demo
kubectl logs -n cert-manager deploy/cert-manager --tail=100

cmctl status certificate web-tls -n tls-demo collapses most of this into one view.

Challenge Stuck in pending

Symptom:

kubectl describe challenge -n tls-demo
Status:
  Presented:   true
  Processing:  true
  Reason:      Waiting for HTTP-01 challenge propagation: failed to perform self check GET request 'http://app.example.com/.well-known/acme-challenge/...': Get "http://app.example.com/.well-known/acme-challenge/...": dial tcp 198.51.100.7:80: i/o timeout
  State:       pending
Events:
  Type    Reason     Age   From                     Message
  ----    ------     ----  ----                     -------
  Normal  Started    3m    cert-manager-challenges  Challenge scheduled for processing
  Normal  Presented  3m    cert-manager-challenges  Presented challenge using HTTP-01 challenge mechanism
ACME Challenge in tls-demo remains pending because the HTTP-01 propagation self-check failed.

Why it happens: Before it asks Let’s Encrypt to validate, cert-manager checks that it can fetch the token itself. That self-check fails when DNS points at the wrong IP, port 80 is blocked, or the wrong controller handles the temporary challenge Ingress.

Fix:

  • Confirm that nslookup app.example.com returns your Ingress load balancer’s external IP. Compare it with kubectl get svc -A for your controller’s Service.
  • Confirm that port 80 is open from the internet. That includes cloud security groups, your home router’s port forward, and any host firewall.
  • Check that ingressClassName in the issuer exactly matches kubectl get ingressclass.
  • Make sure no global HTTP-to-HTTPS redirect grabs /.well-known/acme-challenge/ before it reaches the solver Pod.
  • Check the IP in the error message. If it’s your own public IP and the cluster can’t reach it from inside, your router may not support NAT hairpinning. In that case, DNS-01 is often the easier route.

Ingress Has the Annotation but No Certificate Appears

Why it happens: The issuer name doesn’t exist, or you used the wrong annotation key for the issuer’s scope.

Fix: Run kubectl get clusterissuer or kubectl get issuer -n tls-demo and compare names character by character. Use cert-manager.io/cluster-issuer for ClusterIssuers and cert-manager.io/issuer for same-namespace Issuers. Also confirm the Ingress has a tls block with secretName. Without one, cert-manager has nothing to create.

Production Issuance Fails with a Rate-Limit Error

Why it happens: Repeated attempts against production used up the per-domain or duplicate-certificate limits (details).

Fix: Test with a separate staging Ingress and TLS Secret, preserving any valid certificate serving production. Fix the underlying issue and confirm Ready: True on staging. Follow the rate-limit response’s Retry-After before retrying production; capacity refills over time. Do not replace a live service’s trusted certificate with a staging certificate.

Wrong Controller Handles the Challenge (Multi-Controller Clusters)

Why it happens: ingressClassName is missing from the solver, or it names a different controller than the one serving the domain.

Fix: Set solvers[].http01.ingress.ingressClassName explicitly. If you run more than one controller, choose solver selectors deliberately using the supported dnsNames, dnsZones or matchLabels fields. Separate dnsNames selectors work only when the classes serve distinct names; they do not distinguish two controllers serving the same name.

An Extra Load Balancer or IP Appears During Validation

Why it happens: With ingressClassName, cert-manager creates a separate temporary Ingress. On some cloud setups, that can spin up another load balancer.

Fix: Use the solver’s name field instead. cert-manager then adds the challenge path to your existing Ingress and skips creating a new one (HTTP-01 configuration).

failed calling webhook "webhook.cert-manager.io"

Why it happens: You applied an Issuer before the cert-manager webhook was ready. Or a network policy or firewall blocks the API server from reaching it.

Fix: Wait for cmctl check api to succeed, then re-apply. On private clusters with strict control-plane firewalls, see the troubleshooting guide.

Useful Habits

  • Force a renewal for testing: cmctl renew web-tls -n tls-demo triggers reissuance without deleting the Secret. Do this against staging.
  • Version your issuer manifests in Git, and back up the ACME account-key Secrets separately. The ClusterIssuer YAML is easy to recreate from source control, but the account-key Secret is not: restoring the original Secret preserves your existing ACME account, while generating a new key creates a different account. Keep a secure backup of the account-key Secrets (for example, with a Kubernetes-aware backup tool or sealed-secrets) so you can restore the same account identity if the Secret is lost.
  • Watch your infrastructure, too. cert-manager can’t renew anything if the cluster is down when a renewal comes due. For a homelab cluster on a few mini PCs or a Raspberry Pi 5 node, a small UPS keeps a power blip from turning into a surprise expired certificate.

Wrapping Up

You now have cert-manager handing out Let’s Encrypt certificates for your Ingress resources. You built it staging first, so nothing you broke along the way cost you production rate limits. The habit worth keeping is the chain: when something stalls, walk Certificate → CertificateRequest → Order → Challenge with kubectl describe and stop at the first warning. More often than not, the culprit is DNS or port 80.

My take: HTTP-01 is the right default for anything public. Move to DNS-01 once you want wildcards or private services, and accept the extra webhook setup as the price. For new clusters, pair cert-manager with a maintained Ingress controller or a Gateway API implementation. Don’t copy older ingress-nginx examples as-is.

StepActionApplies To
1–2Install kubectl/Helm/cmctl, confirm contextLinux, macOS, Windows
3–4Install cert-manager (pinned version), verify podsAll clusters
5Create staging ClusterIssuerAll clusters
6–8Annotate Ingress, follow the chain, verify Ready: TrueHTTP-01 / public Ingress
9–10Create production issuer, switch overAll clusters
11DNS-01 solver and wildcard CertificateWildcards, private/homelab clusters

Resources