docs/vso: instant updates (#27668)

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 <EnterpriseAlert inline="true" />
+
+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))
+
+<Note title="Requires Vault Enterprise 1.16.3+">
+
+The instant updates option requires [Vault Enterprise](/vault/docs/enterprise)
+1.16.3+ due to the use of [Vault Event Notifications][vault-events].
+
+</Note>
+
+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

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 "<kv mount>/<kv secret path>" {
+    capabilities = ["read", "list", "subscribe"]
+    subscribe_event_types = ["*"]
+  }
+
+  path "sys/events/subscribe/kv*" {
+    capabilities = ["read"]
+  }
+  ```
+
+<Tip>
+
+See [Event Notifications Policies][events-policies] for more information on
+Vault event notification permissions.
+
+</Tip>
+
+## 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: <kv mount>
+  type: kv-v2
+  path: <kv secret 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

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"
                       }
                     ]
                   },