Component setup

This guide helps you to get an acme-dns instance deployed and configured as a nameserver for a zone of your domain.


  • You can locally compile a cluster catalog

  • You have a Kubernetes or OpenShift cluster which supports service type LoadBalancer

  • curl

  • jq

  • vault CLI

Enable the acme-dns component

  1. Add the following configuration to your cluster’s c-cluster-id.yml file:

      - acme-dns as acme-dns-prod (1)
      acme_dns_prod: (2)
        namespace: syn-acme-dns-prod (3)
          hostname: (4)
            domain: (5)
            nsname: (6)
            nsadmin: (7)
    1 You can instantiate the acme-dns component if you want to run multiple acme-dns instances on the same cluster.
    2 Configure the component instance, rather than the component itself.
    3 Override the namespace to use to be more succinct than the generated version.
    4 Configure the hostname for the acme-dns HTTP API.
    5 Configure the zone for which the acme-dns instance will serve DNS records.
    6 Configure the DNS name of the nameserver (the acme-dns instance itself).
    7 Configure the email address of the domain/zone administrator.
    Make sure that configurations - refer to a domain that you administrate.
    See the parameters documentation for all the configuration parameters of the component.
  2. Compile the cluster catalog to deploy acme-dns to the cluster

Configure the DNS parent zone

To configure your new acme-dns instance as the nameserver for the zone you’ve configured, you need to add a few records to the zone’s parent zone.

acme-dns-api    IN CNAME (1)
acme-dns-ns     IN A (2)
acme-dns        IN NS (3)
1 Configure a CNAME (or A) record, which points to the ingress controller of your target cluster.
2 Replace with the IP assigned to the LoadBalancer service created by the component. You can get the IP by accessing the cluster on which you’ve deployed the acme-dns instance, and executing the following command:
$ export KUBECONFIG=/path/to/target/cluster.kubeconfig
$ kubectl -n syn-acme-dns-prod get svc acme-dns \
3 Configure a NS record which delegates DNS queries for * to the acme-dns instance at

Test the acme-dns instance

At this point, the acme-dns instance should be ready to use.

You can test the instance with the following sequence of commands:

$ export ACME_DNS_API= (1)
$ export VAULT_ADDR= (2)
$ vault login -method=<login-method> login_arg=login_value (3)
$ register_pw=$(vault kv get -format=json \
    clusters/kv/${TENANT_ID}/${CLUSTER_ID}/acme-dns/vshn-acme-dns-prod \
    | jq -r '"api-password"')
$ client_credentials=$(curl -u "acme-dns:${register_pw}" "${ACME_DNS_API}/register" -XPOST)
$ client_username=$(echo "${client_credentials} | jq -r '.username')
$ client_password=$(echo "${client_credentials} | jq -r '.password')
$ client_subdomain=$(echo "${client_credentials} | jq -r '.subdomain')
$ curl -H"X-Api-User: ${client_username}" \
    -H"X-Api-Key: ${client_password}" \
    -d '{
      "subdomain": "${client_subdomain}",
      "txt": "___validation_token_received_from_the_ca___"
    }' \
$ client_fulldomain=$(echo "${client_credentials} | jq -r '.fulldomain')
$ dig "${client_fulldomain}" TXT

[ ... ]

<subdomain>	1 IN TXT "___validation_token_received_from_the_ca___" (4)

[ ... ]
1 The hostname for the acme-dns HTTP API.
2 Replace with the address of your Project Syn Vault.
3 Select a login method you’ve configured on your Vault instance and provide necessary login arguments for the login method.
4 dig should return the TXT record we created via the API.

To configure a client, such as cert-manager, to use your acme-dns instance, see configuring a client.