cert-manager mit Scaleway DNS: Wildcard-Zertifikate per DNS-01

Montagmorgen bei einem SaaS-Team auf Scaleway: Der zehnte Kunde dieser Woche bekommt seine Subdomain, und die Zertifikatsausstellung hängt. Der Grund ist bekannt – Let’s Encrypt zählt jedes Zertifikat gegen die registrierte Domain –, die Lösung auch: ein Wildcard-Zertifikat für *.example.com. Nur liegt die Zone bei Scaleway Domains & DNS, und in der Liste der eingebauten DNS-Anbieter von cert-manager steht Scaleway nicht.

Die DNS-01-Challenge ist das ACME-Verfahren, bei dem Sie die Kontrolle über eine Domain beweisen, indem Sie einen vorgegebenen Wert als TXT-Eintrag unter _acme-challenge.<domain> veröffentlichen. Damit cert-manager Scaleway DNS bedienen kann, braucht es einen Webhook. Dieser Beitrag zeigt die Schritte, die Stolperfallen und wie Clusterward das übernimmt.

Warum brauchen Wildcard-Zertifikate DNS-01?

Let’s Encrypt kennt drei Challenge-Typen. HTTP-01 legt eine Datei unter /.well-known/acme-challenge/ ab und passt für einzelne Hosts; für Wildcards schließt Let’s Encrypt sie ausdrücklich aus, ebenso TLS-ALPN-01. Bleibt DNS-01: Wer TXT-Einträge in der Zone setzen darf, kontrolliert jede Subdomain darunter – deshalb reicht dieser Nachweis für *.example.com.

Warum sich ein Wildcard bei Subdomains pro Kunde überhaupt lohnt, beschreibt der Beitrag Let’s Encrypt Rate-Limits: Warum SaaS-Subdomains ein Wildcard-Zertifikat brauchen. Hier geht es um das Wie.

Warum kennt cert-manager Scaleway nicht?

cert-manager bringt DNS-01-Solver für eine feste Liste mit: ACME-DNS, Akamai, Azure DNS, Cloudflare, Google Cloud DNS, Route 53, DigitalOcean und RFC2136. Alle anderen Anbieter docken über einen Webhook an – einen eigenen Dienst im Cluster, den cert-manager als API-Erweiterung anspricht und der die TXT-Einträge beim Anbieter setzt und wieder löscht.

Für Scaleway pflegt Scaleway den Webhook selbst: Chart scaleway-certmanager-webhook aus dem Repository https://helm.scw.cloud, API-Gruppe acme.scaleway.com, Solver-Name scaleway. Diese drei Werte tauchen später im Issuer wieder auf.

Liegt die Zone wirklich bei Scaleway?

Der Webhook schreibt in Scaleway Domains & DNS, also muss die Zone dort existieren und autoritativ sein. Eine bei Scaleway registrierte Domain hat sie automatisch. Eine Domain von einem anderen Registrar fügen Sie als externe Domain hinzu:

• Scaleway verlangt zuerst einen TXT-Eintrag _scaleway-challenge in der bisherigen Zone als Besitznachweis.
• Danach stellen Sie beim Registrar die Nameserver auf ns0.dom.scw.cloud und ns1.dom.scw.cloud um.
• Für den ganzen Ablauf bleiben 14 Tage, sonst entfernt Scaleway die externe Domain wieder.

Solange noch die alten Nameserver antworten, landet der TXT-Eintrag des Webhooks in einer Zone, die Let’s Encrypt nie fragt – die Challenge bleibt dann endlos ausstehend.

Wie richte ich den Scaleway-Webhook ein?

Voraussetzung ist ein laufender cert-manager. Dann, in dieser Reihenfolge:

1. IAM-Key anlegen. In der Scaleway-Konsole unter IAM eine Application erstellen, ihr eine Policy mit dem Permission Set DomainsDNSFullAccess auf genau dem Projekt geben, in dem die Zone liegt, und einen API-Key erzeugen. Mehr braucht der Key nicht.
2. Webhook installieren und warten. helm repo add scaleway https://helm.scw.cloud/, dann helm install scaleway-certmanager-webhook scaleway/scaleway-certmanager-webhook -n cert-manager --wait. Der Webhook holt sich bei cert-manager ein eigenes Serving-Zertifikat; erst danach meldet kubectl get apiservice v1alpha1.acme.scaleway.com den Status Available. Bei uns dauerte das rund eine Minute.
3. Secret im richtigen Namespace. Ein Secret mit den Schlüsseln SCW_ACCESS_KEY und SCW_SECRET_KEY im Namespace cert-manager – warum genau dort, folgt unten.
4. ClusterIssuer anlegen. Ein ACME-Issuer mit einem dns01.webhook-Solver: groupName: acme.scaleway.com, solverName: scaleway und unter config die Verweise accessKeySecretRef und secretKeySecretRef auf das Secret.
5. Certificate anfordern. dnsNames mit *.example.com und example.com – ein Wildcard deckt weder die Apex-Domain ab noch mehr als eine Ebene darunter.
6. Secret verteilen. Das ausgestellte Secret liegt in genau einem Namespace. Mit Reflector und den Annotationen reflection-allowed und reflection-auto-enabled im secretTemplate des Certificates landet es in jedem Namespace, und jedes Ingress-Objekt verweist nur noch auf den Namen.

Welche Stolperfallen gibt es in der Praxis?

• Secret im falschen Namespace. Der Webhook liest das Secret im Namespace der Challenge – bei einem ClusterIssuer ist das der Cluster-Resource-Namespace von cert-manager, standardmäßig cert-manager. Die RBAC-Rolle des Charts erlaubt ihm das Lesen von Secrets ohnehin nur in seinem eigenen Namespace. Installieren Sie ihn deshalb dorthin; ein Secret neben der Anwendung bleibt unsichtbar, die Challenge scheitert mit „could not get secret“.
• Zu früh ausgestellt. Wer direkt nach der Installation das Certificate anlegt, trifft auf einen Webhook, dessen API-Gruppe noch nicht antwortet. cert-manager versucht es später erneut, aber der erste Fehler kostet Zeit bei der Fehlersuche. --wait und ein Blick auf den APIService ersparen das.
• Zone nicht autoritativ. Externe Domain angelegt, Nameserver aber nie umgestellt: Der TXT-Eintrag steht bei Scaleway, Let’s Encrypt fragt die alten Server.
• Key im falschen Projekt. Die Policy gilt pro Projekt. Liegt die Zone in einem anderen Projekt, lehnt die API den Schreibzugriff ab.
• Zu früh in Produktion. Let’s Encrypt erlaubt nur fünf fehlgeschlagene Validierungen pro Name und Konto in der Stunde. Testen Sie die Kette erst gegen die Staging-Umgebung und stellen Sie dann den Issuer um.

Hängt eine Ausstellung, zeigt kubectl describe challenge im Namespace des Zertifikats fast immer den eigentlichen Grund.

Wie Clusterward das übernimmt

In Clusterward registrieren Sie die Zone einmal unter DNS mit Access Key und Secret Key. Clusterward prüft direkt nach dem Speichern, ob der Key die Zone sieht, und bietet nur verifizierte Zonen für Wildcards an. Die Karte „Cluster setup“ installiert cert-manager, Reflector und den Scaleway-DNS-Webhook – Letzteren mit Warten, bis seine API-Gruppe antwortet; erst dann steht er auf „Installed“.

Unter Certificates legen Sie mit „Register wildcard“ einen verwalteten Wildcard an: Zone, Cluster, Let’s Encrypt oder dessen Staging, eine E-Mail-Adresse. Clusterward legt pro Wildcard ein Secret mit dem Key im Namespace cert-manager an, einen eigenen ClusterIssuer und ein Certificate für die Zone plus Apex mit den Reflector-Annotationen – und stellt sofort aus. Fehlt etwas, nennt die Zertifikatsseite vorher jedes Hindernis einzeln (Admin-Zugriff auf den Cluster, der Webhook, der Key der Zone), verlinkt die Karte, die es behebt, und hält „Issue“ gesperrt. Danach verfolgt Clusterward die Ausstellung, bis das Zertifikat mit Ablaufdatum bereit ist; eine tägliche Prüfung meldet, wenn es in weniger als 14 Tagen abläuft. Mehr unter DNS & Zertifikate; wie ein Service den Wildcard am Ingress nutzt, steht unter Netzwerk & Ingress.

Fazit

Wildcard-Zertifikate für eine Scaleway-Zone sind kein Sonderweg, sondern sechs Objekte in der richtigen Reihenfolge: Key, Webhook, Secret, Issuer, Certificate, Reflector. Die meisten Fehler entstehen nicht in cert-manager, sondern davor – beim Namespace des Secrets, beim Warten auf den Webhook und bei Nameservern, die nie umgestellt wurden.

Wildcard-Zertifikate für Ihre Scaleway-Zone? Schreiben Sie uns, wie Ihre Domains und Cluster heute aufgeteilt sind. Wir zeigen, wie DNS-01 und Ihr Kunden-Onboarding zusammenpassen. Frage stellen →

Quellen und weiterführende Links

• Let’s Encrypt: Challenge-Typen (englisch)
• cert-manager-Doku: DNS01 und Webhook-Anbieter (englisch)
• Scaleway: cert-manager-webhook-scaleway auf GitHub
• Scaleway-Doku: Permission Sets (englisch)
• Scaleway-Doku: Externe Domain hinzufügen (englisch)