ACME Certificates Resolvers

Configuration Example

ACME Certificates Resolver

certificatesResolvers:
  my-resolver:
    acme:
      email: "[email protected]"
      storage: "/path/to/acme.json"
      httpChallenge:
        entryPoint: "web"

Distributed ACME Certifcates Resolver

certificatesResolvers:
  my-resolver:
    distributedAcme:
      email: "[email protected]"
      storage:
        kubernetes: {}
      httpChallenge:
        entryPoint: "web"

Configuration Options

ACME and distributed ACME certificate resolvers share the following configuration options:

Field	Description	Default	Required
acme.email/ distributedAcme.email	Email address used for registration.		Yes
acme.caServer / distributedAcme.caServer	CA server to use.	https://acme-v02.api.letsencrypt.org/directory	No
acme.preferredChain / distributedAcme.preferredChain	Preferred chain to use. If the CA offers multiple certificate chains, prefer the chain with an issuer matching this Subject Common Name. If no match, the default offered chain will be used.		No
acme.keyType / distributedAcme.keyType	KeyType to use.	RSA4096	No
acme.eab / distributedAcme.eab	Enable external account binding.		No
acme.eab.kid / distributedAcme.eab.kid	Key identifier from External CA.		No
acme.eab.hmacEncoded / distributedAcme.eab.hmacEncoded	HMAC key from External CA, should be in Base64 URL Encoding without padding format.		No
acme.certificatesDuration / distributedAcme.certificatesDuration	The certificates' duration in hours, exclusively used to determine renewal dates.	2160	No
acme.dnsChallenge / distributedAcme.dnsChallenge	Enable DNS-01 challenge. More information here		No
acme.dnsChallenge.provider / distributedAcme.dnsChallenge.provider	DNS provider to use.		No
acme.dnsChallenge.delayBeforeCheck / distributedAcme.dnsChallenge.delayBeforeCheck	By default, the provider will verify the TXT DNS challenge record before letting ACME verify. If delayBeforeCheck is greater than zero, this check is delayed for the configured duration in seconds. Useful if internal networks block external DNS queries.		No
acme.dnsChallenge.resolvers / distributedAcme.dnsChallenge.resolvers	DNS servers to resolve the FQDN authority.		No
acme.dnsChallenge.disablePropagationCheck / distributedAcme.dnsChallenge.disablePropagationCheck	Disable the DNS propagation checks before notifying ACME that the DNS challenge is ready.		No
acme.httpChallenge / distributedAcme.httpChallenge	Enable HTTP-01 challenge.		No
acme.httpChallenge.entryPoint / distributedAcme.httpChallenge.entryPoint	EntryPoint to use for the HTTP-01 challenges. Must be reachable by Let's Encrypt through port 80.		Yes
acme.tlsChallenge / distributedAcme.tlsChallenge	Enable TLS-ALPN-01 challenge. Hub API Gateway must be reachable by Let's Encrypt through port 443		No
acme.storage	File path used for certificates storage.		Yes
distributedAcme.storage.kubernetes	Enable Kubernetes Secret storage.		Yes
distributedAcme.storage.vault	Enable Vault storage.		No
distributedAcme.storage.vault.url	Vault server URL.		Yes
distributedAcme.storage.vault.enginePath	Path to the Vault KV engine version 2.		Yes
distributedAcme.storage.vault.auth	Authentication method.		Yes
distributedAcme.storage.vault.auth.token	Authenticate using a Vault Token.		No
distributedAcme.storage.vault.auth.appRole	Authenticate using a Vault AppRole.		No
distributedAcme.storage.vault.auth.appRole.roleId	AppRole RoleID.		Yes
distributedAcme.storage.vault.auth.appRole.secretId	AppRole SecretID.		Yes
distributedAcme.storage.vault.auth.appRole.path	Custom path under which AppRole authentication is enabled in Vault.	approle	No
distributedAcme.storage.vault.auth.kubernetes	Authenticate using a Kubernetes Service Account Token.		No
distributedAcme.storage.vault.auth.kubernetes.role	Name of the role.		Yes
distributedAcme.storage.vault.auth.kubernetes.path	Custom path under which Kubernetes authentication is enabled in Vault.	kubernetes	No
distributedAcme.storage.vault.namespace	Namespace of the KV secret engine.		No
distributedAcme.storage.vault.syncInterval	Secret synchronization interval.	5s	No
distributedAcme.storage.vault.tls	TLS configuration.		No
distributedAcme.storage.vault.tls.ca	PEM-encoded certificate bundle or a path to a file containing the certificate bundle used to establish a TLS connection with the Vault server.		No
distributedAcme.storage.vault.tls.cert	PEM-encoded certificate or a path to a file containing the certificate used to establish a mTLS connection with the Vault server.		No
distributedAcme.storage.vault.tls.key	PEM-encoded key or a path to a file containing the key used to establish a mTLS connection with the Vault server.		No
distributedAcme.storage.vault.tls.insecureSkipVerify	Disables TLS certificate verification when communicating with Vault server.		No

dnsChallenge

The DNS-01 challenge to generate and renew ACME certificates by provisioning a DNS record.

Hub API Gateway relies internally on Lego for ACME. You can find the list of all the supported DNS providers in their documentation with instructions about which environment variables need to be setup.

DNS-01 domain delegation

CNAME are supported and even encouraged.

If needed, CNAME support can be turned off with the following environment variable:

LEGO_DISABLE_CNAME_SUPPORT=true

Multiple DNS Challenge provider

Multiple DNS challenge provider are not supported with Hub API Gateway, but you can use CNAME to handle that. For example, if you have example.org (account foo) and example.com (account bar) you can create a CNAME on example.org called _acme-challenge.example.org pointing to challenge.example.com. This way, you can obtain certificates for example.com with the foo account.

Domain Definition

A certificate resolver requests certificates for a set of domain names inferred from routers, according to the following:

• If the IngressRoute has a tls.domains option set, then the certificate resolver derives this router domain name from the main option of tls.domains.

• Otherwise, the certificate resolver derives the domain name from any Host() or HostSNI() matchers in the IngressRoute's rule.

You can set SANs (alternative domains) for each main domain. Every domain must have A/AAAA records pointing to Traefik. Each domain & SAN will lead to a certificate request.

ACME v2 supports wildcard certificates. As described in Let's Encrypt's post wildcard certificates can only be generated through a DNS-01 challenge. It is not possible to request a double wildcard certificate for a domain (for example *.*.local.com).

Most likely the root domain should receive a certificate too, so it needs to be specified as SAN and 2 DNS-01 challenges are invoked. In such a case the generated DNS TXT record for both domains is the same. Even though this behavior is DNS RFC compliant, it can lead to problems as all DNS providers keep DNS records cached for a given time (TTL) and this TTL can be greater than the challenge timeout making the DNS-01 challenge fail.

The Traefik ACME client library lego supports some but not all DNS providers to work around this issue. The supported provider table indicates if they allow generating certificates for a wildcard domain and its root domain.

Certificate Renewal

Hub API Gateway automatically tracks the expiry date of certificates it generates.

Not used Certificates

Certificates that are no longer used may still be renewed, as Hub API Gateway does not currently check if the certificate is being used before renewing.

By default, Hub API Gateway manages 90-day certificates and starts renewing them 30 days before their expiry.

When using a certificate resolver that issues certificates with custom durations, the certificatesDuration option can be used to configure the certificates' duration.