luxolus/open-nomad
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity
open-nomad/website/pages/api-docs/events.mdx
Kris Hicks 1da9e7fc67
Add event sink API and CLI commands (#9226) 
Co-authored-by: Drew Bailey <2614075+drewbailey@users.noreply.github.com>
2020-11-02 09:57:35 -08:00

523 lines
15 KiB
Plaintext
Raw Blame History

---
layout: api
page_title: Events - HTTP API
sidebar_title: Events <sup>Beta</sup>
description: |-
The /event endpoints are used to query for and stream Nomad events.
---
# Events HTTP API <sup>Beta</sup>
The `/event` endpoints are used to stream events and manage event sinks. Event
sinks allow for operators to configure a sink (such as a webhook). Nomad will
subscribe to the event stream with the configured sinks topics and send events
to the sink in near real time.
## Event Stream
This endpoint streams a servers backlog of events as well as new events as they occur.
The stream will be kept alive until the connection is closed.
| Method | Path | Produces |
| ------ | ------------------ | ------------------ |
| `GET` | `/v1/event/stream` | `application/json` |
The table below shows this endpoint's [required ACLs](/api-docs#acls). Due to
the nature of this endpoint individual topics require specific policies.
| Topic | ACL Required |
| ------------ | -------------------- |
| `*` | `management` |
| `Job` | `namespace:read-job` |
| `Alloc` | `namespace:read-job` |
| `Deployment` | `namespace:read-job` |
| `Eval` | `namespace:read-job` |
| `Node` | `node:read` |
### Parameters
- `index` `(int: 0)` - Specifies the index to start streaming events from. If
the requested index is no longer in the buffer the stream will start at the
next available index.
- `topic` `(topic:filter_key: "*:*")` - Specifies a topic to subscribe to and
filter on. The default is to subscrive to all topics. Multiple topics may be
specified by passing multiple `topic` parameters. A valid topic parameter
includes a `topic` type and an optional `filter_key` separated by a colon
`:`. As an example `?topic=Deployment:redis` would subscribe to all
`Deployment` events for a job redis. an additional topic
`&topic=Deployment:web` would include deployment events for redis and web. To
only subscribe to `Node` events a topic parameter of `?topic=Node` without a
separator value would be used. `?topic=Node:*` is also valid.
### Event Topics
| Topic | Output |
| ------------ | ------------------------------- |
| Job | Job |
| Eval | Evaluation |
| Alloc | Allocation (no job information) |
| Deployment | Deployment |
| Node | Node |
| NodeDrain | Node |
### Event Types
| Type |
| ------------------------ |
| AllocCreated |
| AllocUpdated |
| AllocUpdateDesiredStatus |
| DeploymentStatusUpdate |
| DeploymentPromotion |
| DeploymentAllocHealth |
| EvalUpdated |
| JobRegistered |
| JobDeregistered |
| JobBatchDeregistered |
| NodeRegistration |
| NodeDeregistration |
| NodeEligibility |
| NodeDrain |
| NodeEvent |
| PlanResult |
### Sample Request
```shell-session
$ curl -s -v -N http://127.0.0.1:4646/v1/event/stream
```
```shell-session
$ curl -s -v -N http://127.0.0.1:4646/v1/event/stream?index=100&topic=Eval
```
```shell-session
$ curl -s -v -N \
--data-urlencode "topic=Node:ccc4ce56-7f0a-4124-b8b1-a4015aa82c40" \
--data-urlencode "topic=Deployment" \
--data-urlencode "topic=Job:web" \
http://127.0.0.1:4646/v1/event/stream
```
### Sample Response
```json
{
"Index": 7,
"Events": [
{
"Topic": "Node",
"Type": "NodeRegistration",
"Key": "ccc4ce56-7f0a-4124-b8b1-a4015aa82c40",
"Namespace": "",
"FilterKeys": null,
"Index": 7,
"Payload": {
"Node": {
"ID": "ccc4ce56-7f0a-4124-b8b1-a4015aa82c40",
"SecretID": "089437c0-db81-6622-5490-9d7f9203dae5",
"Datacenter": "dc1",
"Name": "nomad-4",
"HTTPAddr": "127.0.0.1:4646",
"TLSEnabled": false,
"Attributes": {
"cpu.arch": "amd64",
"cpu.frequency": "4200",
"cpu.modelname": "Intel(R) Core(TM) i7-8650U CPU @ 1.90GHz",
"cpu.numcores": "8",
"cpu.totalcompute": "33600",
"driver.docker": "1",
"driver.docker.bridge_ip": "172.17.0.1",
"driver.docker.os_type": "linux",
"driver.docker.runtimes": "runc",
"driver.docker.version": "19.03.13",
"driver.mock": "true",
"driver.mock_driver": "1",
"driver.raw_exec": "1",
"kernel.name": "linux",
"kernel.version": "5.4.0-48-generic",
"memory.totalbytes": "16525733888",
"nomad.advertise.address": "127.0.0.1:4646",
"nomad.revision": "8c88f29bff0849720e33b0cc73af87495358f3b8",
"nomad.version": "0.13.0-dev",
"os.name": "ubuntu",
"os.signals": "SIGBUS,SIGFPE,SIGTRAP,SIGTTOU,SIGWINCH,SIGXFSZ,SIGHUP,SIGILL,SIGALRM,SIGCHLD,SIGSYS,SIGXCPU,SIGPROF,SIGQUIT,SIGTERM,SIGUSR2,SIGCONT,SIGIO,SIGSEGV,SIGTTIN,SIGIOT,SIGKILL,SIGPIPE,SIGABRT,SIGINT,SIGSTOP,SIGTSTP,SIGURG,SIGUSR1",
"os.version": "20.04",
"unique.cgroup.mountpoint": "/sys/fs/cgroup/systemd",
"unique.hostname": "x1c",
"unique.network.ip-address": "127.0.0.1",
"unique.storage.bytesfree": "299488927744",
"unique.storage.bytestotal": "502468108288",
"unique.storage.volume": "/dev/nvme0n1p2"
},
"NodeResources": {
"Cpu": {
"CpuShares": 33600
},
"Memory": {
"MemoryMB": 15760
},
"Disk": {
"DiskMB": 285614
},
"Networks": [
{
"Mode": "bridge",
"Device": "",
"CIDR": "",
"IP": "",
"MBits": 0,
"DNS": null,
"ReservedPorts": null,
"DynamicPorts": null
},
{
"Mode": "host",
"Device": "lo",
"CIDR": "127.0.0.1/32",
"IP": "127.0.0.1",
"MBits": 1000,
"DNS": null,
"ReservedPorts": null,
"DynamicPorts": null
},
{
"Mode": "host",
"Device": "lo",
"CIDR": "::1/128",
"IP": "::1",
"MBits": 1000,
"DNS": null,
"ReservedPorts": null,
"DynamicPorts": null
}
],
"NodeNetworks": [
{
"Mode": "bridge",
"Device": "",
"MacAddress": "",
"Speed": 0,
"Addresses": null
},
{
"Mode": "host",
"Device": "lo",
"MacAddress": "",
"Speed": 1000,
"Addresses": [
{
"Family": "ipv4",
"Alias": "default",
"Address": "127.0.0.1",
"ReservedPorts": "",
"Gateway": ""
},
{
"Family": "ipv6",
"Alias": "default",
"Address": "::1",
"ReservedPorts": "",
"Gateway": ""
}
]
}
],
"Devices": null
},
"ReservedResources": {
"Cpu": {
"CpuShares": 0
},
"Memory": {
"MemoryMB": 0
},
"Disk": {
"DiskMB": 0
},
"Networks": {
"ReservedHostPorts": ""
}
},
"Resources": {
"CPU": 33600,
"MemoryMB": 15760,
"DiskMB": 285614,
"IOPS": 0,
"Networks": [
{
"Mode": "host",
"Device": "lo",
"CIDR": "127.0.0.1/32",
"IP": "127.0.0.1",
"MBits": 1000,
"DNS": null,
"ReservedPorts": null,
"DynamicPorts": null
},
{
"Mode": "host",
"Device": "lo",
"CIDR": "::1/128",
"IP": "::1",
"MBits": 1000,
"DNS": null,
"ReservedPorts": null,
"DynamicPorts": null
}
],
"Devices": null
},
"Reserved": {
"CPU": 0,
"MemoryMB": 0,
"DiskMB": 0,
"IOPS": 0,
"Networks": null,
"Devices": null
},
"Links": null,
"Meta": {
"connect.gateway_image": "envoyproxy/envoy:v1.11.2@sha256:a7769160c9c1a55bb8d07a3b71ce5d64f72b1f665f10d81aa1581bc3cf850d09",
"connect.log_level": "info",
"connect.sidecar_image": "envoyproxy/envoy:v1.11.2@sha256:a7769160c9c1a55bb8d07a3b71ce5d64f72b1f665f10d81aa1581bc3cf850d09"
},
"NodeClass": "",
"ComputedClass": "v1:9803688035578634002",
"Drain": false,
"DrainStrategy": null,
"SchedulingEligibility": "eligible",
"Status": "initializing",
"StatusDescription": "",
"StatusUpdatedAt": 1602770857,
"Events": [
{
"Message": "Node registered",
"Subsystem": "Cluster",
"Details": null,
"Timestamp": "2020-10-15T10:07:37-04:00",
"CreateIndex": 0
}
],
"Drivers": {
"docker": {
"Attributes": {
"driver.docker": "true",
"driver.docker.bridge_ip": "172.17.0.1",
"driver.docker.os_type": "linux",
"driver.docker.runtimes": "runc",
"driver.docker.version": "19.03.13"
},
"Detected": true,
"Healthy": true,
"HealthDescription": "Healthy",
"UpdateTime": "2020-10-15T10:07:37.904159516-04:00"
},
"exec": {
"Attributes": null,
"Detected": false,
"Healthy": false,
"HealthDescription": "Driver must run as root",
"UpdateTime": "2020-10-15T10:07:37.445083368-04:00"
},
"java": {
"Attributes": null,
"Detected": false,
"Healthy": false,
"HealthDescription": "Driver must run as root",
"UpdateTime": "2020-10-15T10:07:37.445601605-04:00"
},
"mock_driver": {
"Attributes": {
"driver.mock": "true"
},
"Detected": true,
"Healthy": true,
"HealthDescription": "Healthy",
"UpdateTime": "2020-10-15T10:07:37.445193068-04:00"
},
"qemu": {
"Attributes": null,
"Detected": false,
"Healthy": false,
"HealthDescription": "",
"UpdateTime": "2020-10-15T10:07:37.445684857-04:00"
},
"raw_exec": {
"Attributes": {
"driver.raw_exec": "true"
},
"Detected": true,
"Healthy": true,
"HealthDescription": "Healthy",
"UpdateTime": "2020-10-15T10:07:37.445431163-04:00"
}
},
"CSIControllerPlugins": null,
"CSINodePlugins": null,
"HostVolumes": null,
"CreateIndex": 7,
"ModifyIndex": 7
}
}
}
]
}
```
## List Event Sinks
This endpoint lists all configured event sinks.
| Method | Path | Produces |
| ------ | ------------------ | ------------------ |
| `GET` | `/v1/event/sinks` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `YES` | `operator:read` |
### Sample Request
```shell-session
$ curl \
http://localhost:4646/v1/event/sinks
```
### Sample Response
```json
[
{
"ID": "webhook",
"Type": "webhook",
"Topics": {
"*": ["*"]
},
"Address": "http://127.0.0.1:8080",
"LatestIndex": 0,
"CreateIndex": 11,
"ModifyIndex": 13
},
{
"ID": "deployment-webhook",
"Type": "webhook",
"Topics": {
"Deployment": ["*"]
},
"Address": "http://127.0.0.1:8080/deployments",
"LatestIndex": 0,
"CreateIndex": 11,
"ModifyIndex": 13
}
]
```
## Create or Update an Event Sink
This endpoint creates or updates an event sink.
| Method | Path | Produces |
| -------------- | -------------------------- | ----------------------------- |
| `POST`, `PUT` | `/v1/event/sink/:sink_id` | `200 text/plain (empty body)` |
The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `NO` | `management` |
### Sample Request
```shell-session
$ cat event-sink.json
{
"ID": "webhook",
"Address": "http://127.0.0.1:8080",
"Type": "webhook",
"Topics": {
"*": ["*"]
}
}
$ curl \
-X POST http://localhost:4646/v1/event/sink/webhook -d @event-sink.json
```
## Get an Event Sink
This endpoint returns the current configuration details of a specific event sink.
| Method | Path | Produces |
| ------ | -------------------------- | ------------------ |
| `GET` | `/v1/event/sink/:sink_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | -------------------- |
| `YES` | `operator:read` |
### Sample Request
```shell-session
$ curl \
http://localhost:4646/v1/event/sink/deployment-webhook
```
### Sample Response
```json
{
"ID": "deployment-webhook",
"Type": "webhook",
"Topics": {
"*": [
"*"
]
},
"Address": "http://127.0.0.1:8080",
"LatestIndex": 0,
"CreateIndex": 11,
"ModifyIndex": 62
}
```
## Delete an Event Sink
This endpoint deletes an event sink
| Method | Path | Produces |
| --------- | -------------------------- | ----------------------------- |
| `DELETE` | `/v1/event/sink/:sink_id` | `200 text/plain (empty body)` |
The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).
| Blocking Queries | ACL Required |
| ---------------- | ----------------- |
| `YES` | `management` |
### Sample Request
```shell-session
$ curl \
-X DELETE http://localhost:4646/v1/event/sink/deployment-webhook
```
Reference in a new issue View git blame Copy permalink