Using DNS01 challenges
Usually DNS01 challenges are required for the following scenarios:
-
Issuing Let’s Encrypt wildcard certificates
-
Issuing certificates for services which have a public DNS name, but aren’t reachable on the internet
This how-to shows you how to configure the letsencrypt-staging
and letsencrypt-production
cluster issuers managed by the component for DNS01 challenges.
This how-to assumes that you have access to an acme-dns instance. You can manage your own acme-dns instance with component acme-dns.
Prerequisites
-
Access to an acme-dns instance
-
A domain for which you can create
CNAME
records -
You can compile cluster catalogs locally
Setup
-
Configure the component to register itself on an acme-dns instance. Add the following configuration to your cluster or global configuration.
parameters: cert_manager: acmeClients: client-name: (1) api: endpoint: https://acme-dns-api.example.com (2) username: acme-dns (3) password: ?{vaultkv:${cluster:tenant}/${cluster:name}/cert-manager/acme-dns-password} (3) fqdns: (4) - cluster.example.com
1 An arbitrary name 2 The HTTP API of the acme-dns instance 3 The HTTP basic auth username and password for the acme-dns instance (optional) 4 The list of FQDNs that you want to use acme-dns challenges for. Note that the entries must match FQDNs for which you want to use acme-dns challenges exactly. With this configuration, cert-manager will only present DNS01 challenges for certificates with dnsNames cluster.example.com
or*.cluster.example.com
. In particular, cert-manager won’t present DNS01 challenges for any subdomains ofcluster.example.com
with this configuration.This configuration creates a secret
acme-dns-client-name-client
with the acme-dns client configuration in keyacmedns.json
in the cert-manager namespace. -
Configure the DNS01 solver
parameters: cert_manager: clusterIssuers: letsencrypt-production: ~solverRefs: [] (1) acmeClientRefs: (2) - client-name
1 Disable the default nginx_http01
solver2 Reference the acme-dns client from the previous step -
Compile and push the cluster catalog to apply your configuration.
-
Setup CNAME records to point acme challenges to acme-dns on your cluster’s domain after the registration job has completed.
Extract CNAME target from the acme-dns-client secret$ kubectl -n syn-cert-manager get secret client-name-client \ -ojsonpath='{.data.acmedns\.json}' | \ base64 -d | \ jq -r '[.[]][0].fulldomain' 9165e46c-7bc8-4b00-aa0d-d40413271434.acme-dns.example.com
Add the following record to your cluster’s DNS zone$ORIGIN cluster.example.com (1) _acme-challenge IN CNAME 9165e46c-7bc8-4b00-aa0d-d40413271434.acme-dns.example.com. (2)
1 This snippet assumes that the cluster’s DNS zone is cluster.example.com
.2 Replace <UUID>.acme-dns.example.com
with the output of thekubectl
command.