You can configure Consul to use [Vault](https://www.vaultproject.io/) as the certificate authority (CA) so that Vault can manage and sign certificates distributed to services in the mesh.
The Vault CA provider uses the [Vault PKI secrets engine](https://www.vaultproject.io/docs/secrets/pki) to generate and sign certificates.
This page describes how configure the Vault CA provider.
This page documents the specifics of the Vault CA provider.
Please read the [certificate management overview](/docs/connect/ca)
page first to understand how Consul manages certificates with configurable
CA providers.
-> **Tip:** Complete the [tutorial](https://learn.hashicorp.com/tutorials/consul/vault-pki-consul-connect-ca?in=consul/vault-secure) to learn how to configure Vault as the Consul Connect service mesh Certification Authority.
> **Tutorial:** Complete the [Vault as Consul Service Mesh Certification Authority](/consul/tutorials/vault-secure/vault-pki-consul-connect-ca) tutorial for hands-on guidance on how to configure Vault as the Consul service mesh certification authority.
## 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.
- Refer to [Service Mesh Certificate Authority Overview](/docs/connect/ca) for important background information about how Consul manages certificates with configurable CA providers.
~> **Note:** Do not use Vault v1.11.0+ as Consul's Connect CA provider — the intermediate CA will become unable to issue the leaf nodes required by service mesh, and by Consul client agents if using auto-encrypt or auto-config and using TLS for agent communication. If you are already using Vault 1.11+ as a Connect CA, refer to this [Knowledge Base article](https://support.hashicorp.com/hc/en-us/articles/11308460105491) for more information about the underlying cause and recommended workaround.
- Vault 0.10.3 to 1.10.x.
## Configuration
~> **Compatibility warning:** Do not use Vault v1.11.0+ as Consul's Connect CA provider — the intermediate CA becomes unable to issue the leaf nodes required by service mesh, and by Consul client agents if using auto-encrypt or auto-config and using TLS for agent communication. If you are already using Vault 1.11+ as a Connect CA, refer to this [Knowledge Base article](https://support.hashicorp.com/hc/en-us/articles/11308460105491) for more information about the underlying cause and recommended workaround.
The Vault CA is enabled by setting the CA provider to `"vault"` and
setting the required configuration values.
## Enable Vault as the CA
The configuration may either be provided in the agent's configuration file using
the [`ca_provider`] and [`ca_config`] options, or configured using the
[`/connect/ca/configuration`] API endpoint.
You can enable Vault as the CA by configuring Consul to use `"vault"` as the CA provider
and including the required provider configuration options.
You can provide the CA configuration in the server agents' configuration file
or in the body of a `PUT` request to the
[`/connect/ca/configuration`](/api-docs/connect/ca#update-ca-configuration) API endpoint.
Refer to the [Configuration Reference](#configuration-reference) for details about configuration options and for example use cases.
Example configurations are shown below:
The following example shows the required configurations for a default implementation:
<CodeTabs heading="Connect CA configuration" tabs={["Agent configuration", "API"]}>
Vault PKI can be managed by either Consul or by Vault. If you want to manually create and tune the PKI secret engines used to store the root and intermediate certificates, use Vault Managed PKI Paths. If you want to have the PKI automatically managed for you, use Consul Managed PKI Paths.
The Vault CA provider requires a [Vault token](#token) with a specific set of Vault privileges
depending on whether you would prefer to control mount configuration from Vault or to delegate
that responsibility to Consul.
### Vault Managed PKI Paths
Use [Vault-managed PKI paths](#vault-managed-pki-paths) to obtain the following benefits:
- Enables use of a root CA external to Consul by instantiating the PKI secrets engine at
[`RootPKIPath`](#rootpkipath) with an intermediate certificate
- Retain full control over PKI mount creation, and over `RootPKIPath` mount configuration
The following Vault policy allows Consul to use pre-existing PKI paths in Vault.
Consul is granted read-only access to the PKI mount points and the Root CA, but is
granted full control of the Intermediate or Leaf CA for Connect clients.
Otherwise, use [Consul-managed PKI paths](#consul-managed-pki-paths) to let Consul fully automate PKI management.
In this example the `RootPKIPath` is `connect_root` and the `IntermediatePKIPath`
is `connect_inter`. These values should be updated for your environment.
The following sections describe the Vault policy needed for both options.
The policy snippets use placeholder values for `RootPKIPath` and `IntermediatePKIPath`.
Replace them to match the path values in your CA provider configuration.
Jared Kirschner
2 years ago
committed by