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

  1. 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 of cluster.example.com with this configuration.

    This configuration creates a secret acme-dns-client-name-client with the acme-dns client configuration in key acmedns.json in the cert-manager namespace.

  2. Configure the DNS01 solver

    parameters:
  cert_manager:
    clusterIssuers:
      letsencrypt-production:
        ~solverRefs: [] (1)
        acmeClientRefs: (2)
          - client-name
    1 Disable the default nginx_http01 solver
    2 Reference the acme-dns client from the previous step

  3. Compile and push the cluster catalog to apply your configuration.

  4. 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 the kubectl command.