Aller au contenu

Cert-manager Troubleshooting

Abstract

The new standard practice is to use the generic annotation on Ingress resources. This simplifies the configuration and centralizes the management of the Certificate Authority (Issuer).

metadata:
  annotations:
    kubernetes.io/tls-acme: "true"

If you are running into an issue with certificate generation, follow these diagnostic steps.

Tip

All kubectl commands should be run in the correct namespace where your application and Ingress are deployed. Use the -n <your-namespace> flag for each command.

1. Check the Status of cert-manager Resources#

When requesting a certificate, cert-manager creates several resources to validate the request (CertificateRequest, Order, Challenge). Inspecting these objects is the first thing to do to understand the root of the problem.

1.1. Get a Quick Overview#

Before diving into details, get a high-level view of all cert-manager resources. This single command helps you see if objects are being created and what their current status is.

kubectl get certificate,certificaterequest,order,challenge -n <namespace>

Look at the READY column. If it's False or empty, it indicates a problem. Also, check the AGE column to see how long the resource has existed.

⏳ How Long Should You Wait ?

Certificate issuance is not instant. It involves DNS propagation and validation by an external authority.

  • Normal Wait (2-5 minutes): It's common for the process to take a few minutes. If the resources are new, give them some time.

  • Time to Investigate (>10 minutes): If a resource remains in a Pending state or its READY status is False for more than 10 minutes, it's a clear sign of a problem. Proceed to the next step.

1.2. Describe the Certificate Resource#

If the overview shows a problem or you've been waiting too long, use describe to get detailed information and error messages.

Start with the Certificate resource. The certificate's name can usually be found in the tls section of your Ingress.

# Describe the main Certificate resource
kubectl describe certificate <certificate-name> -n <namespace>

Tip

Pay close attention to the Status and Events sections in the output. They will often tell you exactly what is wrong or point to the next resource you need to inspect (like a CertificateRequest or Order).

1.3. Analyze the CertificateRequest#

If the Certificate shows an issue, the next step is to inspect the associated CertificateRequest.

# First, list all CertificateRequests in the namespace to find the right one
kubectl get certificaterequest -n <namespace>

# Then, describe the specific request that is failing
kubectl describe certificaterequest <certificaterequest-name> -n <namespace>

Output

...
Status:
  Conditions:
    Last Transition Time:  2020-02-19T10:36:54Z
    Message:               Referenced issuer does not have a Ready status condition
    Reason:                Pending
    Status:                False
    Type:                  Ready
Events:                    <none>

Tip

A False or Pending status indicates a problem. The message often gives the reason (e.g., the default Issuer is not ready).

1.4. Examine Orders and Challenges#

Note

For ACME certificates (from providers like ZeroSSL or Let's Encrypt), you may need to go deeper and inspect the Order and Challenge resources.

# List and describe the Order
kubectl get order -n <namespace>
kubectl describe order <order-name> -n <namespace>

# List and describe the Challenge
kubectl get challenges -n <namespace>
kubectl describe challenge <challenge-name> -n <namespace>

Tip

The Challenge is particularly useful for DNS-related issues. Its events will show if cert-manager failed to create or verify the required DNS record (e.g., the TXT record).

2. Verify the Ingress Configuration#

If analyzing the cert-manager resources did not reveal the issue, double-check that your Ingress is configured correctly.

kubectl describe ingress <ingress-name> -n <namespace>

Check the following two sections in the output:

2.1. The kubernetes.io/tls-acme annotation#

Ensure that the annotation allowing cert-manager to automatically manage the certificate is present and set to "true".

metadata:
  name: ingress-example
  annotations:
    kubernetes.io/tls-acme: "true"

2.2. The tls section#

Verify that the hosts field is correct and that the secretName is defined. The certificate will be stored in this Secret.

tls:
  - hosts:
    - my-domain.example.com
    secretName: MY-SECRET-tls

You can then check if the Secret was successfully created:

kubectl get secret -n <namespace>

Tip

If the secret is not created or has a generated suffix, it confirms that the cert-manager failed to issue the certificate. Go back to step 1.

Knowledge Base: Common Errors#

_Cert-manager: DNS Error (SERVFAIL looking up TXT for _acme-challenge)#

Symptoms

Renewal fails, the CertificateRequest is False, and the Challenge log shows a DNS problem: SERVFAIL looking up TXT for _acme-challenge error. This is often related to slow DNS propagation or a misconfiguration.

Solution

Force the recreation of the certificate by deleting the Certificate resource. Cert-manager will create a new one, triggering a new challenge.

kubectl delete certificate <cert_name> -n <namespace>

CertmanagerCertificateExpiration Alert: Order Failed#

Symptoms

The certificate is not renewing because a previous Order failed and is blocking the process.

Solution

Manually delete the failed Order object. If necessary, also delete the associated CertificateRequest and Challenge. Cert-manager will then re-attempt the renewal.

kubectl delete order <order-name> -n <namespace>