docs: vault ca provider patch upgrade guidance

CHANGELOG.md

@@ -6,6 +6,10 @@ BUG FIXES:
 
 ## 1.13.2 (September 20, 2022)
 
+BREAKING CHANGES:
+
+* ca: If using Vault as the service mesh CA provider, the Vault policy used by Consul now requires the `update` capability on the intermediate PKI's tune mount configuration endpoint, such as `/sys/mounts/connect_inter/tune`. The breaking nature of this change will be resolved in an upcoming 1.13 patch release. Refer to [upgrade guidance](https://www.consul.io/docs/upgrading/upgrade-specific#modify-vault-policy-for-vault-ca-provider) for more information.
+
 SECURITY:
 
 * auto-config: Added input validation for auto-config JWT authorization checks. Prior to this change, it was possible for malicious actors to construct requests which incorrectly pass custom JWT claim validation for the `AutoConfig.InitialConfiguration` endpoint. Now, only a subset of characters are allowed for the input before evaluating the bexpr. [[GH-14577](https://github.com/hashicorp/consul/issues/14577)]
@@ -48,6 +52,10 @@ BUG FIXES:
 
 ## 1.12.5 (September 20, 2022)
 
+BREAKING CHANGES:
+
+* ca: If using Vault as the service mesh CA provider, the Vault policy used by Consul now requires the `update` capability on the intermediate PKI's tune mount configuration endpoint, such as `/sys/mounts/connect_inter/tune`. The breaking nature of this change will be resolved in an upcoming 1.12 patch release. Refer to [upgrade guidance](https://www.consul.io/docs/upgrading/upgrade-specific#modify-vault-policy-for-vault-ca-provider) for more information.
+
 SECURITY:
 
 * auto-config: Added input validation for auto-config JWT authorization checks. Prior to this change, it was possible for malicious actors to construct requests which incorrectly pass custom JWT claim validation for the `AutoConfig.InitialConfiguration` endpoint. Now, only a subset of characters are allowed for the input before evaluating the bexpr. [[GH-14577](https://github.com/hashicorp/consul/issues/14577)]
@@ -72,6 +80,10 @@ BUG FIXES:
 
 ## 1.11.9 (September 20, 2022)
 
+BREAKING CHANGES:
+
+* ca: If using Vault as the service mesh CA provider, the Vault policy used by Consul now requires the `update` capability on the intermediate PKI's tune mount configuration endpoint, such as `/sys/mounts/connect_inter/tune`. The breaking nature of this change will be resolved in an upcoming 1.11 patch release. Refer to [upgrade guidance](https://www.consul.io/docs/upgrading/upgrade-specific#modify-vault-policy-for-vault-ca-provider) for more information.
+
 SECURITY:
 
 * auto-config: Added input validation for auto-config JWT authorization checks. Prior to this change, it was possible for malicious actors to construct requests which incorrectly pass custom JWT claim validation for the `AutoConfig.InitialConfiguration` endpoint. Now, only a subset of characters are allowed for the input before evaluating the bexpr. [[GH-14577](https://github.com/hashicorp/consul/issues/14577)]

website/content/docs/connect/ca/vault.mdx

@@ -227,6 +227,11 @@ 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" ]
 }
@@ -275,6 +280,11 @@ 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" ]
 }

website/content/docs/upgrading/upgrade-specific.mdx

@@ -45,6 +45,7 @@ review the following guidances relevant to your deployment:
 - [All service mesh deployments](#all-service-mesh-deployments)
 - [Service mesh deployments using auto-encrypt or auto-config](#service-mesh-deployments-using-auto-encrypt-or-auto-config)
 - [Service mesh deployments without the HTTPS port enabled on Consul agents](#service-mesh-deployments-without-the-https-port-enabled-on-consul-agents)
+- [All service mesh deployments using the Vault CA provider](#modify-vault-policy-for-vault-ca-provider)
 
 #### All service mesh deployments
 
@@ -170,6 +171,38 @@ such as with flags or environment variables like
 [`-ca-file`](/commands/connect/envoy#ca-file) and
 [`CONSUL_CACERT`](/commands#consul_cacert).
 
+#### Modify Vault policy for Vault CA provider
+
+If using the Vault CA provider,
+you must modify the Vault policy used by Consul to interact with Vault
+so that certificates required for service mesh operation can still be generated.
+The policy must include the `update` capability on the intermediate PKI's tune mount configuration endpoint
+at path `/sys/mounts/<intermediate_pki_mount_name>/tune`.
+Refer to the [Vault CA provider documentation](/docs/connect/ca/vault#vault-acl-policies)
+for updated example Vault policies for use with Vault-managed or Consul-managed PKI paths.
+
+You are using the Vault CA provider if either of the following configurations exists:
+- The Consul server agent configuration option [`connect.ca_provider`](/docs/agent/config/config-files#connect_ca_provider) is set to `vault`, or
+- The Consul on Kubernetes Helm Chart [`global.secretsBackend.vault.connectCA`](/docs/k8s/helm#v-global-secretsbackend-vault-connectca) value is configured.
+
+Though this guidance is listed in the 1.13.x section, it applies to all of the following release series:
+- Consul 1.13.x: applies to 1.13.2+
+- Consul 1.12.x: applies to 1.12.5+
+- Consul 1.11.x: applies to 1.11.9+
+
+Those affected Consul versions contain a
+[bugfix that allows the intermediate CA's TTL configuration to be modified](https://github.com/hashicorp/consul/pull/14516).
+The bugfix requires the `update` capability to tune that configuration.
+Without the `update` capability, those affected Consul versions
+cannot provide services with the certificates they need to participate in the mesh.
+In an upcoming patch for each of those release series,
+we will restore the intermediate CA's ability to provide certificates even without the `update` capability on the tune configuration endpoint,
+though the `update` capability will still be needed to modify the CA's TTL configuration.
+
+We recommend modifying the Vault policy before upgrading to Consul 1.11 or later
+to ensure your organization does not accidentally miss this guidance when performing subsequent upgrades,
+such as to the latest patch within a release series.
+
 ### 1.9 Telemetry Compatibility
 
 #### Removing configuration options
@@ -178,7 +211,17 @@ The [`disable_compat_19`](/docs/agent/options#telemetry-disable_compat_1.9) tele
 In prior Consul versions (1.10.x through 1.11.x), the config defaulted to `false`. In 1.12.x it defaulted to `true`.
 If you were using this flag, you must remove it before upgrading.
 
-## Consul 1.12.0
+### Modify Vault Policy for Vault CA Provider
+
+Follow the same guidance as provided in the
+[1.13 upgrade section for modifying the Vault policy if using the Vault CA provider](#modify-vault-policy-for-vault-ca-provider).
+
+## Consul 1.12.x ((#consul-1-12-0))
+
+### Modify Vault Policy for Vault CA Provider
+
+Follow the same guidance as provided in the
+[1.13 upgrade section for modifying the Vault policy if using the Vault CA provider](#modify-vault-policy-for-vault-ca-provider).
 
 ### 1.9 Telemetry Compatibility
 
@@ -216,7 +259,7 @@ be replaced with the new [`tls` stanza](/docs/agent/config/config-files#tls-conf
 - `verify_outgoing`
 - `verify_server_hostname`
 
-## Consul 1.11.0
+## Consul 1.11.x ((#consul-1-11-0))
 
 ### 1.10 Compatibility <EnterpriseAlert inline />
 Consul Enterprise versions 1.10.0 through 1.10.4 contain a latent bug that
@@ -291,6 +334,11 @@ When upgrading to Consul 1.10, you must ensure that the Envoy sidecars are
 restarted and bootstrapped using a version of the Consul CLI >= 1.10. This
 ensures your sidecars are supported by Consul 1.11.
 
+### Modify Vault Policy for Vault CA Provider
+
+Follow the same guidance as provided in the
+[1.13 upgrade section for modifying the Vault policy if using the Vault CA provider](#modify-vault-policy-for-vault-ca-provider).
+
 ## Consul 1.10.0
 
 ### Licensing Changes <EnterpriseAlert inline />