mirrors/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2025-08-15 19:17:02 +02:00
Code Issues Projects Releases Wiki Activity
bc69ef899a
vault/website/content/docs/concepts/events.mdx
Christopher Swenson 500cf21d0d
events: Update docs for beta release (#23036) 
Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
2023-09-13 14:18:18 -07:00

199 lines
8.8 KiB
Plaintext
Raw Blame History

---
layout: docs
page_title: Events
description: >-
Events allow Vault and plugins to exchange arbitrary activity data
within Vault and with external subscribers via WebSockets.
---
# Events
<Important title="Beta functionality is stable but possibly incomplete">
Vault delivers events on a best-effort basis. We do not provide delivery
guarantees for beta functionality.
</Important>
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).
## 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 | Metadata | Vault version |
| ------ | ----------------------- | -------------------------------------------- | ------------- |
| kv | `kv-v1/delete` | `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v1/write` | `data_path`, `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/config-write` | `data_path`, `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/data-delete` | `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/data-patch` | `data_path`, `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/data-write` | `data_path`, `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/delete` | `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/destroy` | `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/metadata-delete` | `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/metadata-patch` | `data_path`, `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/metadata-read` | `data_path`, `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/metadata-write` | `data_path`, `modified`, `operation`, `path` | 1.13 |
| kv | `kv-v2/undelete` | `data_path`, `modified`, `operation`, `path` | 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.
- `event_type` `(string)` - the event type that was published.
- `plugin_info` `(PluginInfo)` - information about the plugin that generated the event, if applicable.
- `mount_class` `(string)` - the class of plugin, e.g., `secret`, `auth`.
- `mount_accessor` `(string)` - the unique ID of the mounted plugin.
- `mount_path` `(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": "a3be9fb1-b514-519f-5b25-b6f144a8c1ce",
"source": "https://vaultproject.io/",
"specversion": "1.0",
"type": "*",
"data": {
"event": {
"id": "a3be9fb1-b514-519f-5b25-b6f144a8c1ce",
"metadata": {
"current_version": "1",
"data_path": "secret/data/foo",
"modified": "true",
"oldest_version": "0",
"operation": "data-write",
"path": "secret/data/foo"
}
},
"event_type": "kv-v2/data-write",
"plugin_info": {
"mount_class": "secret",
"mount_accessor": "kv_5dc4d18e",
"mount_path": "secret/",
"plugin": "kv"
}
},
"datacontentype": "application/cloudevents",
"time": "2023-09-12T15:19:49.394915-07: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":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","source":"https://vaultproject.io/","specversion":"1.0","type":"*","data":{"event":{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","metadata":{"current_version":"1","data_path":"secret/data/foo","modified":"true","oldest_version":"0","operation":"data-write","path":"secret/data/foo"}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_5dc4d18e","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2023-09-12T15:19:49.394915-07: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":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","source":"https://vaultproject.io/","specversion":"1.0","type":"*","data":{"event":{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","metadata":{"current_version":"1","data_path":"secret/data/foo","modified":"true","oldest_version":"0","operation":"data-write","path":"secret/data/foo"}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_5dc4d18e","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2023-09-12T15:19:49.394915-07:00"}
...
```
## Policies
To subscribe to an event, you must have the following policy grants:
1. `read` capability on `/v1/sys/events/subscribe/{eventType}`, 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"]
}
```
1. `list` and `subscribe` capabilities on the *path of the secret* for events
related to secrets. The policy must also provide a `subscribe_event_types`
entry with the specific events subscribers are allowed to use. For example,
to receive events related to the KV secrets engine path,
`secret/my-data`, a valid policy would be:
```hcl
path "secret/my-data" {
capabilities = ["list", "subscribe"]
subscribe_event_types = ["*"]
}
```
<Highlight title="Event payload for secrets is subject to change">
If the policy for the path of the secret <strong>also</strong> contains
the <code>read</code> capability, future versions of the events functionality may include the
contents of the secret in the event payload.
</Highlight>
Vault continuously evaluates policies for WebSocket subscriptions and
caches the results for a short period of time to improve performance.
As a result, events **may** still be sent for a few minutes after a token is
revoked or a policy is deleted.
## Supported versions
Version | Support
------- | -------
<= 1.12 | Not supported
1.13 | Supported; **disabled** by default
1.14 | Supported; **disabled** by default
1.15+ | Supported; **enabled** by default
For versions where events are disabled by default, you can enable the
functionality with the `events.alpha1`
[experiment option](/vault/docs/configuration#experiments) in your Vault
configuration or from the command line with the `-experiments` flag. For example:
```shell-session
$ vault server -experiment events.alpha1
```
Reference in New Issue View Git Blame Copy Permalink