ACME / Let's Encrypt Operations

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

Create ACME Resolvers

TraefikEE 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 documentation for more configuration options.

Below is an example static configuration:

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

  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.le.acme]
  email = "[email protected]"
  [certificatesResolvers.le.acme.tlsChallenge]
entryPoints:
  web:
    address: ":80"

  websecure:
    address: ":443"

certificatesResolvers:
  le:
    acme:
      email: [email protected]
      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 documentation for more information.

Below is an example static configuration:

[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"
entryPoints:
  web:
    address: ":80"

  websecure:
    address: ":443"

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

DNS Challenge

TraefikEE supports the same DNS Challenge providers as Traefik, please refer to Traefik 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:

containers:
    - name: "default-controller"
      # ...
      env:
        - name: DO_AUTH_TOKEN
          value: "XXXXXXXXXX"
# ...
services:
  controller-X: # all the controllers need to be updated
    # ...
    environment:
      - DO_AUTH_TOKEN=XXXXXX
# ...

Then, enable DNS challenge in the static configuration.

[certificatesResolvers.le.acme]
  # ...
  [certificatesResolvers.le.acme.dnsChallenge]
    provider = "digitalocean"
    delayBeforeCheck = 0
# ...
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:

---
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
## 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
## Dynamic configuration
http:
  routers:
    blog:
      rule: "Host(`company.com`) && Path(`/blog`)"
      tls:
        certResolver: le
## Dynamic configuration
[http]
  [http.routers]
    [http.routers.blog]
        rule="Host(`company.com`) && Path(`/blog`)"
    [http.routers.blog.tls]
        certResolver="le"

TraefikEE 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:

[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]
# ...
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: {}
# ...
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 TraefikEE.

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

Configuration Options

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