Vault Provider

The Vault provider allows Traefik Enterprise to use TLS certificates stored in Vault using the KV secret engine version 2.

All certificates must be stored base64-encoded in the data map under the cert and key keys, respectively.

Using cURL

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Vault-Token: <Vault token>" \
    -d '{"data": {"cert": "<base64-encoded certificate>", "key": "<base64-encoded key>"}}' \
    http://127.0.0.1:8200/v1/secret/data/example.org

Using the Vault CLI

vault kv put secret/example.org cert="$(cat cert.pem | base64 -w0)" key="$(cat key.pem | base64 -w0)"

Path Requirement

The Vault TLS provider requires all secrets to be at the root of the KV secret engine.

Dedicated KV Secret Engine

It is recommended to use a dedicated KV secret engine in Vault to store TLS certificates.

Provider Configuration

The Vault provider is enabled and configured in the static configuration:

File (YAML)

providers:
  plugin:
    vault:
      url: "http://127.0.0.1:8200"
      auth:
        token: "s.CUDDqqjiIFXF60KVSeJOxeb5"
      enginePath: "secret"
      syncInterval: "5s"
      rescanInterval: "60s"

File (TOML)

[providers.plugin.vault]
  url = "http://127.0.0.1:8200"
  enginePath = "secret"
  syncInterval = "5s"
  rescanInterval = "60s"
  [certificatesResolvers.resolverName.vault.auth]
    token = "s.CUDDqqjiIFXF60KVSeJOxeb5"

url

Required, Default=""

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

File (YAML)

providers:
  plugin:
    vault:
      url: "http://127.0.0.1:8200"

File (TOML)

[providers.plugin.vault]
  url = "http://127.0.0.1:8200"

tls.caBundle

Optional, Default=""

An optional caBundle containing a PEM-encoded certificate bundle or a path to a file containing the certificate bundle used to establish a TLS connection with the Vault server.

Using a File

Note that TraefikEE does not watch for file changes. If caBundle is set to a file path, its content will be read once when the certificate resolver is initialized but if the file is modified the resolver will need to be restarted to take the latest changes into effect.

File (YAML) using content

providers:
  plugin:
    vault:
      tls:
        caBundle: |-
          -----BEGIN CERTIFICATE-----
          MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNV
          BAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl
          Y29kaW5nIG1lPyAgVGhpcyBpcyBvbmx5IGEgdGVzdCEhITERMA8GA1UEBwwISGFt
          aWx0b24xETAPBgNVBAgMCFBlbWJyb2tlMQswCQYDVQQGEwJCTTEPMA0GCSqGSIb3
          DQEJARYAMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCJ9WRanG/fUvcfKiGl
          EL4aRLjGt537mZ28UU9/3eiJeJznNSOuNLnF+hmabAu7H0LT4K7EdqfF+XUZW/2j
          RKRYcvOUDGF9A7OjW7UfKk1In3+6QDCi7X34RE161jqoaJjrm/T18TOKcgkkhRzE
          apQnIDm0Ea/HVzX/PiSOGuertwIDAQABMAsGCSqGSIb3DQEBBQOBgQBzMJdAV4QP
          Awel8LzGx5uMOshezF/KfP67wJ93UW+N7zXY6AwPgoLj4Kjw+WtU684JL8Dtr9FX
          ozakE+8p06BpxegR4BR3FMHf6p+0jQxUEAkAyb/mVgm66TyghDGC6/YkiKoZptXQ
          98TwDIK/39WEB/V607As+KoYazQG8drorw==
          -----END CERTIFICATE-----

File (YAML) using file path

providers:
  plugin:
    vault:
      tls:
        caBundle: /etc/tls/ca-bundle.pem

File (TOML)

[providers.plugin.vault.tls]
  caBundle = """
-----BEGIN CERTIFICATE-----
MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNV
BAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl
Y29kaW5nIG1lPyAgVGhpcyBpcyBvbmx5IGEgdGVzdCEhITERMA8GA1UEBwwISGFt
aWx0b24xETAPBgNVBAgMCFBlbWJyb2tlMQswCQYDVQQGEwJCTTEPMA0GCSqGSIb3
DQEJARYAMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCJ9WRanG/fUvcfKiGl
EL4aRLjGt537mZ28UU9/3eiJeJznNSOuNLnF+hmabAu7H0LT4K7EdqfF+XUZW/2j
RKRYcvOUDGF9A7OjW7UfKk1In3+6QDCi7X34RE161jqoaJjrm/T18TOKcgkkhRzE
apQnIDm0Ea/HVzX/PiSOGuertwIDAQABMAsGCSqGSIb3DQEBBQOBgQBzMJdAV4QP
Awel8LzGx5uMOshezF/KfP67wJ93UW+N7zXY6AwPgoLj4Kjw+WtU684JL8Dtr9FX
ozakE+8p06BpxegR4BR3FMHf6p+0jQxUEAkAyb/mVgm66TyghDGC6/YkiKoZptXQ
98TwDIK/39WEB/V607As+KoYazQG8drorw==
-----END CERTIFICATE-----
"""

File (TOML) using file path

[providers.plugin.vault.tls]
        caBundle = "/etc/tls/ca-bundle.pem"

tls.insecureSkipVerify

Optional, Default=false

Disables TLS certificate verification when communicating with Vault. Useful for testing purposes but strongly discouraged for production.

File (YAML)

providers:
  plugin:
    vault:
      tls:
        insecureSkipVerify: true

File (TOML)

[providers.plugin.vault.tls]
  insecureSkipVerify = true

token (deprecated)

Deprecated, Default=""

Defines the token to authenticate with Vault.

Deprecated

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

File (YAML)

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

File (TOML)

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

enginePath

Optional, Default="secret"

Defines the path under which the KV 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 secret under the default namespace, set default/secret as the engine path.

File (YAML)

providers:
  plugin:
    vault:
      enginePath: "secret"

File (TOML)

[providers.plugin.vault]
  enginePath = "secret"

File (YAML)

providers:
  plugin:
    vault:
      enginePath: "secret"

syncInterval

Optional, Default="5s"

Defines the interval at which the Vault provider looks for new or deleted TLS certificates.

File (YAML)

providers:
  plugin:
    vault:
      syncInterval: "5s"

File (TOML)

[providers.plugin.vault]
  syncInterval = "5s"

rescanInterval

Optional, Default="60s"

Defines the interval at which the Vault provider performs a full rescan of all TLS certificates to check for updates.

Rescanning with Many Certificates

This operation performs at least one request per certificate stored in Vault. If there are many certificates, this interval may need to be increased to reduce load on Vault.

File (YAML)

providers:
  plugin:
    vault:
      rescanInterval: "60s"

File (TOML)

[providers.plugin.vault]
  rescanInterval = "60s"

auth.token

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

Defines the token to authenticate with Vault.

File (YAML)

providers:
  plugin:
    vault:
      auth:
        token: "s.CUDDqqjiIFXF60KVSeJOxeb5"

File (TOML)

[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.

File (YAML)

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

File (TOML)

[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.

File (YAML)

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

File (TOML)

[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.

File (YAML)

providers:
  plugin:
    vault:
      auth:
        appRole:
          path: "customAppRolePath"

File (TOML)

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