diff --git a/website/content/docs/platform/k8s/vso/sources/vault/index.mdx b/website/content/docs/platform/k8s/vso/sources/vault/index.mdx
index 9957123d2653..aefd6ecca36a 100644
--- a/website/content/docs/platform/k8s/vso/sources/vault/index.mdx
+++ b/website/content/docs/platform/k8s/vso/sources/vault/index.mdx
@@ -29,6 +29,8 @@ Vault Secrets Operator supports the following Vault features:
during drift remediation.
- Cross Vault namespace authentication for Vault Enterprise 1.13+.
- [Encrypted Vault client cache storage](/vault/docs/platform/k8s/vso/sources/vault#vault-client-cache) for improved performance and security.
+- [Instant updates](/vault/docs/platform/k8s/vso/sources/vault#instant-updates)
+ for VaultStaticSecret's with Vault Enterprise 1.16.3+.
### Supported Vault authentication methods
@@ -305,6 +307,30 @@ The Vault Secrets Operator can optionally cache Vault client information such as
The [Encrypted client cache](/vault/docs/platform/k8s/vso/sources/vault/client-cache) guide will walk you through the steps to enable and configure client cache encryption.
+## Instant updates
+
+The Vault Secrets Operator can instantly update Kubernetes Secrets when changes
+are made in Vault, by subscribing to [Vault Events][vault-events] for change
+notification. Setting a refresh interval (e.g. [refreshAfter][vss-spec]) is
+still recommended since event message delivery is not guaranteed.
+
+**Supported secret types:**
+- [VaultStaticSecret](#vaultstaticsecret-custom-resource) ([kv-v1](/vault/docs/secrets/kv/kv-v2),
+ [kv-v2](/vault/docs/secrets/kv/kv-v1))
+
+
+
+The instant updates option requires [Vault Enterprise](/vault/docs/enterprise)
+1.16.3+ due to the use of [Vault Event Notifications][vault-events].
+
+
+
+The [Instant updates](/vault/docs/platform/k8s/vso/sources/vault/instant-updates) guide
+will walk you through the steps to enable instant updates for a VaultStaticSecret.
+
+[vss-spec]: /vault/docs/platform/k8s/vso/api-reference#vaultstaticsecretspec
+[vault-events]: /vault/docs/concepts/events
+
## Tutorial
Refer to the [Vault Secrets Operator on
diff --git a/website/content/docs/platform/k8s/vso/sources/vault/instant-updates.mdx b/website/content/docs/platform/k8s/vso/sources/vault/instant-updates.mdx
new file mode 100644
index 000000000000..a6f739988e6c
--- /dev/null
+++ b/website/content/docs/platform/k8s/vso/sources/vault/instant-updates.mdx
@@ -0,0 +1,102 @@
+---
+layout: docs
+page_title: Instant updates with Vault Secrets Operator
+description: >-
+ Enable instant updates with Vault Secrets Operator.
+---
+
+# Instant updates for a VaultStaticSecret
+
+Vault Secrets Operator (VSO) supports instant updates for
+[VaultStaticSecrets][vss-spec] by subscribing to event notifications from Vault.
+
+## Before you start
+
+- **You must have [Vault Secrets Operator](/vault/docs/platform/k8s/vso/sources/vault) installed**.
+- **You must use [Vault Enterprise](/vault/docs/enterprise) version 1.16.3 or later**.
+
+## Step 1: Set event permissions
+
+Grant these permissions in the policy associated with the VaultAuth role:
+
+ ```hcl
+ path "/" {
+ capabilities = ["read", "list", "subscribe"]
+ subscribe_event_types = ["*"]
+ }
+
+ path "sys/events/subscribe/kv*" {
+ capabilities = ["read"]
+ }
+ ```
+
+
+
+See [Event Notifications Policies][events-policies] for more information on
+Vault event notification permissions.
+
+
+
+## Step 2: Enable instant updates on the VaultStaticSecret
+
+Set `syncConfig.instantUpdates=true` in the [VaultStaticSecret spec][vss-spec]:
+
+```yaml
+---
+apiVersion: secrets.hashicorp.com/v1beta1
+kind: VaultStaticSecret
+metadata:
+ namespace: vso-example
+ name: vault-static-secret-v2
+spec:
+ vaultAuthRef: vault-auth
+ mount:
+ type: kv-v2
+ path:
+ version: 2
+ refreshAfter: 1h
+ destination:
+ create: true
+ name: static-secret2
+ syncConfig:
+ instantUpdates: true
+```
+
+## Debugging
+
+Check Kubernetes events on the VaultStaticSecret resource to see if VSO
+subscribed to Vault event notifications.
+
+### Example: VSO is subscribed to Vault event notifications for the secret
+
+```shell-session
+$ kubectl describe vaultstaticsecret vault-static-secret-v2 -n vso-example
+...
+Events:
+ Type Reason Age From Message
+ ---- ------ ---- ---- -------
+ Normal SecretSynced 2s VaultStaticSecret Secret synced
+ Normal EventWatcherStarted 2s (x2 over 2s) VaultStaticSecret Started watching events
+ Normal SecretRotated 2s VaultStaticSecret Secret synced
+```
+
+### Example: The VaultAuth role policy lacks the required event permissions
+
+```shell-session
+$ kubectl describe vaultstaticsecret vault-static-secret-v2 -n vso-example
+...
+Events:
+ Type Reason Age From Message
+ ---- ------ ---- ---- -------
+ Normal SecretSynced 2s VaultStaticSecret Secret synced
+ Warning EventWatcherError 2s VaultStaticSecret Error while watching events:
+ failed to connect to vault websocket: error returned when opening event stream
+ web socket to wss://vault.vault.svc.cluster.local:8200/v1/sys/events/subscribe/kv%2A?json=true,
+ ensure VaultAuth role has correct permissions and Vault is Enterprise version
+ 1.16 or above: {"errors":["1 error occurred:\n\t* permission denied\n\n"]}
+ Normal SecretRotated 2s VaultStaticSecret Secret synced
+```
+
+[vss-spec]: /vault/docs/platform/k8s/vso/api-reference#vaultstaticsecretspec
+[vault-events]: /vault/docs/concepts/events
+[events-policies]: /vault/docs/concepts/events#policies
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index bb98a5efe16f..df7a2643363d 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -2235,6 +2235,10 @@
{
"title": "Encrypted client cache",
"path": "platform/k8s/vso/sources/vault/client-cache"
+ },
+ {
+ "title": "Instant updates",
+ "path": "platform/k8s/vso/sources/vault/instant-updates"
}
]
},