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-01 | DNS-01 | |
|---|---|---|
| How it proves ownership | Serves a token at http://your-domain/.well-known/acme-challenge/... | Creates a _acme-challenge TXT record in your DNS zone |
| Needs public port 80 | Yes | No |
Wildcard certs (*.example.com) | Not supported | Supported |
| Works for private/VPN-only clusters | No | Yes |
| Extra setup | None beyond a working Ingress | DNS 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.
kubectlinstalled 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
| Requirement | Details |
|---|---|
| cert-manager | Pin the exact version from the releases page before installing; this guide uses a <CERT_MANAGER_VERSION> placeholder in commands |
| Helm | 3.x (optional) |
| Workstation OS | Linux (Ubuntu/Debian), macOS, or Windows 10/11 with PowerShell |
| Kubernetes version | Check 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 laterhelm upgradecan’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.
macOS
brew install kubectl
brew install helm
brew install cmctl
kubectl version --client
helm version
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 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=trueto install CRDs; older chart releases usedinstallCRDs=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!
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
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.
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:
| Resource | What it represents | Lifetime |
|---|---|---|
| Certificate | Your 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 |
| CertificateRequest | One concrete attempt to get that cert, including the CSR (Certificate Signing Request) | One per issuance or renewal |
| Order | The ACME order opened with Let’s Encrypt for those hostnames | One per CertificateRequest |
| Challenge | One domain-validation task (HTTP-01 or DNS-01) per hostname in the Order | Temporary; 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
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:
| Setting | Where | What it does |
|---|---|---|
spec.acme.server | ClusterIssuer/Issuer | ACME 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.name | ClusterIssuer/Issuer | Secret that holds the ACME account key. Use a different one per issuer. |
solvers[].http01.ingress.ingressClassName | ClusterIssuer/Issuer | IngressClass used for the temporary challenge Ingress. It must match kubectl get ingressclass. |
solvers[].http01.ingress.name | ClusterIssuer/Issuer | Edits an existing named Ingress instead of creating a temporary one |
cert-manager.io/cluster-issuer | Ingress annotation | Uses a ClusterIssuer for that Ingress’s tls block |
cert-manager.io/issuer | Ingress annotation | Uses a namespaced Issuer in the same namespace |
issuerRef.kind | Certificate | Defaults to Issuer. Set it to ClusterIssuer explicitly when needed. |
tls[].secretName | Ingress | Secret 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
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.comreturns your Ingress load balancer’s external IP. Compare it withkubectl get svc -Afor 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
ingressClassNamein the issuer exactly matcheskubectl 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-demotriggers 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.
| Step | Action | Applies To |
|---|---|---|
| 1–2 | Install kubectl/Helm/cmctl, confirm context | Linux, macOS, Windows |
| 3–4 | Install cert-manager (pinned version), verify pods | All clusters |
| 5 | Create staging ClusterIssuer | All clusters |
| 6–8 | Annotate Ingress, follow the chain, verify Ready: True | HTTP-01 / public Ingress |
| 9–10 | Create production issuer, switch over | All clusters |
| 11 | DNS-01 solver and wildcard Certificate | Wildcards, private/homelab clusters |