ACME / Let's Encrypt Operations¶

Traefik Enterprise can be configured to use an ACME provider (like Let's Encrypt) for automatic TLS certificate management.

Create ACME Resolvers¶

Traefik Enterprise requires a Certificate Resolver to be defined in the static configuration, which is responsible for retrieving certificates from an ACME server.

Challenges must be defined in the certificate resolver in order to resolve certificates. The different kinds of challenges supported are: TLS, HTTP and DNS.

TLS Challenge¶

To use the TLS challenge, it must be added to the certificate resolver in the static configuration. Please refer to the Traefik Proxy documentation for more configuration options.

Below is an example static configuration:

File (YAML)

entryPoints:
  web:
    address: ":80"

  websecure:
    address: ":443"

certificatesResolvers:
  le:
    acme:
      email: [email protected]
      tlsChallenge: {}

File(TOML)

[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.le.acme]
  email = "[email protected]"
  [certificatesResolvers.le.acme.tlsChallenge]

HTTP Challenge¶

To use the HTTP challenge, it needs to be added to the certificate resolver in the static configuration. Please refer to the Traefik Proxy documentation for more information.

Below is an example static configuration:

File (YAML)

entryPoints:
  web:
    address: ":80"

  websecure:
    address: ":443"

certificatesResolvers:
  le:
    acme:
      email: [email protected]
      httpChallenge:
        # used during the challenge
        entryPoint: web

File(TOML)

[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.le.acme]
  email = "[email protected]"
  [certificatesResolvers.le.acme.httpChallenge]
    # used during the challenge
    entryPoint = "web"

DNS Challenge¶

Traefik Enterprise supports the same DNS Challenge providers as Traefik Proxy, please refer to Traefik Proxy documentation for more information.

In order to use the DNS-01 challenge, environment variables must be defined on the controllers (depending on the provider you're using).

First, update the environment variables required by your provider. Below is an example for using the DigitalOcean provider:

Kubernetes

containers:
    - name: "default-controller"
      # ...
      env:
        - name: DO_AUTH_TOKEN
          value: "XXXXXXXXXX"
# ...

Docker Swarm

services:
  controller-X: # all the controllers need to be updated
    # ...
    environment:
      - DO_AUTH_TOKEN=XXXXXX
# ...

Then, enable DNS challenge in the static configuration.

File (YAML)

certificatesResolvers:
  le:
    acme:
      # ...
      dnsChallenge:
        provider: digitalocean
        delayBeforeCheck: 0
    # ...

File(TOML)

[certificatesResolvers.le.acme]
  # ...
  [certificatesResolvers.le.acme.dnsChallenge]
    provider = "digitalocean"
    delayBeforeCheck = 0
# ...

Deploying Services¶

Once ACME setup is done, TLS enabled services can be configured to use its certificate resolver. Below are some examples for different providers:

Kubernetes

---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: blogtls
spec:
  entryPoints:
    - websecure
  routes:
  - match: Host(`company.com`) && Path(`/blog`)
    kind: Rule
    services:
    - name: blog
      port: 8080
  tls:
    certResolver: le

Docker Swarm

## Dynamic configuration
deploy:
  labels:
    - traefik.http.routers.blog.entrypoints=websecure
    - traefik.http.routers.blog.rule=Host(`company.com`) && Path(`/blog`)
    - traefik.http.routers.blog.tls=true
    - traefik.http.routers.blog.tls.certresolver=le
    - traefik.http.services.blog-svc.loadbalancer.server.port=8080

File (YAML)

## Dynamic configuration
http:
  routers:
    blog:
      rule: "Host(`company.com`) && Path(`/blog`)"
      tls:
        certResolver: le

File (TOML)

## Dynamic configuration
[http]
  [http.routers]
    [http.routers.blog]
        rule="Host(`company.com`) && Path(`/blog`)"
    [http.routers.blog.tls]
        certResolver="le"

Traefik Enterprise Premium ACME Accounts¶

If you have subscribed to ACME premium accounts, your cluster comes with two accounts (Production and Staging) already built-in. The premium account comes with a preferential Let's Encrypt rate limit (thousands of certificates per registered domain instead of the normal limit of 50). Please reach out to know more about this feature.

To use ACME premium account, set "[email protected]" or "[email protected]" in the email value:

File (YAML)

certificatesResolvers:
  le-staging:
    acme:
      # certificates will be generate with the staging ACME premium account
      email: [email protected]
      httpChallenge:
        # used during the challenge
        entryPoint: web
  le-prod:
    acme:
      # certificates will be generate with the production ACME premium account
      email: [email protected]
      httpChallenge:
        # used during the challenge
        entryPoint: web
      tlsChallenge: {}
# ...

File(TOML)

[certificatesResolvers.le-staging.acme]
  # certificates will be generate with the stating ACME premium account
  email = "[email protected]"
  [certificatesResolvers.le-staging.acme.httpChallenge]
    # used during the challenge
    entryPoint = "web"

[certificatesResolvers.le-prod.acme]
  # certificates will be generate with the production ACME premium account
  email = "[email protected]"
  [certificatesResolvers.le-prod.acme.httpChallenge]
    # used during the challenge
    entryPoint = "web"
  [certificatesResolvers.le-prod.acme.tlsChallenge]
# ...

CA Server

Don't provide any CA server when using an ACME premium account. One will be automatically set.

Limits on certificates

The production premium account cannot generate a certificate for the exact same set of domains (CN and SANs) more than 5 times per week. We recommend making regular backups using the backup command to avoid losing any certificates. You can use the staging premium account for test purposes.

List ACME Certificates¶

The command teectl get acme-certs gets the certificates generated by Traefik Enterprise.

teectl get acme-certs

ID                         CN                            SANS  NOT AFTER
p5g69jlt48txvhtc5azznzhas  http-challenge.crd.localhost        2025-01-24T09:17:51Z
py3z5yifklu410wp7ig7ghl11  tls-challenge.crd.localhost         2025-01-24T09:17:54Z

Deleting & Revoking ACME Certificates¶

By using teectl delete acme-cert, you can remove ACME certificates from your cluster as well as revoke them from the CA Server. This command requires the ID of the certificate which can be obtained by running the teectl get acme-certs command.

For certificates imported from versions <=2.1

In order to revoke certificates which were imported from backups that predate the v2.2.0, it is mandatory to specify the --caserver option.

teectl delete acme-cert --id="p5g69jlt48txvhtc5azznzhas"

Configuration Options¶

For more information on the different configuration possibilities, please refer to the Traefik Proxy documentation.