Cert-Manager - Troubleshooting der Zertifikaterstellung

Wenn Sie Probleme beim Erstellen von Kubernetes Zertifikaten mit dem Cert-Manager haben, finden Sie hier einige Hinweise zur Fehlerbehebung.

Reihenfolge der Zertifikaterstellung

Die folgenden Schritte beschreiben den Prozess der Ausstellung eines Zertifikats, wenn das ACME (Automatic Certificate Management Environment) wie z.B. Let's Encrypt verwendet wird. Das ACME-Protokoll ist für die automatische Ausstellung und Erneuerung von Zertifikaten vorgesehen.

Schritt 1. Der erste Schritt ist die Erstellung des Zertifikatsobjekts.

kubectl apply -f mein-zertifikat.yaml

So kann eine yaml-Datei dafür aussehen: 

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: mein-zertifikat
  namespace: mein-namespace
spec:
  secretName: mein-zertifikat-secret
  duration: 8760h # 365 Tage
  renewBefore: 360h # 15 Tage vor Ablauf erneuern
  issuerRef:
    name: meine-pki
    kind: ClusterIssuer
  commonName: www.beispieldomain.de
  dnsNames:
  - www.beispieldomain.de
  - subdomian.beispieldomain.de

Beschreibung einiger Felder:

Schritt 2. Cert-Manager überwacht den Kubernetes-Cluster auf neue oder geänderte Certificate-Objekte. Wenn das Certificate-Objekt erstellt wurde, erkennt Cert-Manager dies und beginnt mit der Zertifikatsausstellung.

Schritt 3. Cert-Manager erstellt ein CertificateRequest-Objekt, das die Anforderung für ein neues Zertifikatabbildet. Dieses Objekt enthält die erforderlichen Informationen, um ein Zertifikat vom angegebenen ClusterIssuer (in unserem Fall meine-pki) zu beantragen.

Schritt 4.  Cert-Manager startet eine Challenge*, um die Kontrolle über die im Zertifikat angegebenen Domains zu überprüfen. In diesem Fall wird eine DNS-01 Challenge verwendet. Dies bedeutet, dass ein spezieller DNS TXT-Eintrag auf der DNS-Appliance erstellt werden muss.

* eine "Certificate Challenge" ist ein Verfahren, mit dem nachgewiesen wird, dass der Antragsteller tatsächlich die Kontrolle über die angefragte Domain hat.

Schritt 5.  Als nächstes kommt eine Komponente des Cert Managers ins Spiel, der DNS Solver. Der DNS-Solver kommuniziert mit der DNS-Infrastruktur, um den benötigten DNS TXT-Eintrag zu erstellen. Der ACME-Server überprüft dann diesen Eintrag, um sicherzustellen, dass der Antragsteller tatsächlich die entsprechenden Rechte an der Domain hat.

Schritt 6. Nach erfolgreicher Challenge und Domain Validation stellt der ClusterIssuer das Zertifikat aus. Der Cert-Manager holt das ausgestellte Zertifikat ab und speichert es im angegebenen Kubernetes Secret (in oberem Beispiel mein-zertifikat-secret). 

Mit diesem Schritt ist die Zertifikatserstellung abgeschlossen. Das Zertifikat und der private Schlüssel sind nun im Secret gespeichert und können von anderen Ressourcen im Cluster (z. B. Ingress-Controllern) verwendet werden.

Schritt 7. Der Cert-Manager überwacht das Ablaufdatum des Zertifikats. Er veranlasst automatisch eine Erneuerung, bevor das Zertifikat abläuft.

Allgemeines Troubleshooting des Cert-Managers

Hier sind einige kubectl-Befehle aufgelistet, die helfen können, eine fehlgeschlagene Zertifikatsausstellung zu debuggen. Eine eine sinnvolle Reihenfolge ist wichtig.

1. Certificate-Objekte überprüfen
2. CertificateRequests überprüfen
3. Order-Objekte überprüfen
4. Issuer- und ClusterIssuer überprüfen
5. Challenge-Objekte überprüfen
6. Logs des Cert-Managers überprüfen

Die ersten vier Schritte umfassen die Kernressourcen des Cert Managers, die direkt am Prozess der Zertifikatsausstellung beteiligt sind: Certificate, CertificateRequest, Order, Issuer, ClusterIssuer.

1.1. Alle Certificate-Objekte im angegebenen Namespace auflisten.

kubectl get certificate -n <namespace-name>

1.2. Zeigt detaillierte Informationen zu einem bestimmten Certificate-Objekt an.

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

2.1. Listet alle CertificateRequest-Objekte im angegebenen Namensraum auf.

kubectl get certificaterequest -n <namespace-name>

2.2. Zeigt Detailinformationen zu einem CertificateRequest an. Hier wird angezeigt, ob der Antrag genehmigt wurde oder nicht.

kubectl describe certificaterequest <name-des-certificaterequests> -n <namespace-name>

Hier sind zwei Beispiele: ein positiver und ein negativer Status:

Message: Certificate fetched from issuer successfully
Reason: Issued
Status: True

Message: Waiting on certificate issuance from order <order-name> "pending"
Reason: Pending
Status: False

3.1. Alle Order-Objekte im angegebenen Namespace auflisten.

kubectl describe order <name-der-order> -n <namespace-name>

3.2. Zeigt detaillierte Informationen zu einer spezifischen Order.

kubectl describe order <name-der-order> -n <namespace-name>

4.1. Ein Issuer ist eine Namespace-spezifische Ressource, die Ressourcen im angegebenen Namespace auflistet. ClusterIssuer sind clusterweit und nicht auf einen Namespace beschränkt.

kubectl get issuer -n <namespace-name>
kubectl get clusterissuer -n <namespace-name>

4.2. Details zu einem spezifischen Issuer / ClusterIssuer anzeigen.

kubectl describe issuer <issuer-name> -n <namespace-name>
kubectl describe clusterissuer <clusterIssuer-name> -n <namespace-name>

5.1. Alle Challenge-Objekte im angegebenen Namespace auflisten

kubectl get challenge -n <namespace-name>

5.2. Details zu einer bestimmten Challenge anzeigen.

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

6.1. Die folgende Befehlskette zeigt die Logs des Cert-Manager-Pods an

kubectl logs <name-des-cert-manager-pods> -n <namespace-name> 

6.2. Auch untere Befehlskette kann bei der Fehlersuche im Bereich des Cert-Managers nützlich sein.

kubectl get events -n <namespace>

Nützliche Information auf Cetr-Manager.io

• Issuing an ACME certificate using DNS validation
• Troubleshooting Issuing ACME Certificates
• Troubleshooting Problems with ACME / Let's Encrypt Certificates
• Certificate resource

• Weiter