Vault Certificate Resolver

The Vault certificate resolver allows Traefik Enterprise to use a Vault server with the PKI secret engine enabled as a certificate resolver. This is a brief overview of how to configure Vault PKI. For a more in-depth tutorial, consult the user guide

In order to use the Vault certificate resolver, Traefik Enterprise needs access to a Vault server with the PKI secret engine enabled and set up. You can find more information on how to do so here. Note that the role used by the Vault certificate resolver needs to be configured with at least one of ttl or max_ttl explicitly set.

Once the Vault server is ready, a Vault certificate resolver can be added in Traefik Enterprise's static configuration:

File (YAML)

certificatesResolvers:
  resolverName:
    vault:
      url: "http://127.0.0.1:8200"
      token: "s.CUDDqqjiIFXF60KVSeJOxeb5"
      enginePath: "pki"
      role: "vault-role"

File (TOML)

[certificatesResolvers.resolverName.vault]
  url = "http://127.0.0.1:8200"
  token = "s.CUDDqqjiIFXF60KVSeJOxeb5"
  enginePath = "pki"
  role = "vault-role"

Next, define a router that references this certificate resolver:

Docker

labels:
  - "traefik.http.routers.routerName.rules=Host(`example.com`)"
  - "traefik.http.routers.routerName.tls.certResolver=resolverName"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: example
spec:
  routes:
    - match: Host(`example.com`)
      kind: Rule
  tls:
    certResolver: resolverName

Consul Catalog

- "traefik.http.routers.routerName.rules=Host(`example.com`)"
- "traefik.http.routers.routerName.tls.certResolver=resolverName"

Marathon

"labels": {
    "traefik.http.routers.routerName.rules": "Host(`example.com`)",
    "traefik.http.routers.routerName.tls.certResolver": "resolverName"
}

Rancher

labels:
  - "traefik.http.routers.routerName.rules=Host(`example.com`)"
  - "traefik.http.routers.routerName.tls.certResolver=resolverName"

File (YAML)

http:
  routers:
    routerName:
      rules: "Host(`example.com`)"
      tls:
        certResolver: "resolverName"

File (TOML)

[http.routers]
  [http.routers.routerName]
    rules = "Host(`example.com`)"
    [http.routers.routerName.tls]
      certResolver = "resolverName"

Certificates are generated accordingly to the role configuration. This means their maximum time-to-live (TTL) is equal to either the ttl or the max_ttl of the role, whichever has the lowest value.

Once a certificate reaches ⅔ of its lifetime, the Vault certificate resolver tries to renew it. If this operation fails, the old certificate will continue to be served until it expires or another renewal attempt succeeds.

Changing the role's TTL

The Vault certificate resolver regularly verifies if the role configuration has been modified. If the lowest value between ttl and max_ttl is changed, a renewal process starts for all certificates issued by the certificate resolver. This is done so certificates handled by the resolver always reflect the role configuration.

Certificate Resolver Configuration

url

Required, Default=""

Defines the URL of the Vault server, including the scheme and port.

File (YAML)

certificatesResolvers:
  resolverName:
    vault:
      url: "http://127.0.0.1:8200"

File (TOML)

[certificatesResolvers.resolverName.vault]
  url = "http://127.0.0.1:8200"

token

Required, Default=""

Defines the token to authenticate with Vault.

Supported Authentication Mechanisms

The Vault certificate resolver currently supports token authentication only.

File (YAML)

certificatesResolvers:
  resolverName:
    vault:
      token: "s.CUDDqqjiIFXF60KVSeJOxeb5"

File (TOML)

[certificatesResolvers.resolverName.vault]
  token = "s.CUDDqqjiIFXF60KVSeJOxeb5"

enginePath

Optional, Default="pki"

Defines the path under which the PKI secret engine is enabled.

File (YAML)

certificatesResolvers:
  resolverName:
    vault:
      enginePath: "pki"

File (TOML)

[certificatesResolvers.resolverName.vault]
  enginePath = "pki"

role

Required, Default=""

The role used to issue certificates.

Role configuration

The role used by the Vault certificate resolver needs to be configured with at least one of ttl or max_ttl explicitly set. These are used to know the maximum time-to-live (TTL) of certificates.

File (YAML)

certificatesResolvers:
  resolverName:
    vault:
      role: "vault-role"

File (TOML)

[certificatesResolvers.resolverName.vault]
  role = "vault-role"