diff --git a/website/data/api-navigation.js b/website/data/api-navigation.js index 943fbaffb..be14a6d60 100644 --- a/website/data/api-navigation.js +++ b/website/data/api-navigation.js @@ -18,6 +18,7 @@ export default [ 'client', 'deployments', 'evaluations', + 'events', 'jobs', 'namespaces', 'nodes', diff --git a/website/pages/api-docs/events.mdx b/website/pages/api-docs/events.mdx new file mode 100644 index 000000000..967f06f5c --- /dev/null +++ b/website/pages/api-docs/events.mdx @@ -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 + } + } + } + ] +} +``` diff --git a/website/pages/docs/configuration/server.mdx b/website/pages/docs/configuration/server.mdx index 5c7cbd05b..efc4b1266 100644 --- a/website/pages/docs/configuration/server.mdx +++ b/website/pages/docs/configuration/server.mdx @@ -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".