mirror of https://github.com/status-im/consul.git
375 lines
16 KiB
Plaintext
375 lines
16 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Service Mesh Certificate Authority - Vault
|
|
description: >-
|
|
You can use a Vault PKI secrets engine as the Consul service mesh's certificate authority to secure your service mesh. Learn how to configure the Vault CA as a root CA or an intermediate CA connected to an existing PKI system, and how to manage PKI paths with either Vault or Consul.
|
|
---
|
|
|
|
# Vault as a Service Mesh Certificate Authority
|
|
|
|
You can configure Consul to use [Vault](/vault) 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](/vault/docs/secrets/pki) to generate and sign certificates.
|
|
This page describes how configure the Vault CA provider.
|
|
|
|
> **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
|
|
|
|
- Vault 0.10.3 or higher
|
|
|
|
~> **Compatibility note:** If you use Vault 1.11.0+ as Consul's service mesh CA, versions of Consul released before Dec 13, 2022 will develop an issue with Consul control plane or service mesh communication ([GH-15525](https://github.com/hashicorp/consul/pull/15525)). Use or upgrade to a [Consul version that includes the fix](https://support.hashicorp.com/hc/en-us/articles/11308460105491#01GMC24E6PPGXMRX8DMT4HZYTW) to avoid this problem.
|
|
|
|
## Recommendations
|
|
|
|
- Refer to [Service Mesh Certificate Authority Overview](/consul/docs/connect/ca) for important background information about how Consul manages certificates with configurable CA providers.
|
|
|
|
- For best performance and resiliency, every datacenter should have a Vault cluster local to its Consul cluster.
|
|
|
|
- If your Consul datacenters are WAN-federated and the secondary datacenter uses Vault Enterprise
|
|
[performance secondaries](/vault/docs/enterprise/replication#performance-replication), we recommend
|
|
configuring [`local`](/vault/docs/enterprise/replication#local) mounts for their [`intermediate_pki_path`](/consul/docs/connect/ca/vault#intermediatepkipath).
|
|
|
|
## Enable Vault as the CA
|
|
|
|
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`](/consul/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.
|
|
|
|
The following example shows the required configurations for a default implementation:
|
|
|
|
<CodeTabs heading="Service mesh CA configuration" tabs={["Agent configuration", "API"]}>
|
|
|
|
<CodeBlockConfig filename="/etc/consul.d/config.hcl" highlight="4,6-9">
|
|
|
|
```hcl
|
|
# ...
|
|
connect {
|
|
enabled = true
|
|
ca_provider = "vault"
|
|
ca_config {
|
|
address = "http://localhost:8200"
|
|
token = "<vault-token-with-necessary-policy>"
|
|
root_pki_path = "connect-root"
|
|
intermediate_pki_path = "connect-dc1-intermediate"
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
<CodeBlockConfig highlight="2,4-7">
|
|
|
|
```json
|
|
{
|
|
"Provider": "vault",
|
|
"Config": {
|
|
"Address": "http://localhost:8200",
|
|
"Token": "<vault-token-with-necessary-policy>",
|
|
"RootPKIPath": "connect-root",
|
|
"IntermediatePKIPath": "connect-dc1-intermediate"
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
</CodeTabs>
|
|
|
|
## Configuration Reference
|
|
|
|
You can specify the following configuration options.
|
|
Note that a configuration option's name may differ between API calls and the agent configuration file.
|
|
The first key refers to the option name for use in API calls.
|
|
The key after the slash refers to the corresponding option name in the agent configuration file.
|
|
|
|
- `Address` / `address` (`string: <required>`) - The address of the Vault
|
|
server.
|
|
|
|
- `Token` / `token` (`string: ""`) - 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](#vault-acl-policies) for the PKI
|
|
paths configured. In Consul 1.8.5 and later, if the token has the [renewable](/vault/api-docs/auth/token#renewable)
|
|
flag set, Consul will attempt to renew its lease periodically after half the
|
|
duration has expired.
|
|
|
|
!> **Warning:** You must either provide a token or configure an auth method below.
|
|
|
|
- `AuthMethod` / `auth_method` (`map: nil`) - Vault auth method to use for logging in to Vault.
|
|
Please see [Vault Auth Methods](/vault/docs/auth) for more information
|
|
on how to configure individual auth methods. If auth method is provided, Consul will obtain
|
|
a new token from Vault when the token can no longer be renewed.
|
|
|
|
- `Type`/ `type` (`string: ""`) - The type of Vault auth method. Valid options are "approle", "aws", "azure", "gcp", "jwt" and "kubernetes".
|
|
|
|
- `MountPath`/ `mount_path` (`string: <AuthMethod.Type>`) - The mount path of the auth method.
|
|
If not provided the auth method type will be used as the mount path.
|
|
|
|
- `Params`/`params` (`map: nil`) - The parameters to configure the auth method. The required configuration parameters depend on which auth type you are using. Refer to the Vault Agent auto-auth method documentation for details on their configuration options: [AppRole](/vault/docs/agent-and-proxy/autoauth/methods/approle#configuration), [AWS](/vault/docs/agent-and-proxy/autoauth/methods/aws#configuration), [Azure](/vault/docs/agent-and-proxy/autoauth/methods/azure#configuration), [GCP](/vault/docs/agent-and-proxy/autoauth/methods/gcp#configuration), [JWT](/vault/docs/agent-and-proxy/autoauth/methods/jwt#configuration), [Kubernetes](/vault/docs/agent-and-proxy/autoauth/methods/kubernetes#configuration).
|
|
|
|
Only the authentication related fields (for example, JWT's `path` and `role`) are supported. The optional management fields (for example: `remove_jwt_after_reading`) are not supported.
|
|
|
|
- `RootPKIPath` / `root_pki_path` (`string: <required>`) - The path to
|
|
a PKI secrets engine for the root certificate. Required for primary
|
|
datacenters. Secondary datacenters do not use this path.
|
|
|
|
If the path does not
|
|
exist, Consul will mount a new PKI secrets engine at the specified path with the
|
|
`RootCertTTL` value as the root certificate's TTL. If the `RootCertTTL` is not set,
|
|
a [`max_lease_ttl`](/vault/api-docs/system/mounts)
|
|
of 87600 hours, or 10 years is applied by default as of Consul 1.11 and later. Prior to Consul 1.11,
|
|
the root certificate TTL was set to 8760 hour, or 1 year, and was not configurable.
|
|
The root certificate will expire at the end of the specified period.
|
|
|
|
To use an intermediate certificate as the primary CA in Consul, initialize the
|
|
`RootPKIPath` in Vault with a PEM bundle. The first certificate in the bundle
|
|
must be the intermediate certificate that Consul will use as the primary CA.
|
|
The last certificate in the bundle must be a root certificate. The bundle
|
|
must contain a valid chain, where each certificate is followed by the certificate
|
|
that authorized it.
|
|
|
|
- `RootPKINamespace` / `root_pki_namespace` (`string: <optional>`) - The absolute namespace
|
|
that the `RootPKIPath` is in. Setting this parameter overrides the `Namespace` option for the `RootPKIPath`. Introduced in 1.12.3.
|
|
|
|
- `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 does not exist, Consul will attempt to mount and configure this
|
|
automatically.
|
|
|
|
When WAN federation is enabled, every secondary datacenter that shares a common Vault cluster
|
|
must specify a unique `intermediate_pki_path`. If a Vault cluster is not used by more than one Consul datacenter,
|
|
then you do not need to specify a unique value for the `intermediate_pki_path`. We still recommend using a
|
|
unique `intermediate_pki_path` for each datacenter, however, to improve operational and diagnostic clarity.
|
|
|
|
- `IntermediatePKINamespace` / `intermediate_pki_namespace` (`string: <optional>`) - The absolute namespace
|
|
that the `IntermediatePKIPath` is in. Setting this parameter overrides the `Namespace` option for the `IntermediatePKIPath`. Introduced in 1.12.3.
|
|
|
|
- `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 also need to
|
|
set `key_file`.
|
|
|
|
- `KeyFile` / `key_file` (`string: ""`) - Specifies the path to the private
|
|
key used for Vault communication. If this is set, then you also need to 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.
|
|
|
|
- `Namespace` / `namespace` (`string: <optional>`) - The Vault Namespace that
|
|
the `Token` and PKI Certificates are a part of. Vault Namespaces are a Vault
|
|
Enterprise feature. Added in Consul 1.11.0
|
|
|
|
@include 'http_api_connect_ca_common_options.mdx'
|
|
|
|
### Root and Intermediate PKI Paths
|
|
|
|
The Vault CA provider uses two separately configured
|
|
[PKI secrets engines](/vault/docs/secrets/pki)
|
|
for managing Consul service mesh certificates.
|
|
|
|
The `RootPKIPath` is the PKI engine for the root certificate.
|
|
Consul uses this root certificate to sign the intermediate certificate.
|
|
Consul does not 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 signs all leaf
|
|
certificates, and Consul may periodically generate new intermediates for
|
|
automatic rotation. Therefore, Consul requires write access to this path.
|
|
|
|
For each path, if the path does not exist, Consul attempts to mount and initialize
|
|
a PKI secrets engine at that path. For this operation to succeed,
|
|
the provided [Vault token](#token) must have the [required Vault privileges](#vault-acl-policies).
|
|
If the path does already exist, Consul uses the PKI secrets engine at that path as configured.
|
|
|
|
### Configure Vault ACL policies ((#vault-acl-policies))
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
Otherwise, use [Consul-managed PKI paths](#consul-managed-pki-paths) to let Consul fully automate PKI management.
|
|
|
|
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.
|
|
|
|
#### Define a policy for Vault-managed PKI paths ((#vault-managed-pki-paths))
|
|
|
|
To use Vault-managed PKI paths, you must first instantiate and configure PKI secrets engines at
|
|
`RootPKIPath` and `IntermediatePKIPath`.
|
|
|
|
Then, attach the following Vault ACL policy to the CA provider's
|
|
[Vault token](#token) or [auth method](#authmethod):
|
|
|
|
1. Allow Consul to read both PKI mounts and to manage the intermediate PKI mount configuration:
|
|
|
|
<CodeBlockConfig filename="vault-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "/sys/mounts/<root_pki_path>" {
|
|
capabilities = [ "read" ]
|
|
}
|
|
|
|
path "/sys/mounts/<intermediate_pki_path>" {
|
|
capabilities = [ "read" ]
|
|
}
|
|
|
|
path "/sys/mounts/<intermediate_pki_path>/tune" {
|
|
capabilities = [ "update" ]
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
1. Allow Consul read-only access to the root PKI engine, to automatically rotate
|
|
intermediate CAs as needed, and full use of the intermediate PKI engine:
|
|
|
|
<CodeBlockConfig filename="vault-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "/<root_pki_path>/" {
|
|
capabilities = [ "read" ]
|
|
}
|
|
|
|
path "/<root_pki_path>/root/sign-intermediate" {
|
|
capabilities = [ "update" ]
|
|
}
|
|
|
|
path "/<intermediate_pki_path>/*" {
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
}
|
|
```
|
|
</CodeBlockConfig>
|
|
|
|
1. Allow Consul to renew its Vault token if the token is renewable.
|
|
The rule enables the token to be renewed whether it is provided
|
|
[directly](#token) in the CA provider configuration or presented in an [auth method](#authmethod).
|
|
|
|
<CodeBlockConfig filename="vault-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "auth/token/renew-self" {
|
|
capabilities = [ "update" ]
|
|
}
|
|
|
|
path "auth/token/lookup-self" {
|
|
capabilities = [ "read" ]
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
#### Define a policy for Consul-managed PKI paths ((#consul-managed-pki-paths))
|
|
|
|
To use Consul-managed PKI paths, ensure no PKI secrets engines are mounted at
|
|
`RootPKIPath` and `IntermediatePKIPath`.
|
|
|
|
Then, attach the following Vault ACL policy to the CA provider's
|
|
[Vault token](#token) or [auth method](#authmethod):
|
|
|
|
1. Allow Consul to create and manage both PKI engines:
|
|
|
|
<CodeBlockConfig filename="consul-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "/sys/mounts/<root_pki_path>" {
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
}
|
|
|
|
path "/sys/mounts/<intermediate_pki_path>" {
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
}
|
|
|
|
path "/sys/mounts/<intermediate_pki_path>/tune" {
|
|
capabilities = [ "update" ]
|
|
}
|
|
```
|
|
</CodeBlockConfig>
|
|
|
|
1. Allow Consul full use of both PKI engines:
|
|
|
|
<CodeBlockConfig filename="consul-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "/<root_pki_path>/*" {
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
}
|
|
|
|
path "/<intermediate_pki_path>/*" {
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
1. Allow Consul to renew its Vault token if the token is renewable.
|
|
The rule enables the token to be renewed whether it is provided
|
|
[directly](#token) in the CA provider configuration or presented in an [auth method](#authmethod).
|
|
|
|
<CodeBlockConfig filename="consul-managed-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "auth/token/renew-self" {
|
|
capabilities = [ "update" ]
|
|
}
|
|
|
|
path "auth/token/lookup-self" {
|
|
capabilities = [ "read" ]
|
|
}
|
|
```
|
|
|
|
</CodeBlockConfig>
|
|
|
|
#### Additional Vault ACL policies for sensitive operations
|
|
|
|
Additional Vault permissions are required while you perform the
|
|
following CA provider configuration changes:
|
|
- Changing the provider from Vault to a different provider, such as Consul's built-in provider
|
|
- Changing the `RootPKIPath`
|
|
|
|
Those configuration modifications trigger a root CA change that requires an
|
|
extremely privileged root cross-sign operation.
|
|
For that operation to succeed, the CA provider's [Vault token](#token) or
|
|
[auth method](#authmethod) must contain the following rule:
|
|
|
|
<CodeBlockConfig filename="temporary-sensitive-operation-pki-policy.hcl">
|
|
|
|
```hcl
|
|
path "<root_pki_path>/root/sign-self-issued" {
|
|
capabilities = [ "sudo", "update" ]
|
|
}
|
|
```
|
|
</CodeBlockConfig>
|
|
|
|
We recommend using the following process when performing such a CA provider
|
|
configuration change to minimize the time that a privileged Vault token is in use:
|
|
1. Create a new Vault token that includes both the `root/sign-self-issued`
|
|
permission and the standard permissions for the current Consul or Vault
|
|
managed PKI paths.
|
|
1. Modify the CA provider configuration to use that new Vault token.
|
|
1. Perform the CA provider configuration change that triggers the extremely privileged
|
|
root cross-sign operation. If the configuration change maintains Vault
|
|
as the provider but modifies `RootPKIPath`, the configuration change must
|
|
include a Vault token or auth method with standard permissions for the new
|
|
Consul or Vault managed PKI paths.
|