From 4cb319a8606957d9898a38d33cd5635b97e2b142 Mon Sep 17 00:00:00 2001 From: Theron Voran Date: Mon, 22 Jul 2024 08:01:52 -0700 Subject: [PATCH] docs/vso: instant updates (#27668) --- .../platform/k8s/vso/sources/vault/index.mdx | 26 +++++ .../k8s/vso/sources/vault/instant-updates.mdx | 102 ++++++++++++++++++ website/data/docs-nav-data.json | 4 + 3 files changed, 132 insertions(+) create mode 100644 website/content/docs/platform/k8s/vso/sources/vault/instant-updates.mdx 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" } ] },