docs: Add page about events (#19243)

This page details the new events experiment that will be
released in Vault 1.13.

Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com>

website/content/docs/concepts/events.mdx

@@ -0,0 +1,169 @@
+---
+layout: docs
+page_title: Events
+description: >-
+  Events are an experimental feature that allows Vault and plugins to exchange arbitrary activity data
+  within Vault and with external subscribers via WebSockets.
+---
+
+# Events
+
+~> **Important:** Events are experimental, and may have backwards incompatible changes introduced in subsequent versions of Vault, or be removed altogether.
+
+Events are arbitrary, **non-secret** data that can be exchanged between producers (Vault and plugins)
+and subscribers (Vault components and external users via the API).
+Events are delivered on a *best-effort* basis, so do not have delivery guarantees at this time.
+
+As of Vault 1.13, events are not considered production-ready, and so are disabled by default when starting a Vault server.
+Events can be enabled via the `events.alpha1` [experiment option](/vault/docs/configuration#experiments) in the Vault
+configuration or on the command-line:
+
+```shell-session
+$ vault server -experiment events.alpha1
+```
+
+-> Note: Experiments can only be enabled at startup, and cannot be disabled or enabled at runtime.
+
+## Event Types
+
+<!-- This information will probably be migrated to the plugin pages eventually -->
+
+Internal components of Vault as well as external plugins can generate events.
+These are published to "event types", sometimes called "topics" in some event systems.
+All events of a specific event type will have the same format for their
+additional `metadata` field.
+
+The following events are currently generated by Vault and its builtin plugins automatically:
+
+| Plugin | Event Type              | Vault version |
+| ------ | ----------------------- | ------------- |
+| kv     | `kv-v1/delete`          | 1.13          |
+| kv     | `kv-v1/write`           | 1.13          |
+| kv     | `kv-v2/config-write`    | 1.13          |
+| kv     | `kv-v2/data-delete`     | 1.13          |
+| kv     | `kv-v2/data-patch`      | 1.13          |
+| kv     | `kv-v2/data-write`      | 1.13          |
+| kv     | `kv-v2/delete`          | 1.13          |
+| kv     | `kv-v2/destroy`         | 1.13          |
+| kv     | `kv-v2/metadata-delete` | 1.13          |
+| kv     | `kv-v2/metadata-patch`  | 1.13          |
+| kv     | `kv-v2/metadata-read`   | 1.13          |
+| kv     | `kv-v2/metadata-write`  | 1.13          |
+| kv     | `kv-v2/undelete`        | 1.13          |
+
+
+## Event Format
+
+Events may be formatted in protobuf binary format or as JSON.
+See `EventReceived` in [`sdk/logical/event.proto`](https://github.com/hashicorp/vault/blob/main/sdk/logical/event.proto) in the relevant Vault version for the protobuf schema.
+
+When formatted as JSON, the event conforms to the [CloudEvents](https://cloudevents.io/) specification.
+
+- `id` `(string)` - CloudEvents unique identifier for the event. The `id` is unique for each event, and events with the same `id` represent the same event.
+
+- `source` `(string)` - CloudEvents source, which is currently `https://vaultproject.io`.
+
+- `specversion` `(string)` - The CloudEvents specification version this conforms to.
+
+- `type` `(string)` - CloudEvents type this event corresponds to, which is currently always `*`.
+
+- ` datacontenttype` `(string)` - CloudEvents content type of the event, which is currently always `application/json`.
+
+- `time` `(string)` - ISO 8601-formatted timestamp for when the event was generated.
+
+- ` data` `(object)` - Vault-specific data.
+
+  - `event` `(Event)` - contains the event that happened.
+
+    - `id` `(string)` - (repeat of the `id` parameter)
+
+    - `metadata` `(object)` - arbitrary extra data customized for the event type.
+
+  - `eventType` `(string)` - the event type that was published.
+
+  - `pluginInfo` `(PluginInfo)` - information about the plugin that generated the event, if applicable.
+
+    - `mountClass` `(string)` - the class of plugin, e.g., `secret`, `auth`.
+
+    - `mountAccessor` `(string)` - the unique ID of the mounted plugin.
+
+    - `mountPath` `(string)` - the path that the plugin is mounted at.
+
+    - `plugin` `(string)` - the name of the plugin, e.g., `kv`.
+
+Here is an example event in JSON format:
+
+```json
+{
+  "id": "901f2388-aabb-a385-7bc0-0b09d5fa060b",
+  "source": "https://vaultproject.io/",
+  "specversion": "1.0",
+  "type": "*",
+  "data": {
+    "event": {
+      "id": "901f2388-aabb-a385-7bc0-0b09d5fa060b",
+      "metadata": {
+        "current_version": "1",
+        "oldest_version": "0",
+        "path": "data/foo"
+      }
+    },
+    "event_type": "kv-v2/data-write",
+    "plugin_info": {
+      "mount_class": "secret",
+      "mount_accessor": "kv_a6081d01",
+      "mount_path": "secret/",
+      "plugin": "kv"
+    }
+  },
+  "datacontentype": "application/cloudevents",
+  "time": "2023-02-17T13:11:39.227341-08:00"
+}
+```
+
+## Subscribing to Events
+
+Vault has an API endpoint, `/v1/sys/events/subscribe/{eventType}`, that allows users to subscribe to events via a
+WebSocket stream.
+This endpoint supports the standard authentication and authorization workflows used by other Vault endpoints.
+The `{eventType}` parameter is a non-empty string of what event type to subscribe to, which may contain wildcards (`*`)
+to subscribe to multiple events, e.g., `kv-v2/data-*`.
+
+By default, the events are delivered in protobuf binary format.
+The endpoint can also format the data as JSON if the `json` query parameter is set to `true`:
+
+```shell-session
+$ wscat -H "X-Vault-Token: $(vault print token)" --connect 'ws://127.0.0.1:8200/v1/sys/events/subscribe/kv-v2/data-write?json=true
+{"id":"901f2388-aabb-a385-7bc0-0b09d5fa060b","source":"https://vaultproject.io/","specversion":"1.0","type":"*","data":{"event":{"id":"901f2388-aabb-a385-7bc0-0b09d5fa060b","metadata":{"current_version":"1","oldest_version":"0","path":"data/foo"}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_a6081d01","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2023-02-17T13:11:39.227341-08:00"}
+...
+```
+
+The Vault CLI support this endpoint via the `events subscribe` command, which will output a stream of
+JSON for the requested events (one line per event):
+
+```shell-session
+$ vault events subscribe kv-v2/data-write
+{"id":"901f2388-aabb-a385-7bc0-0b09d5fa060b","source":"https://vaultproject.io/","specversion":"1.0","type":"*","data":{"event":{"id":"901f2388-aabb-a385-7bc0-0b09d5fa060b","metadata":{"current_version":"1","oldest_version":"0","path":"data/foo"}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_a6081d01","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2023-02-17T13:11:39.227341-08:00"}
+...
+```
+
+## Policies
+
+To subscribe, the `read` capability must be granted by a [policy](/vault/docs/concepts/policies)
+on the `/v1/sys/events/subscribe/{eventType}` path, where `{eventType}` is the event type that will be
+subscribed to. The path may contain wildcards.
+
+An example blanket policy is:
+```hcl
+path "sys/events/subscribe/*" {
+    capabilities = ["read"]
+}
+```
+
+
+## Supported Versions
+
+| Vault Version | Support                                     |
+| ------------- | ------------------------------------------- |
+| <= 1.12       | Not supported                               |
+| 1.13          | Supported (with `events.alpha1` experiment) |

website/data/docs-nav-data.json

@@ -198,7 +198,16 @@
       {
         "title": "User Lockout",
         "path": "concepts/user-lockout"
-      }
+      },
+      {
+        "title": "Events",
+        "path": "concepts/events",
+        "badge": {
+          "text": "ALPHA",
+          "type": "outlined",
+          "color": "neutral"
+        }
+  }
     ]
   },
   {