» Vault as a Connect CA

Consul can be used with Vault to manage and sign certificates. The Vault CA provider uses the Vault PKI secrets engine to generate and sign certificates.

This page documents the specifics of the built-in CA provider. Please read the certificate management overview page first to understand how Consul manages certificates with configurable CA providers.

» Requirements

Prior to using Vault as a CA provider for Consul, the following requirements must be met:

Vault 0.10.3 or later. Consul uses URI SANs in the PKI engine which were introduced in Vault 0.10.3. Prior versions of Vault are not compatible with Connect.

» Configuration

The Vault CA is enabled by setting the ca_provider to "vault" and setting the required configuration values. An example configuration is shown below:

connect {
    enabled = true
    ca_provider = "vault"
    ca_config {
        address = "http://localhost:8200"
        token = "..."
        root_pki_path = "connect-root"
        intermediate_pki_path = "connect-intermediate"
    }
}

The set of configuration options is listed below. The first key is the value used in API calls while the second key (after the /) is used if configuring in an agent configuration file.

Address / address (string: <required>) - The address of the Vault server.
Token / token (string: <required>) - A token for accessing Vault. This is write-only and will not be exposed when reading the CA configuration. This token must have proper privileges for the PKI paths configured.
RootPKIPath / root_pki_path (string: <required>) - The path to a PKI secrets engine for the root certificate. If the path doesn't exist, Consul will attempt to mount and configure this automatically.
IntermediatePKIPath / intermediate_pki_path (string: <required>) - The path to a PKI secrets engine for the generated intermediate certificate. This certificate will be signed by the configured root PKI path. If this path doesn't exist, Consul will attempt to mount and configure this automatically.
CAFile / ca_file (string: "") - Specifies an optional path to the CA certificate used for Vault communication. If unspecified, this will fallback to the default system CA bundle, which varies by OS and version.
CAPath / ca_path (string: "") - Specifies an optional path to a folder containing CA certificates to be used for Vault communication. If unspecified, this will fallback to the default system CA bundle, which varies by OS and version.
CertFile / cert_file (string: "") - Specifies the path to the certificate used for Vault communication. If this is set then you need to also set tls_key_file.
KeyFile / key_file (string: "") - Specifies the path to the private key used for Vault communication. If this is set then you need to also set cert_file.
TLSServerName / tls_server_name (string: "") - Specifies an optional string used to set the SNI host when connecting to Vault via TLS.
TLSSkipVerify / tls_skip_verify (bool: false) - Specifies if SSL peer validation should be enforced.

» Root and Intermediate PKI Paths

The Vault CA provider uses two separately configured PKI secrets engines for managing Connect certificates.

The RootPKIPath is the PKI engine for the root certificate. Consul will use this root certificate to sign the intermediate certificate. Consul will never attempt to write or modify any data within the root PKI path.

The IntermediatePKIPath is the PKI engine used for storing the intermediate signed with the root certificate. The intermediate is used to sign all leaf certificates and Consul may periodically generate new intermediates for automatic rotation. Therefore, Consul requires write access to this path.

If either path does not exist, then Consul will attempt to mount and initialize it. This requires additional privileges by the Vault token in use. If the paths already exist, Consul will use them as configured.