From 78133f588ca48f85b78c3b77080e2ffd76e91bff Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Mon, 8 Sep 2025 14:01:06 -0400 Subject: [PATCH 1/8] VAULT-37037 docs for Vault proxy update --- .../content/docs/internals/telemetry/metrics/all.mdx | 2 +- .../agent-and-proxy/proxy/caching/static-secret-caching.mdx | 6 +++++- .../content/docs/internals/telemetry/metrics/all.mdx | 2 ++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/content/vault/v1.20.x/content/docs/internals/telemetry/metrics/all.mdx b/content/vault/v1.20.x/content/docs/internals/telemetry/metrics/all.mdx index 500f34b20c..2dc6a84fe4 100644 --- a/content/vault/v1.20.x/content/docs/internals/telemetry/metrics/all.mdx +++ b/content/vault/v1.20.x/content/docs/internals/telemetry/metrics/all.mdx @@ -186,7 +186,7 @@ alphabetic order by name. @include 'telemetry-metrics/vault/core/handle_request.mdx' -@include 'telemetry-metrics/vault/core/in_flight_requests.mdx' +@include 'telemetry-metrics/vault/core/response_status_code.mdx' @include 'telemetry-metrics/vault/core/leadership_lost.mdx' diff --git a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx index 61be100b10..0c181ab032 100644 --- a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx @@ -18,7 +18,11 @@ feature for cache freshness. As a result, static secret caching can only be used with Vault Enterprise installations. When using a Vault cluster with performance standbys, Proxy may receive secret update events -before the secret update has been fully replicated. To make sure that Proxy can get updated +before the secret update has been fully replicated. When using Vault Proxy 1.21+ and Vault Server +1.20+, Vault Proxy will handle this automatically, and will use client-controlled consistency +to retry, if required, on secondary nodes that don't yet have the corresponding secret update. + +On any set of versions lower than those, to make sure that Proxy can get updated secret values after receiving an event notification, Proxy must be configured to point to the address of the active node in its [Vault stanza](/vault/docs/agent-and-proxy/proxy#vault-stanza), or [allow_forwarding_via_header must be set to true](/vault/docs/configuration/replication#allow_forwarding_via_header) diff --git a/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx b/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx index acac06d10c..4db23caf5d 100644 --- a/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx @@ -188,6 +188,8 @@ alphabetic order by name. @include 'telemetry-metrics/vault/core/in_flight_requests.mdx' +include 'telemetry-metrics/vault/core/response_status_code.mdx' + @include 'telemetry-metrics/vault/core/leadership_lost.mdx' @include 'telemetry-metrics/vault/core/leadership_setup_failed.mdx' From 3dffdff54510968a3069224d8740f1b62c2e9e4a Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Mon, 8 Sep 2025 14:02:00 -0400 Subject: [PATCH 2/8] whoops --- .../v1.20.x/content/docs/internals/telemetry/metrics/all.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/vault/v1.20.x/content/docs/internals/telemetry/metrics/all.mdx b/content/vault/v1.20.x/content/docs/internals/telemetry/metrics/all.mdx index 2dc6a84fe4..f58684c623 100644 --- a/content/vault/v1.20.x/content/docs/internals/telemetry/metrics/all.mdx +++ b/content/vault/v1.20.x/content/docs/internals/telemetry/metrics/all.mdx @@ -186,6 +186,8 @@ alphabetic order by name. @include 'telemetry-metrics/vault/core/handle_request.mdx' +@include 'telemetry-metrics/vault/core/in_flight_requests.mdx' + @include 'telemetry-metrics/vault/core/response_status_code.mdx' @include 'telemetry-metrics/vault/core/leadership_lost.mdx' From 5ce61cb5ff45e2142c203efca242c0bb4401536a Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Mon, 8 Sep 2025 14:05:10 -0400 Subject: [PATCH 3/8] whoops --- .../content/docs/internals/telemetry/metrics/all.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx b/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx index 4db23caf5d..fa00634e3d 100644 --- a/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/internals/telemetry/metrics/all.mdx @@ -188,7 +188,7 @@ alphabetic order by name. @include 'telemetry-metrics/vault/core/in_flight_requests.mdx' -include 'telemetry-metrics/vault/core/response_status_code.mdx' +@include 'telemetry-metrics/vault/core/response_status_code.mdx' @include 'telemetry-metrics/vault/core/leadership_lost.mdx' From 1fef984c747ac6ade5c659a83b715c76d8568739 Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Mon, 8 Sep 2025 15:27:16 -0400 Subject: [PATCH 4/8] feedback --- .../proxy/caching/static-secret-caching.mdx | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx index 0c181ab032..8c1a65a755 100644 --- a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx @@ -18,14 +18,18 @@ feature for cache freshness. As a result, static secret caching can only be used with Vault Enterprise installations. When using a Vault cluster with performance standbys, Proxy may receive secret update events -before the secret update has been fully replicated. When using Vault Proxy 1.21+ and Vault Server -1.20+, Vault Proxy will handle this automatically, and will use client-controlled consistency -to retry, if required, on secondary nodes that don't yet have the corresponding secret update. - -On any set of versions lower than those, to make sure that Proxy can get updated -secret values after receiving an event notification, Proxy must be configured to point to the -address of the active node in its [Vault stanza](/vault/docs/agent-and-proxy/proxy#vault-stanza), -or [allow_forwarding_via_header must be set to true](/vault/docs/configuration/replication#allow_forwarding_via_header) +before the secret update is fully replicated. + +When using Vault Proxy 1.21+ and Vault Server 1.20+, Vault Proxy handles the +incomplete replication automatically with client-controlled consistency. If +needed, Vault Proxy retries the read on any secondary node until the +corresponding secret update's storage index is present on the node. + +If you use Vault Proxy 1.20 or earlier and/or Vault 1.19 or earlier, to make +sure that Proxy can get updated secret values after receiving an event notification, +Proxy must be configured to point to the address of the active node in its +[Vault stanza](/vault/docs/agent-and-proxy/proxy#vault-stanza), or +[allow_forwarding_via_header must be set to true](/vault/docs/configuration/replication#allow_forwarding_via_header) on the cluster. When `allow_forwarding_via_header` is configured, Proxy will only forward requests to update a secret in its cache after receiving an event indicating that secret got updated. This approach would be recommended if access to Vault was behind, for example, a load balancer. From bb3565c08d7b17e37f82e7c9a8971a827239c966 Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Mon, 8 Sep 2025 15:43:27 -0400 Subject: [PATCH 5/8] feedback --- .../agent-and-proxy/proxy/caching/static-secret-caching.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx index 8c1a65a755..41e220107d 100644 --- a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx @@ -23,7 +23,7 @@ before the secret update is fully replicated. When using Vault Proxy 1.21+ and Vault Server 1.20+, Vault Proxy handles the incomplete replication automatically with client-controlled consistency. If needed, Vault Proxy retries the read on any secondary node until the -corresponding secret update's storage index is present on the node. +storage index for the corresponding secret update is present on the node. If you use Vault Proxy 1.20 or earlier and/or Vault 1.19 or earlier, to make sure that Proxy can get updated secret values after receiving an event notification, From c2ebf60914e1c08bfec42a4bd78c5ca72e780ee3 Mon Sep 17 00:00:00 2001 From: Sarah Chavis <62406755+schavis@users.noreply.github.com> Date: Mon, 8 Sep 2025 12:44:21 -0700 Subject: [PATCH 6/8] Update content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx --- .../agent-and-proxy/proxy/caching/static-secret-caching.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx index 41e220107d..ad70328082 100644 --- a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx @@ -29,7 +29,7 @@ If you use Vault Proxy 1.20 or earlier and/or Vault 1.19 or earlier, to make sure that Proxy can get updated secret values after receiving an event notification, Proxy must be configured to point to the address of the active node in its [Vault stanza](/vault/docs/agent-and-proxy/proxy#vault-stanza), or -[allow_forwarding_via_header must be set to true](/vault/docs/configuration/replication#allow_forwarding_via_header) +[`allow_forwarding_via_header`(/vault/docs/configuration/replication#allow_forwarding_via_header) must be set to `true`. on the cluster. When `allow_forwarding_via_header` is configured, Proxy will only forward requests to update a secret in its cache after receiving an event indicating that secret got updated. This approach would be recommended if access to Vault was behind, for example, a load balancer. From fc45be82ded6cd44a03d41def5493240419a487f Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Mon, 8 Sep 2025 15:46:26 -0400 Subject: [PATCH 7/8] feedback --- .../proxy/caching/static-secret-caching.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx index ad70328082..ca65790690 100644 --- a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx @@ -29,10 +29,11 @@ If you use Vault Proxy 1.20 or earlier and/or Vault 1.19 or earlier, to make sure that Proxy can get updated secret values after receiving an event notification, Proxy must be configured to point to the address of the active node in its [Vault stanza](/vault/docs/agent-and-proxy/proxy#vault-stanza), or -[`allow_forwarding_via_header`(/vault/docs/configuration/replication#allow_forwarding_via_header) must be set to `true`. -on the cluster. When `allow_forwarding_via_header` is configured, Proxy will only forward -requests to update a secret in its cache after receiving an event indicating that secret got updated. -This approach would be recommended if access to Vault was behind, for example, a load balancer. +[allow_forwarding_via_header](/vault/docs/configuration/replication#allow_forwarding_via_header) +must be set to `true` on the cluster. When `allow_forwarding_via_header` is configured, +Proxy will only forward requests to update a secret in its cache after receiving an +event indicating that secret got updated. This approach would be recommended if access +to Vault was behind, for example, a load balancer. ## Step 1: Subscribe Vault Proxy to KV events From a69b52821c3d80e677a9c4a97102e4744a5a1e69 Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Mon, 8 Sep 2025 15:47:45 -0400 Subject: [PATCH 8/8] backticks --- .../agent-and-proxy/proxy/caching/static-secret-caching.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx index ca65790690..cf704dec60 100644 --- a/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx +++ b/content/vault/v1.21.x (rc)/content/docs/agent-and-proxy/proxy/caching/static-secret-caching.mdx @@ -29,7 +29,7 @@ If you use Vault Proxy 1.20 or earlier and/or Vault 1.19 or earlier, to make sure that Proxy can get updated secret values after receiving an event notification, Proxy must be configured to point to the address of the active node in its [Vault stanza](/vault/docs/agent-and-proxy/proxy#vault-stanza), or -[allow_forwarding_via_header](/vault/docs/configuration/replication#allow_forwarding_via_header) +[`allow_forwarding_via_header`](/vault/docs/configuration/replication#allow_forwarding_via_header) must be set to `true` on the cluster. When `allow_forwarding_via_header` is configured, Proxy will only forward requests to update a secret in its cache after receiving an event indicating that secret got updated. This approach would be recommended if access