mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-22 15:11:07 +02:00
0660ea6fac
* Update README Let contributors know that docs will now be located in UDR * Add comments to each mdx doc Comment has been added to all mdx docs that are not partials * chore: added changelog changelog check failure * wip: removed changelog * Fix content errors * Doc spacing * Update website/content/docs/deploy/kubernetes/vso/helm.mdx Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
246 lines
14 KiB
Plaintext
246 lines
14 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Event Notications
|
|
description: >-
|
|
Event notifications allow Vault and plugins to exchange arbitrary activity
|
|
data within Vault and with external subscribers via WebSockets.
|
|
---
|
|
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.
|
|
|
|
# Event Notifications
|
|
|
|
@include 'alerts/enterprise-only.mdx'
|
|
|
|
Event notifications 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 -->
|
|
|
|
<Note title="Note">
|
|
|
|
Event types without the `path` metadata field require a root token in order to be consumed from the `/v1/sys/events/subscribe/{eventType}` API endpoint.
|
|
|
|
</Note>
|
|
|
|
Internal components of Vault as well as external plugins can generate event notifications.
|
|
These are published to "event types", sometimes called "topics" in other event systems.
|
|
All event notifications of a specific event type will have the same format for their
|
|
additional `metadata` field.
|
|
|
|
The following event types are currently generated by Vault and its builtin plugins automatically:
|
|
|
|
| Plugin | Event Type | Metadata | Vault version |
|
|
|----------|-------------------------------------|---------------------------------------------------------------|---------------|
|
|
| database | `database/config-delete` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/config-write` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/creds-create` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/reload` | `modified`, `operation`, `path`, `plugin_name`, `vault_index` | 1.16 |
|
|
| database | `database/reload-connection` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.19 |
|
|
| database | `database/reload-connection-fail` | `modified`, `operation`, `path`, `name` | 1.19 |
|
|
| database | `database/reset` | `modified`, `operation`, `path`, `name` | 1.16 |
|
|
| database | `database/role-create` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/role-delete` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/role-update` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/root-rotate-fail` | `modified`, `operation`, `path`, `name` | 1.16 |
|
|
| database | `database/root-rotate` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/rotate-fail` | `modified`, `operation`, `path`, `name` | 1.16 |
|
|
| database | `database/rotate` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/static-creds-create-fail` | `modified`, `operation`, `path`, `name` | 1.16 |
|
|
| database | `database/static-creds-create` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/static-role-create` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/static-role-delete` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| database | `database/static-role-update` | `modified`, `operation`, `path`, `name`, `vault_index` | 1.16 |
|
|
| kv | `kv-v1/delete` | `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v1/write` | `data_path`, `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v2/config-write` | `data_path`, `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v2/data-delete` | `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v2/data-patch` | `data_path`, `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v2/data-write` | `data_path`, `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v2/delete` | `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v2/destroy` | `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v2/metadata-delete` | `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v2/metadata-patch` | `data_path`, `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v2/metadata-write` | `data_path`, `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
| kv | `kv-v2/undelete` | `data_path`, `modified`, `operation`, `path`, `vault_index` | 1.13 |
|
|
|
|
|
|
## Event notifications format
|
|
|
|
Event notifications 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 notification conforms to the [CloudEvents](https://cloudevents.io/) specification.
|
|
|
|
- `id` `(string)` - CloudEvents unique identifier for the event notification. The `id` is unique for each event notification, and event notifications with the same `id` represent the same event notification.
|
|
|
|
- `source` `(string)` - CloudEvents source, which is set to `vault://` followed by the Raft node ID or the hostname of the host that generated the event notification.
|
|
|
|
- `specversion` `(string)` - The CloudEvents specification version this conforms to.
|
|
|
|
- `type` `(string)` - CloudEvents type this event notification corresponds to, which is currently always `*`.
|
|
|
|
- `datacontentype` `(string)` - CloudEvents content type of the event notification, which is currently always `application/cloudevents`.
|
|
|
|
- `time` `(string)` - ISO 8601-formatted timestamp for when the event notification was generated.
|
|
|
|
- `data` `(object)` - Vault-specific data.
|
|
|
|
- `event` `(Event)` - contains the event notification that happened.
|
|
|
|
- `id` `(string)` - (repeat of the `id` parameter)
|
|
|
|
- `metadata` `(object)` - arbitrary extra data customized for the event type.
|
|
|
|
- `data_path` `(string)` - the API path that can be used to fetch any underlying data related to the event.
|
|
|
|
- `modified` `(string)` - a boolean value indicating if the event was the result of data being modified.
|
|
|
|
- `operation` `(string)` - the operation that was performed, e.g., `write`, `delete`, etc.
|
|
|
|
- `path` `(string)` - the API path that was invoked in order to generate the event.
|
|
|
|
- `vault_index` `(string)` - Vault's storage index when the event was generated, in the same format as the `X-Vault-Index` header returned from writes to Vault. Use `vault_index` with the other [consistency control headers](/vault/docs/enterprise/consistency#conditional-forwarding-performance-standbys-only) to avoid stale reads in response to events.
|
|
|
|
- `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 notification in JSON format:
|
|
|
|
```json
|
|
{
|
|
"id": "a3be9fb1-b514-519f-5b25-b6f144a8c1ce",
|
|
"source": "vault://mycluster",
|
|
"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",
|
|
"vault_index": "djE6MDAwYjdlMWMtZmU2Yy05NWU1LTExYzMtOGIzNjJmZjRmNDg3Ojc0NDkwNTo3NDQ5MDU6N2Q4NGFhN2NmYzc5ZWMzMjEzOGMxYTc4ZDI1YzdjYTMxN2IxOWFmZTA3NjFiZWYyMzA5NDFjOTA4Zjk4YzM0Mw=="
|
|
}
|
|
},
|
|
"event_type": "kv-v2/data-write",
|
|
"plugin_info": {
|
|
"mount_class": "secret",
|
|
"mount_accessor": "kv_5dc4d18e",
|
|
"mount_path": "secret/",
|
|
"plugin": "kv"
|
|
}
|
|
},
|
|
"datacontentype": "application/cloudevents",
|
|
"time": "2025-06-12T15:19:49.394915-07:00"
|
|
}
|
|
```
|
|
|
|
## Subscribing to event notifications
|
|
|
|
<Note title="Note">
|
|
|
|
For multi-node Vault deployments, Vault only accepts subscriptions on the active node and performance standbys.
|
|
Vault reroutes subscription requests made to [non-performance standby nodes](/vault/docs/enterprise/performance-standby#disabling-performance-standbys) to the active node based on the [`api_addr`](/vault/docs/configuration#api_addr) configuration setting on the active node.
|
|
|
|
Vault deployments with performance replication must subscribe to events on the
|
|
primary performance cluster. Vault ignores subscriptions made from secondary
|
|
clusters.
|
|
|
|
Due to the [eventually consistent](/vault/docs/enterprise/consistency) nature of
|
|
Vault's storage replication, use the [`vault_index` metadata
|
|
field](/vault/docs/concepts/events#vault_index) when reading data in response to
|
|
an event notification to avoid stale reads.
|
|
|
|
</Note>
|
|
|
|
Vault has an API endpoint, `/v1/sys/events/subscribe/{eventType}`, that allows users to subscribe to event notifications 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 event types, e.g., `kv-v2/data-*`.
|
|
|
|
By default, the event notifications 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":"vault://mycluster","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","vault_index":"djE6MDAwYjdlMWMtZmU2Yy05NWU1LTExYzMtOGIzNjJmZjRmNDg3Ojc0NDkwNTo3NDQ5MDU6N2Q4NGFhN2NmYzc5ZWMzMjEzOGMxYTc4ZDI1YzdjYTMxN2IxOWFmZTA3NjFiZWYyMzA5NDFjOTA4Zjk4YzM0Mw=="}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_5dc4d18e","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2025-06-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 event notifications (one line per event notification):
|
|
|
|
```shell-session
|
|
$ vault events subscribe kv-v2/data-write
|
|
{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","source":"vault://mycluster","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","vault_index":"djE6MDAwYjdlMWMtZmU2Yy05NWU1LTExYzMtOGIzNjJmZjRmNDg3Ojc0NDkwNTo3NDQ5MDU6N2Q4NGFhN2NmYzc5ZWMzMjEzOGMxYTc4ZDI1YzdjYTMxN2IxOWFmZTA3NjFiZWYyMzA5NDFjOTA4Zjk4YzM0Mw=="}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_5dc4d18e","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2025-06-12T15:19:49.394915-07:00"}
|
|
...
|
|
```
|
|
|
|
## Policies
|
|
|
|
To subscribe to an event notification, 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"]
|
|
}
|
|
```
|
|
|
|
2. `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 event notifications subscribers are allowed to use. For example,
|
|
to receive event notifications 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 = ["*"]
|
|
}
|
|
```
|
|
|
|
Vault continuously evaluates policies for WebSocket subscriptions and
|
|
caches the results for a short period of time to improve performance.
|
|
As a result, event notifications **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 (beta); **enabled** by default |
|
|
| 1.16+ | Generally available; **enabled** by default |
|
|
|
|
For versions where event notifications 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
|
|
```
|