traefik/docs/content/https/acme.md
2020-09-04 10:52:03 +02:00

38 KiB

Let's Encrypt

Automatic HTTPS {: .subtitle }

You can configure Traefik to use an ACME provider (like Let's Encrypt) for automatic certificate generation.

!!! warning "Let's Encrypt and Rate Limiting" Note that Let's Encrypt API has rate limiting.

Use Let's Encrypt staging server with the [`caServer`](#caserver) configuration option
when experimenting to avoid hitting this limit too fast.

Certificate Resolvers

Traefik requires you to define "Certificate Resolvers" in the static configuration, which are responsible for retrieving certificates from an ACME server.

Then, each "router" is configured to enable TLS, and is associated to a certificate resolver through the tls.certresolver configuration option.

Certificates are requested for domain names retrieved from the router's dynamic configuration.

You can read more about this retrieval mechanism in the following section: ACME Domain Definition.

!!! important "Defining a certificates resolver does not result in all routers automatically using it. Each router that is supposed to use the resolver must reference it."

??? note "Configuration Reference"

There are many available options for ACME.
For a quick glance at what's possible, browse the configuration reference:

```toml tab="File (TOML)"
--8<-- "content/https/ref-acme.toml"
```

```yaml tab="File (YAML)"
--8<-- "content/https/ref-acme.yaml"
```

```bash tab="CLI"
--8<-- "content/https/ref-acme.txt"
```

Domain Definition

Certificate resolvers request certificates for a set of the domain names inferred from routers, with the following logic:

  • If the router has a tls.domains option set, then the certificate resolver uses the main (and optionally sans) option of tls.domains to know the domain names for this router.

  • If no tls.domains option is set, then the certificate resolver uses the router's rule, by checking the Host() matchers. Please note that multiple Host() matchers can be used) for specifying multiple domain names for this router.

Please note that:

Please check the configuration examples below for more details.

Configuration Examples

??? example "Enabling ACME"

```toml tab="File (TOML)"
[entryPoints]
  [entryPoints.web]
    address = ":80"

  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.myresolver.acme]
  email = "your-email@example.com"
  storage = "acme.json"
  [certificatesResolvers.myresolver.acme.httpChallenge]
    # used during the challenge
    entryPoint = "web"
```

```yaml tab="File (YAML)"
entryPoints:
  web:
    address: ":80"

  websecure:
    address: ":443"

certificatesResolvers:
  myresolver:
    acme:
      email: your-email@example.com
      storage: acme.json
      httpChallenge:
        # used during the challenge
        entryPoint: web
```

```bash tab="CLI"
--entrypoints.web.address=:80
--entrypoints.websecure.address=:443
# ...
--certificatesresolvers.myresolver.acme.email=your-email@example.com
--certificatesresolvers.myresolver.acme.storage=acme.json
# used during the challenge
--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web
```

!!! important "Defining a certificates resolver does not result in all routers automatically using it. Each router that is supposed to use the resolver must reference it."

??? example "Single Domain from Router's Rule Example"

* A certificate for the domain `example.com` is requested:

--8<-- "content/https/include-acme-single-domain-example.md"

??? example "Multiple Domains from Router's Rule Example"

* A certificate for the domains `example.com` (main) and `blog.example.org`
  is requested:

--8<-- "content/https/include-acme-multiple-domains-from-rule-example.md"

??? example "Multiple Domains from Router's tls.domain Example"

* A certificate for the domains `example.com` (main) and `*.example.org` (SAN)
  is requested:
  
--8<-- "content/https/include-acme-multiple-domains-example.md"

Automatic Renewals

Traefik automatically tracks the expiry date of ACME certificates it generates.

If there are less than 30 days remaining before the certificate expires, Traefik will attempt to renew it automatically.

!!! info "" Certificates that are no longer used may still be renewed, as Traefik does not currently check if the certificate is being used before renewing.

Using LetsEncrypt with Kubernetes

When using LetsEncrypt with kubernetes, there are some known caveats with both the ingress and crd providers.

!!! info "" If you intend to run multiple instances of Traefik with LetsEncrypt, please ensure you read the sections on those provider pages.

The Different ACME Challenges

!!! important "Defining a certificates resolver does not result in all routers automatically using it. Each router that is supposed to use the resolver must reference it."

tlsChallenge

Use the TLS-ALPN-01 challenge to generate and renew ACME certificates by provisioning a TLS certificate.

As described on the Let's Encrypt community forum, when using the TLS-ALPN-01 challenge, Traefik must be reachable by Let's Encrypt through port 443.

??? example "Configuring the tlsChallenge"

```toml tab="File (TOML)"
[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.tlsChallenge]
```

```yaml tab="File (YAML)"
certificatesResolvers:
  myresolver:
    acme:
      # ...
      tlsChallenge: {}
```

```bash tab="CLI"
# ...
--certificatesresolvers.myresolver.acme.tlschallenge=true
```

httpChallenge

Use the HTTP-01 challenge to generate and renew ACME certificates by provisioning an HTTP resource under a well-known URI.

As described on the Let's Encrypt community forum, when using the HTTP-01 challenge, certificatesresolvers.myresolver.acme.httpchallenge.entrypoint must be reachable by Let's Encrypt through port 80.

??? example "Using an EntryPoint Called web for the httpChallenge"

```toml tab="File (TOML)"
[entryPoints]
  [entryPoints.web]
    address = ":80"
  
  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.httpChallenge]
    entryPoint = "web"
```

```yaml tab="File (YAML)"
entryPoints:
  web:
    address: ":80"

  websecure:
    address: ":443"

certificatesResolvers:
  myresolver:
    acme:
      # ...
      httpChallenge:
        entryPoint: web
```

```bash tab="CLI"
--entrypoints.web.address=:80
--entrypoints.websecure.address=:443
# ...
--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web
```

!!! info "" Redirection is fully compatible with the HTTP-01 challenge.

dnsChallenge

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

??? example "Configuring a dnsChallenge with the DigitalOcean Provider"

```toml tab="File (TOML)"
[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.dnsChallenge]
    provider = "digitalocean"
    delayBeforeCheck = 0
# ...
```

```yaml tab="File (YAML)"
certificatesResolvers:
  myresolver:
    acme:
      # ...
      dnsChallenge:
        provider: digitalocean
        delayBeforeCheck: 0
    # ...
```

```bash tab="CLI"
# ...
--certificatesresolvers.myresolver.acme.dnschallenge.provider=digitalocean
--certificatesresolvers.myresolver.acme.dnschallenge.delaybeforecheck=0
# ...
```

!!! important
    A `provider` is mandatory.

providers

Here is a list of supported providers, that can automate the DNS verification, along with the required environment variables and their wildcard & root domain support. Do not hesitate to complete it.

Many lego environment variables can be overridden by their respective _FILE counterpart, which should have a filepath to a file that contains the secret as its value. For example, CF_API_EMAIL_FILE=/run/secrets/traefik_cf-api-email could be used to provide a Cloudflare API email address as a Docker secret named traefik_cf-api-email.

For complete details, refer to your provider's Additional configuration link.

Provider Name Provider Code Environment Variables
ACME DNS acme-dns ACME_DNS_API_BASE, ACME_DNS_STORAGE_PATH Additional configuration
Alibaba Cloud alidns ALICLOUD_ACCESS_KEY, ALICLOUD_SECRET_KEY, ALICLOUD_REGION_ID Additional configuration
ArvanCloud arvancloud ARVANCLOUD_API_KEY Additional configuration
Auroradns auroradns AURORA_USER_ID, AURORA_KEY, AURORA_ENDPOINT Additional configuration
Autodns autodns AUTODNS_API_USER, AUTODNS_API_PASSWORD Additional configuration
Azure azure AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_RESOURCE_GROUP, [AZURE_METADATA_ENDPOINT] Additional configuration
Bindman bindman BINDMAN_MANAGER_ADDRESS Additional configuration
Blue Cat bluecat BLUECAT_SERVER_URL, BLUECAT_USER_NAME, BLUECAT_PASSWORD, BLUECAT_CONFIG_NAME, BLUECAT_DNS_VIEW Additional configuration
Checkdomain checkdomain CHECKDOMAIN_TOKEN, Additional configuration
CloudDNS clouddns CLOUDDNS_CLIENT_ID, CLOUDDNS_EMAIL, CLOUDDNS_PASSWORD Additional configuration
ClouDNS cloudns CLOUDNS_AUTH_ID, CLOUDNS_AUTH_PASSWORD Additional configuration
Cloudflare cloudflare CF_API_EMAIL, CF_API_KEY 1 or CF_DNS_API_TOKEN, [CF_ZONE_API_TOKEN] Additional configuration
CloudXNS cloudxns CLOUDXNS_API_KEY, CLOUDXNS_SECRET_KEY Additional configuration
ConoHa conoha CONOHA_TENANT_ID, CONOHA_API_USERNAME, CONOHA_API_PASSWORD Additional configuration
Constellix constellix CONSTELLIX_API_KEY, CONSTELLIX_SECRET_KEY Additional configuration
deSEC desec DESEC_TOKEN Additional configuration
DigitalOcean digitalocean DO_AUTH_TOKEN Additional configuration
DNSimple dnsimple DNSIMPLE_OAUTH_TOKEN, DNSIMPLE_BASE_URL Additional configuration
DNS Made Easy dnsmadeeasy DNSMADEEASY_API_KEY, DNSMADEEASY_API_SECRET, DNSMADEEASY_SANDBOX Additional configuration
DNSPod dnspod DNSPOD_API_KEY Additional configuration
Domain Offensive (do.de) dode DODE_TOKEN Additional configuration
DreamHost dreamhost DREAMHOST_API_KEY Additional configuration
Duck DNS duckdns DUCKDNS_TOKEN Additional configuration
Dyn dyn DYN_CUSTOMER_NAME, DYN_USER_NAME, DYN_PASSWORD Additional configuration
Dynu dynu DYNU_API_KEY Additional configuration
EasyDNS easydns EASYDNS_TOKEN, EASYDNS_KEY Additional configuration
EdgeDNS edgedns AKAMAI_CLIENT_TOKEN, AKAMAI_CLIENT_SECRET, AKAMAI_ACCESS_TOKEN Additional configuration
External Program exec EXEC_PATH Additional configuration
Exoscale exoscale EXOSCALE_API_KEY, EXOSCALE_API_SECRET, EXOSCALE_ENDPOINT Additional configuration
Fast DNS fastdns AKAMAI_CLIENT_TOKEN, AKAMAI_CLIENT_SECRET, AKAMAI_ACCESS_TOKEN Additional configuration
Gandi gandi GANDI_API_KEY Additional configuration
Gandi v5 gandiv5 GANDIV5_API_KEY Additional configuration
Glesys glesys GLESYS_API_USER, GLESYS_API_KEY, GLESYS_DOMAIN Additional configuration
GoDaddy godaddy GODADDY_API_KEY, GODADDY_API_SECRET Additional configuration
Google Cloud DNS gcloud GCE_PROJECT, Application Default Credentials 2 3, [GCE_SERVICE_ACCOUNT_FILE] Additional configuration
Hetzner hetzner HETZNER_API_KEY Additional configuration
hosting.de hostingde HOSTINGDE_API_KEY, HOSTINGDE_ZONE_NAME Additional configuration
HTTP request httpreq HTTPREQ_ENDPOINT, HTTPREQ_MODE, HTTPREQ_USERNAME, HTTPREQ_PASSWORD 4 Additional configuration
HyperOne hyperone HYPERONE_PASSPORT_LOCATION, HYPERONE_LOCATION_ID Additional configuration
IIJ iij IIJ_API_ACCESS_KEY, IIJ_API_SECRET_KEY, IIJ_DO_SERVICE_CODE Additional configuration
INWX inwx INWX_USERNAME, INWX_PASSWORD Additional configuration
Joker.com joker JOKER_API_KEY or JOKER_USERNAME, JOKER_PASSWORD Additional configuration
Lightsail lightsail AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, DNS_ZONE Additional configuration
Linode v4 linode LINODE_TOKEN Additional configuration
Liquid Web liquidweb LIQUID_WEB_PASSWORD, LIQUID_WEB_USERNAME, LIQUID_WEB_ZONE Additional configuration
LuaDNS luadns LUADNS_API_USERNAME, LUADNS_API_TOKEN Additional configuration
manual manual none, but you need to run Traefik interactively 5, turn on debug log to see instructions and press Enter.
MyDNS.jp mydnsjp MYDNSJP_MASTER_ID, MYDNSJP_PASSWORD Additional configuration
Mythic Beasts mythicbeasts MYTHICBEASTS_USER_NAME, MYTHICBEASTS_PASSWORD Additional configuration
Namecheap namecheap NAMECHEAP_API_USER, NAMECHEAP_API_KEY Additional configuration
name.com namedotcom NAMECOM_USERNAME, NAMECOM_API_TOKEN, NAMECOM_SERVER Additional configuration
Namesilo namesilo NAMESILO_API_KEY Additional configuration
Netcup netcup NETCUP_CUSTOMER_NUMBER, NETCUP_API_KEY, NETCUP_API_PASSWORD Additional configuration
Netlify netlify NETLIFY_TOKEN Additional configuration
NIFCloud nifcloud NIFCLOUD_ACCESS_KEY_ID, NIFCLOUD_SECRET_ACCESS_KEY Additional configuration
NS1 ns1 NS1_API_KEY Additional configuration
Open Telekom Cloud otc OTC_DOMAIN_NAME, OTC_USER_NAME, OTC_PASSWORD, OTC_PROJECT_NAME, OTC_IDENTITY_ENDPOINT Additional configuration
OVH ovh OVH_ENDPOINT, OVH_APPLICATION_KEY, OVH_APPLICATION_SECRET, OVH_CONSUMER_KEY Additional configuration
Openstack Designate designate OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_TENANT_NAME, OS_REGION_NAME Additional configuration
Oracle Cloud oraclecloud OCI_COMPARTMENT_OCID, OCI_PRIVKEY_FILE, OCI_PRIVKEY_PASS, OCI_PUBKEY_FINGERPRINT, OCI_REGION, OCI_TENANCY_OCID, OCI_USER_OCID Additional configuration
PowerDNS pdns PDNS_API_KEY, PDNS_API_URL Additional configuration
Rackspace rackspace RACKSPACE_USER, RACKSPACE_API_KEY Additional configuration
reg.ru regru REGRU_USERNAME, REGRU_PASSWORD Additional configuration
RFC2136 rfc2136 RFC2136_TSIG_KEY, RFC2136_TSIG_SECRET, RFC2136_TSIG_ALGORITHM, RFC2136_NAMESERVER Additional configuration
Route 53 route53 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, [AWS_REGION], [AWS_HOSTED_ZONE_ID] or a configured user/instance IAM profile. Additional configuration
RimuHosting rimuhosting RIMUHOSTING_API_KEY Additional configuration
Sakura Cloud sakuracloud SAKURACLOUD_ACCESS_TOKEN, SAKURACLOUD_ACCESS_TOKEN_SECRET Additional configuration
Scaleway scaleway SCALEWAY_API_TOKEN Additional configuration
Selectel selectel SELECTEL_API_TOKEN Additional configuration
Servercow servercow SERVERCOW_USERNAME, SERVERCOW_PASSWORD Additional configuration
Stackpath stackpath STACKPATH_CLIENT_ID, STACKPATH_CLIENT_SECRET, STACKPATH_STACK_ID Additional configuration
TransIP transip TRANSIP_ACCOUNT_NAME, TRANSIP_PRIVATE_KEY_PATH Additional configuration
VegaDNS vegadns SECRET_VEGADNS_KEY, SECRET_VEGADNS_SECRET, VEGADNS_URL Additional configuration
Versio versio VERSIO_USERNAME, VERSIO_PASSWORD Additional configuration
Vscale vscale VSCALE_API_TOKEN Additional configuration
VULTR vultr VULTR_API_KEY Additional configuration
Yandex yandex YANDEX_PDD_TOKEN Additional configuration
Zone.ee zoneee ZONEEE_API_USER, ZONEEE_API_KEY Additional configuration
Zonomi zonomi ZONOMI_API_KEY Additional configuration

!!! info "delayBeforeCheck" By default, the provider verifies the TXT record before letting ACME verify. You can delay this operation by specifying a delay (in seconds) with delayBeforeCheck (value must be greater than zero). This option is useful when internal networks block external DNS queries.

resolvers

Use custom DNS servers to resolve the FQDN authority.

[certificatesResolvers.myresolver.acme]
  # ...
  [certificatesResolvers.myresolver.acme.dnsChallenge]
    # ...
    resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
certificatesResolvers:
  myresolver:
    acme:
      # ...
      dnsChallenge:
        # ...
        resolvers:
          - "1.1.1.1:53"
          - "8.8.8.8:53"
# ...
--certificatesresolvers.myresolver.acme.dnschallenge.resolvers=1.1.1.1:53,8.8.8.8:53

Wildcard Domains

ACME V2 supports wildcard certificates. As described in Let's Encrypt's post wildcard certificates can only be generated through a DNS-01 challenge.

More Configuration

caServer

Required, Default="https://acme-v02.api.letsencrypt.org/directory"

The CA server to use:

??? example "Using the Let's Encrypt staging server"

```toml tab="File (TOML)"
[certificatesResolvers.myresolver.acme]
  # ...
  caServer = "https://acme-staging-v02.api.letsencrypt.org/directory"
  # ...
```

```yaml tab="File (YAML)"
certificatesResolvers:
  myresolver:
    acme:
      # ...
      caServer: https://acme-staging-v02.api.letsencrypt.org/directory
      # ...
```

```bash tab="CLI"
# ...
--certificatesresolvers.myresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory
# ...
```

storage

Required, Default="acme.json"

The storage option sets the location where your ACME certificates are saved to.

[certificatesResolvers.myresolver.acme]
  # ...
  storage = "acme.json"
  # ...
certificatesResolvers:
  myresolver:
    acme:
      # ...
      storage: acme.json
      # ...
# ...
--certificatesresolvers.myresolver.acme.storage=acme.json
# ...

ACME certificates are stored in a JSON file that needs to have a 600 file mode.

In Docker you can mount either the JSON file, or the folder containing it:

docker run -v "/my/host/acme.json:/acme.json" traefik
docker run -v "/my/host/acme:/etc/traefik/acme" traefik

!!! warning For concurrency reasons, this file cannot be shared across multiple instances of Traefik.

preferredChain

Optional, Default=""

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.

[certificatesResolvers.myresolver.acme]
  # ...
  preferredChain = "ISRG Root X1"
  # ...
certificatesResolvers:
  myresolver:
    acme:
      # ...
      preferredChain: 'ISRG Root X1'
      # ...
# ...
--certificatesresolvers.myresolver.acme.preferredChain="ISRG Root X1"
# ...

Fallback

If Let's Encrypt is not reachable, the following certificates will apply:

  1. Previously generated ACME certificates (before downtime)
  2. Expired ACME certificates
  3. Provided certificates

!!! important For new (sub)domains which need Let's Encrypt authentication, the default Traefik certificate will be used until Traefik is restarted.


  1. The Global API Key needs to be used, not the Origin CA Key. ↩︎

  2. providing_credentials_to_your_application ↩︎

  3. google/default.go ↩︎

  4. more information about the HTTP message format can be found here ↩︎

  5. docker stack remark: there is no way to support terminal attached to container when deploying with docker stack, so you might need to run container with docker run -it to generate certificates using manual provider. ↩︎