ACME Certificates Resolver

In Traefik Hub API Gateway, TLS Certificates can be generated using Certificates Resolvers. You can find more information about Certificates Resolvers in the Concepts page.

In Traefik Hub API Gateway, three certificate resolvers exist:

acme: It allows generating ACME certificates stored in a file (not distributed).
distributedAcme: Same as acme but the generated certificates are shared between your Traefik Hub API Gateway instances (using Secrets in Kubernetes or Vault in other environments).
tailscale: It allows provisioning TLS certificates for internal Tailscale services.

The Certificates resolvers are defined in the static configuration.

Referencing a certificate resolver

Defining a certificate resolver does not imply that routers are going to use it automatically. Each router or entrypoint that is meant to use the resolver must explicitly reference it.

Configuration Example

Static configuration

certificatesResolvers:
  my-resolver:
    acme:
      email: "[email protected]"
      storage: "/path/to/acme.json"
      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 or key used for certificates storage.		Yes
`distributedAcme.storagekubernetes`	Enable Kubernetes Secret storage.		No
`distributedAcme.storagevault`	Enable Vault storage.		No
`distributedAcme.storagevault.url`	Vault server URL.		Yes
`distributedAcme.storagevault.enginePath`	Path to the Vault KV engine version 2.		Yes
`distributedAcme.storagevault.auth`	Authentication method.		Yes
`distributedAcme.storagevault.auth.token`	Authenticate using a Vault Token.		No
`distributedAcme.storagevault.auth.appRole`	Authenticate using a Vault AppRole.		No
`distributedAcme.storagevault.auth.appRole.roleId`	AppRole RoleID.		Yes
`distributedAcme.storagevault.auth.appRole.secretId`	AppRole SecretID.		Yes
`distributedAcme.storagevault.auth.appRole.path`	Custom path under which AppRole authentication is enabled in Vault.	approle	No
`distributedAcme.storagevault.auth.kubernetes`	Authenticate using a Kubernetes Service Account Token.		No
`distributedAcme.storagevault.auth.kubernetes.role`	Name of the role.		Yes
`distributedAcme.storagevault.auth.kubernetes.path`	Custom path under which Kubernetes authentication is enabled in Vault.	kubernetes	No
`distributedAcme.storagevault.namespace`	Namespace of the KV secret engine.		No
`distributedAcme.storagevault.syncInterval`	Secret synchronization interval.	5s	No
`distributedAcme.storagevault.tls`	TLS configuration.		No
`distributedAcme.storagevault.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.storagevault.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.storagevault.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.storagevault.tls.insecureSkipVerify`	Disables TLS certificate verification when communicating with Vault server.		No
`tailscale`	Enable tailscale certificates resolver.		False

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.