Skip to content

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:

certificatesResolvers:
  resolverName:
    vault:
      url: "http://127.0.0.1:8200"
      token: "s.CUDDqqjiIFXF60KVSeJOxeb5"
      enginePath: "pki"
      role: "vault-role"
[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:

labels:
  - "traefik.http.routers.routerName.rules=Host(`example.com`)"
  - "traefik.http.routers.routerName.tls.certResolver=resolverName"
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: example
spec:
  routes:
    - match: Host(`example.com`)
      kind: Rule
  tls:
    certResolver: resolverName
- "traefik.http.routers.routerName.rules=Host(`example.com`)"
- "traefik.http.routers.routerName.tls.certResolver=resolverName"
"labels": {
    "traefik.http.routers.routerName.rules": "Host(`example.com`)",
    "traefik.http.routers.routerName.tls.certResolver": "resolverName"
}
labels:
  - "traefik.http.routers.routerName.rules=Host(`example.com`)"
  - "traefik.http.routers.routerName.tls.certResolver=resolverName"
http:
  routers:
    routerName:
      rules: "Host(`example.com`)"
      tls:
        certResolver: "resolverName"
[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.

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

token (deprecated)

Deprecated, Default=""

Defines the token to authenticate with Vault.

Deprecated

This option is deprecated, please use auth.token instead.

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

enginePath

Optional, Default="pki"

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

Vault Namespaces

If using Vault Namespaces, simply prefix the engine path with the name of the namespace. If using the engine path pki under the default namespace, set default/pki as the engine path.

certificatesResolvers:
  resolverName:
    vault:
      enginePath: "pki"
[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.

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

auth.token

Optional(one of auth.token or auth.appRole must be set), Default=""

Defines the token to authenticate with Vault.

providers:
  plugin:
    vault:
      auth:
        token: "s.CUDDqqjiIFXF60KVSeJOxeb5"
[providers.plugin.vault.auth]
  token = "s.CUDDqqjiIFXF60KVSeJOxeb5"

auth.appRole

Optional(one of auth.token or auth.appRole must be set), Default=None

Enables the AppRole authentication method. See auth.appRole.* options to see what needs to be provided.

auth.appRole.roleID

Required, Default=""

Defines the ID of the role to use when authenticating to Vault with AppRole.

providers:
  plugin:
    vault:
      auth:
        appRole:
          roleID: "4cf1dc0d-f431-f76d-42fd-ed1264f0b893"
[providers.plugin.vault.auth.appRole]
  roleID = "4cf1dc0d-f431-f76d-42fd-ed1264f0b893"

auth.appRole.secretID

Required, Default=""

Defines the ID of the secret to use when authenticating to Vault with AppRole.

providers:
  plugin:
    vault:
      auth:
        appRole:
          secretID: "63cffb45-b404-18c4-cdbb-af723aaef1e7"
[providers.plugin.vault.auth.appRole]
  secretID = "63cffb45-b404-18c4-cdbb-af723aaef1e7"

auth.appRole.path

Optional, Default="approle"

Defines the path under which the AppRole authentication method is enabled in Vault.

providers:
  plugin:
    vault:
      auth:
        appRole:
          path: "customAppRolePath"
[providers.plugin.vault.auth.appRole]
  path = "customAppRolePath"