cert-manager DNS-01 webhook for PrimeDNS
On Kubernetes, cert-manager requests and renews
certificates through the PrimeDNS webhook. It creates and removes the _acme-challenge TXT record with the same
API key as the other clients, so wildcard certificates and certificates for services that are not reachable from the
internet work the same way. How the challenge works with PrimeDNS is explained in
ACME DNS-01 certificates with PrimeDNS.
1. Create an API key
In Account → API Keys choose Certificate key and list each hostname you will issue a certificate for (details: Create an API key).
2. Install the webhook
Install the webhook next to cert-manager with Helm:
helm install primedns-webhook oci://ghcr.io/primedns/charts/primedns-webhook \
--namespace cert-manager
The webhook runs as a non-root user with a read-only root filesystem. It was tested with cert-manager v1.21.
3. Store the key and create an issuer
kubectl -n cert-manager create secret generic primedns-api-key \
--from-literal=api-key='pdns_xxxxxxxxxxxxxxxxxxxx'
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-primedns
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: you@domain.tld
privateKeySecretRef:
name: letsencrypt-primedns-account
solvers:
- dns01:
cnameStrategy: Follow
webhook:
groupName: acme.primedns.net
solverName: primedns
config:
apiKeySecretRef:
name: primedns-api-key
key: api-key
For a ClusterIssuer the Secret is read from the namespace cert-manager keeps its cluster resources in
(cert-manager by default). For a namespaced Issuer the Secret must be in the same namespace as the issuer.
Try it first with the Let's Encrypt staging server
(https://acme-staging-v02.api.letsencrypt.org/directory).
4. Request a certificate
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: domain-tld
spec:
secretName: domain-tld-tls
issuerRef:
name: letsencrypt-primedns
kind: ClusterIssuer
dnsNames:
- domain.tld
- "*.domain.tld"
kubectl get certificate domain-tld
kubectl describe challenge
Issuing a certificate for an apex and a wildcard name together takes a couple of minutes, because cert-manager handles the two challenges one after the other and checks DNS before it asks the CA to validate.
CNAME delegation
For a domain whose DNS is hosted elsewhere, point _acme-challenge at a name in a zone of your PrimeDNS account
(see CNAME delegation) and give the key the scope for that target.
cnameStrategy: Follow, set in the issuer above, makes cert-manager follow the CNAME and pass the target name
to the webhook. Without that setting cert-manager uses the original name and the API refuses it.
Build the image yourself
The webhook is open source (Apache-2.0) and small. If you prefer not to run our image, build your own from the
repository with
docker build and point the chart at it (--set image.repository=...). The webhook only calls the
public PrimeDNS API.
Troubleshooting
When a challenge fails, kubectl describe challenge shows the message from the PrimeDNS API.
HTTP 401 ... the key is wrong, revoked or expired: check the key in the Secret.HTTP 403 NAME_NOT_ALLOWEDorINSUFFICIENT_SCOPE: the key has no scope for this exact name. With a CNAME delegation this usually means the issuer lackscnameStrategy: Follow, or the key has the scope for the original name instead of the CNAME target.- Other API errors and the
NXDOMAINreported by the CA are described in the overview.