diff --git a/website/content/api-docs/connect/ca.mdx b/website/content/api-docs/connect/ca.mdx index 3d3e456c18..2229b1566c 100644 --- a/website/content/api-docs/connect/ca.mdx +++ b/website/content/api-docs/connect/ca.mdx @@ -169,6 +169,13 @@ The table below shows this endpoint's support for The corresponding CLI command is [`consul connect ca set-config`](/commands/connect/ca#set-config). +~> **If currently using Vault CA provider:** + If you intend to change the CA provider from Vault to another, + or to change the Vault provider's [`RootPKIPath`](/docs/connect/ca/vault#rootpkipath), + you must temporarily elevate the privileges of the Vault token + or auth method in use as described in the + [Vault CA provider documentation](/docs/connect/ca/vault#additional-vault-acl-policies-for-sensitive-operations). + ### JSON Request Body Schema - `Provider` `(string: )` - Specifies the CA provider type to use. @@ -177,11 +184,14 @@ The corresponding CLI command is [`consul connect ca set-config`](/commands/conn for the chosen provider. For more information on configuring the Connect CA providers, see [Provider Config](/docs/connect/ca). -- `ForceWithoutCrossSigning` `(bool: )` - Indicates that the CA change - should be forced to complete even if the current CA doesn't support cross - signing. Changing root without cross-signing may cause temporary connection - failures until the rollout completes. See [Forced Rotation Without - Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing) +- `ForceWithoutCrossSigning` `(bool: false)` - Indicates that the CA change + should be forced to complete even if the current CA doesn't support root cross-signing. + + ~> **Caution:** Setting this field to `true` will cause temporary connection failures + until service mesh proxies and/or Consul client agents receive a new certificate + that establishes trust with the new root. + Do not use this field unless you are sure you need it. + Refer to [Forced Rotation Without Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing) for more detail. ### Sample Payload diff --git a/website/content/commands/connect/ca.mdx b/website/content/commands/connect/ca.mdx index e571258f5a..587d4379c5 100644 --- a/website/content/commands/connect/ca.mdx +++ b/website/content/commands/connect/ca.mdx @@ -97,6 +97,13 @@ Configuration updated! The return code will indicate success or failure. +~> **If currently using Vault CA provider:** + If you intend to change the CA provider from Vault to another, + or to change the Vault provider's [`RootPKIPath`](/docs/connect/ca/vault#rootpkipath), + you must temporarily elevate the privileges of the Vault token + or auth method in use as described in the + [Vault CA provider documentation](/docs/connect/ca/vault#additional-vault-acl-policies-for-sensitive-operations). + #### Command Options - `-config-file` - (required) Specifies a JSON-formatted file to use for the new configuration. @@ -104,10 +111,13 @@ The return code will indicate success or failure. [Update CA Configuration API](/api-docs/connect/ca#update-ca-configuration). - `-force-without-cross-signing` `(bool: )` - Indicates that the CA change - should be forced to complete even if the current CA doesn't support cross - signing. Changing root without cross-signing may cause temporary connection - failures until the rollout completes. See [Forced Rotation Without - Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing) + should be forced to complete even if the current CA doesn't support root cross-signing. + + ~> **Caution:** Use of this flag will cause temporary connection failures + until service mesh proxies and/or Consul client agents receive a new certificate + that establishes trust with the new root. + Do not use this flag unless you are sure you need it. + Refer to [Forced Rotation Without Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing) for more detail. #### API Options diff --git a/website/content/docs/connect/ca/vault.mdx b/website/content/docs/connect/ca/vault.mdx index 1fe8a23362..2a37462241 100644 --- a/website/content/docs/connect/ca/vault.mdx +++ b/website/content/docs/connect/ca/vault.mdx @@ -7,40 +7,30 @@ description: >- # Vault as a Service Mesh Certificate Authority -Consul can be used with [Vault](https://www.vaultproject.io/) to -manage and sign certificates. -The Vault CA provider uses the -[Vault PKI secrets engine](https://www.vaultproject.io/docs/secrets/pki) -to generate and sign certificates. +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: +- Refer to [Service Mesh Certificate Authority Overview](/docs/connect/ca) for important background information about how Consul manages certificates with configurable CA providers. -- **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. +- Vault 0.10.3 to 1.10.x. -~> **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. +~> **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. -## Configuration +## Enable Vault as the CA -The Vault CA is enabled by setting the CA provider to `"vault"` and -setting the required configuration values. +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. -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. - -Example configurations are shown below: +The following example shows the required configurations for a default implementation: @@ -53,9 +43,9 @@ connect { ca_provider = "vault" ca_config { address = "http://localhost:8200" - token = "..." + token = "" root_pki_path = "connect-root" - intermediate_pki_path = "connect-intermediate" + intermediate_pki_path = "connect-dc1-intermediate" } } ``` @@ -69,9 +59,9 @@ connect { "Provider": "vault", "Config": { "Address": "http://localhost:8200", - "Token": "", + "Token": "", "RootPKIPath": "connect-root", - "IntermediatePKIPath": "connect-intermediate" + "IntermediatePKIPath": "connect-dc1-intermediate" } } ``` @@ -80,11 +70,12 @@ connect { -The configuration options are listed below. +## Configuration Reference --> **NOTE**: The first key is the value used in API calls, and the second key - (after the `/`) is used if you are adding the configuration to the agent's - configuration file. +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: `) - The address of the Vault server. @@ -115,7 +106,6 @@ The configuration options are listed below. default mount path `/var/run/secrets/kubernetes.io/serviceaccount/token` if the `jwt` parameter is not provided. - - `RootPKIPath` / `root_pki_path` (`string: `) - The path to a PKI secrets engine for the root certificate. @@ -130,7 +120,7 @@ The configuration options are listed below. When WAN Federation is enabled, each secondary datacenter must use the same Vault cluster and share the same `root_pki_path` with the primary datacenter. - To use an intermediate certificate as the primary CA in Consul initialize the + 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 @@ -181,124 +171,199 @@ The configuration options are listed below. @include 'http_api_connect_ca_common_options.mdx' -## Root and Intermediate PKI Paths +### Root and Intermediate PKI Paths The Vault CA provider uses two separately configured [PKI secrets engines](https://www.vaultproject.io/docs/secrets/pki) -for managing Connect certificates. +for managing Consul service mesh 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 `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 is used to sign all leaf -certificates and Consul may periodically generate new intermediates for +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. -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. +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. -## Vault ACL Policies +### Configure Vault ACL policies ((#vault-acl-policies)) -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. - +#### 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: + + + + ```hcl + path "/sys/mounts/" { + capabilities = [ "read" ] + } + + path "/sys/mounts/" { + capabilities = [ "read" ] + } + + path "/sys/mounts//tune" { + capabilities = [ "update" ] + } + ``` + + + +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: + + + + ```hcl + path "//" { + capabilities = [ "read" ] + } + + path "//root/sign-intermediate" { + capabilities = [ "update" ] + } + + path "//*" { + capabilities = [ "create", "read", "update", "delete", "list" ] + } + ``` + + +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). + + + + ```hcl + path "auth/token/renew-self" { + capabilities = [ "update" ] + } + + path "auth/token/lookup-self" { + capabilities = [ "read" ] + } + ``` + + + +#### 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: + + + + ```hcl + path "/sys/mounts/" { + capabilities = [ "create", "read", "update", "delete", "list" ] + } + + path "/sys/mounts/" { + capabilities = [ "create", "read", "update", "delete", "list" ] + } + + path "/sys/mounts//tune" { + capabilities = [ "update" ] + } + ``` + + +1. Allow Consul full use of both PKI engines: + + + + ```hcl + path "//*" { + capabilities = [ "create", "read", "update", "delete", "list" ] + } + + path "//*" { + capabilities = [ "create", "read", "update", "delete", "list" ] + } + ``` + + + +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). + + + + ```hcl + path "auth/token/renew-self" { + capabilities = [ "update" ] + } + + path "auth/token/lookup-self" { + capabilities = [ "read" ] + } + ``` + + + +#### 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: + + ```hcl -# Existing PKI Mounts -path "/sys/mounts" { - capabilities = [ "read" ] -} - -path "/sys/mounts/connect_root" { - capabilities = [ "read" ] -} - -path "/sys/mounts/connect_inter" { - capabilities = [ "read" ] -} - -# Needed for Consul 1.11+ -path "/sys/mounts/connect_inter/tune" { - capabilities = [ "update" ] -} - -path "/connect_root/" { - capabilities = [ "read" ] -} - -path "/connect_root/root/sign-intermediate" { - capabilities = [ "update" ] -} - -path "/connect_inter/*" { - capabilities = [ "create", "read", "update", "delete", "list" ] -} - -path "auth/token/renew-self" { - capabilities = [ "update" ] -} - -path "auth/token/lookup-self" { - capabilities = [ "read" ] +path "/root/sign-self-issued" { + capabilities = [ "sudo", "update" ] } ``` - -### Consul Managed PKI Paths - -The following Vault policy allows Consul to create and manage the PKI paths in Vault. -Consul is granted the ability to create the PKI mount points and given full -control of the Root and Intermediate or Leaf CA for Connect clients. - -In this example the `RootPKIPath` is `connect_root` and the `IntermediatePKIPath` -is `connect_inter`. These values should be updated for your environment. - - - -```hcl -# Consul Managed PKI Mounts -path "/sys/mounts" { - capabilities = [ "read" ] -} - -path "/sys/mounts/connect_root" { - capabilities = [ "create", "read", "update", "delete", "list" ] -} - -path "/sys/mounts/connect_inter" { - capabilities = [ "create", "read", "update", "delete", "list" ] -} - -# Needed for Consul 1.11+ -path "/sys/mounts/connect_inter/tune" { - capabilities = [ "update" ] -} - -path "/connect_root/*" { - capabilities = [ "create", "read", "update", "delete", "list" ] -} - -path "/connect_inter/*" { - capabilities = [ "create", "read", "update", "delete", "list" ] -} -``` - - - - -[`ca_config`]: /docs/agent/config/config-files#connect_ca_config -[`ca_provider`]: /docs/agent/config/config-files#connect_ca_provider -[`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration +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.