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>
This commit is contained in:
Christopher Swenson
GitHub
parent
2cc6117f28
commit
724ccd5bc4
|
|
@ -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) |
|
||||
|
|
@ -198,6 +198,15 @@
|
|||
{
|
||||
"title": "User Lockout",
|
||||
"path": "concepts/user-lockout"
|
||||
},
|
||||
{
|
||||
"title": "Events",
|
||||
"path": "concepts/events",
|
||||
"badge": {
|
||||
"text": "ALPHA",
|
||||
"type": "outlined",
|
||||
"color": "neutral"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in New Issue