kemko/nomad
1
0
Fork 0
mirror of https://github.com/kemko/nomad.git synced 2026-01-07 10:55:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

Events/docs (#9100)

Browse Source 
* /v1/event/stream docs

* events sidebar

* wip server config

* make ids match

* fix typo

* add server config opts

* Update website/pages/api-docs/events.mdx

Co-authored-by: Seth Hoenig <shoenig@hashicorp.com>

* Update website/pages/api-docs/events.mdx

Co-authored-by: Seth Hoenig <shoenig@hashicorp.com>

* address feedback

Co-authored-by: Seth Hoenig <shoenig@hashicorp.com>
This commit is contained in:
Drew Bailey
2020-10-16 11:23:47 -04:00
committed by GitHub
parent 2b11e52fe9
commit e49bd2e33e
3 changed files with 643 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
website/data/api-navigation.js
View File

@@ -18,6 +18,7 @@ export default [
'client',
'deployments',
'evaluations',
'events',
'jobs',
'namespaces',
'nodes',

626
website/pages/api-docs/events.mdx Normal file
View File

@@ -0,0 +1,626 @@
---
layout: api
page_title: Events - HTTP API
sidebar_title: Events
description: |-
The /event endpoints are used to query for and stream Nomad events.
---
# Events HTTP API
The `/event` endpoints are used to query for recent events.
## 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
}
}
}
]
}
{
"Index": 8,
"Events": [
{
"Topic": "Node",
"Type": "NodeEvent",
"Key": "ccc4ce56-7f0a-4124-b8b1-a4015aa82c40",
"Namespace": "",
"FilterKeys": null,
"Index": 8,
"Payload": {
"Node": {
"ID": "ccc4ce56-7f0a-4124-b8b1-a4015aa82c40",
"SecretID": "089437c0-db81-6622-5490-9d7f9203dae5",
"Datacenter": "dc1",
"Name": "x1c",
"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": "ready",
"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": 8
}
}
}
]
}
```

16
website/pages/docs/configuration/server.mdx
View File

@@ -54,6 +54,9 @@ server {
this server will handle. This can be used to restrict the evaluations that
worker threads will dequeue for processing.
- `enable_event_broker` `(bool: true)` - Specifies if this server will generate
events for its event stream.
- `encrypt` `(string: "")` - Specifies the secret key to use for encryption of
Nomad server's gossip network traffic. This key must be 32 bytes that are
base64-encoded. The provided key is automatically persisted to the data
@@ -65,6 +68,11 @@ server {
[encryption documentation][encryption] for more details on this option
and its impact on the cluster.
- `event_buffer_size` `(int: 100)` - Specifies the number of events generated
by the server to be held in memory. Increasing this value enables new
subscribers to have a larger look back window when initially subscribing.
Decreasing will lower the amount of memory used for the event buffer.
- `node_gc_threshold` `(string: "24h")` - Specifies how long a node must be in a
terminal state before it is garbage collected and purged from the system. This
is specified using a label suffix like "30s" or "1h".
@@ -90,6 +98,14 @@ server {
deployment must be in the terminal state before it is eligible for garbage
collection. This is specified using a label suffix like "30s" or "1h".
- `durable_event_count` `(int: 100)` - Specifies the number of events to
persist during snapshot generation. This provides a given server's event
stream durability during restarts by persiting a backlog of events to be
repopulated when the server comes back online. Increasing this value provides
a greater history of messages when a server comes online. Decreasing this
value reduces the history of messages but uses less disk i/o during
snapshot creation.
- `csi_volume_claim_gc_threshold` `(string: "1h")` - Specifies the minimum age of
a CSI volume before it is eligible to have its claims garbage collected.
This is specified using a label suffix like "30s" or "1h".