diff --git a/website/content/docs/concepts/events.mdx b/website/content/docs/concepts/events.mdx new file mode 100644 index 000000000000..50be813ea29c --- /dev/null +++ b/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 + + + +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) | \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index a441bf8ac976..a293cfb36926 100644 --- a/website/data/docs-nav-data.json +++ b/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" + } + } ] }, {