Nomad — API Surface#

API types#

REST/HTTP, gRPC (internal plugin protocol), CLI, and Go library (api/ package).

REST/HTTP API#

• Router: stdlib net/http.ServeMux — no third-party router. Go 1.22 method-qualified patterns are used in a few places (e.g., "GET /v1/volumes").
• Route registration: All routes registered programmatically in command/agent/http.go:registerHandlers() via s.mux.HandleFunc(...) and s.mux.Handle(...).
• Base path: All public routes under /v1/.

Middleware chain#

Requests flow through three layers, outermost-first:

1. authMiddleware (newAuthMiddleware, http.go:1184) — wraps the entire mux for the Task API subpath. Validates X-Nomad-Token via an ACL.WhoAmI RPC call; returns 401 if token absent, 403 if invalid.
2. wrap() (http.go:738) — applies to nearly every handler. Sets custom response headers, calls auditHandler() (audit logging), maps RPC errors to HTTP codes (403 for ErrPermissionDenied, 400 for ErrIncompatibleFiltering, 500 otherwise), and handles ?pretty JSON formatting.
3. wrapCORS() / wrapCORSWithAllowedMethods() (http.go:1165–1182) — applied to specific endpoints that need cross-origin access (client filesystem, stats, allocation endpoints, variables).

Authentication#

Token-based. Clients pass a token via:

• X-Nomad-Token HTTP header (preferred), or
• ?token= query parameter.

parseToken() (http.go:1019) extracts the token and sets it on every RPC request struct. The server validates tokens against the ACL state store on each request. OIDC/JWT workload identity tokens are also accepted via the JWKS endpoint.

Key endpoints (grouped by resource)#

Blocking queries#

Every read endpoint supports Consul-style blocking queries: clients pass ?index=N&wait=Xs. The server blocks until the state store index advances past N, then responds. This is the primary “watch” mechanism — no WebSocket required for most polling. Implemented via go-memdb watch sets.

Streaming endpoints#

A few endpoints upgrade to streaming:

• /v1/event/stream — server-sent events / newline-delimited JSON stream of cluster events.
• /v1/client/fs/ and /v1/client/allocation/*/logs — WebSocket for interactive exec and log following (c.websocket() in the API client).
• /v1/agent/monitor — log stream.

gRPC API (plugin protocol)#

Nomad does not expose a public-facing gRPC API. gRPC is used exclusively for the internal driver/plugin subprocess protocol via hashicorp/go-plugin.

Proto files#

BasePlugin service (all plugins must implement)#

• PluginInfo(PluginInfoRequest) → PluginInfoResponse — name, type, version
• ConfigSchema(ConfigSchemaRequest) → ConfigSchemaResponse — HCL schema
• SetConfig(SetConfigRequest) → SetConfigResponse — push config to plugin

Driver service (task drivers)#

• TaskConfigSchema — schema for task-level HCL config
• Capabilities — what optional RPCs the driver supports
• Fingerprint(stream) — streaming driver health/capability reporting
• RecoverTask — re-attach to a running task after driver restart
• StartTask — launch a task; returns handle
• WaitTask — block until task exits
• StopTask — send signal + wait for exit with timeout
• DestroyTask — clean up resources
• InspectTask — detailed task info
• TaskStats(stream) — streaming resource usage metrics
• TaskEvents(stream) — streaming task lifecycle events
• SignalTask — send arbitrary signal (optional capability)
• ExecTask — one-shot command execution (optional)
• ExecTaskStreaming — interactive exec with streaming stdin/stdout (optional)
• CreateNetwork / DestroyNetwork — network namespace management (optional)
• NetworkIsolationSpec — get network isolation details (optional)

Transport#

All plugin gRPC runs over stdio (hashicorp/go-plugin with GRPCServer/GRPCClient). The Nomad client forks the plugin binary and connects over stdin/stdout pipes — this is not network-accessible.

CLI#

• Framework: hashicorp/cli (not cobra). Commands registered as a map[string]cli.CommandFactory in command/commands.go.
• Top-level binary: nomad <command> [subcommands] [flags]

Command structure#

Legacy top-level aliases exist for run, stop, start, plan, inspect, exec, fs, status, validate, alloc-status, eval-status, server-force-leave, server-join, server-members, client-config — all delegate to their modern equivalents.

Flag patterns#

• Global flags: -address, -region, -namespace, -token, -ca-cert, -client-cert, -client-key, -tls-server-name — available on all commands.
• Output format: many commands accept -t (Go template), -json, -verbose, -short.
• Env var binding: NOMAD_ADDR, NOMAD_REGION, NOMAD_NAMESPACE, NOMAD_TOKEN, NOMAD_CACERT, NOMAD_CLIENT_CERT, NOMAD_CLIENT_KEY map to the corresponding global flags.

Plugin / Extension system#

• Mechanism: hashicorp/go-plugin with gRPC transport over stdio. Each plugin is a separate OS process forked by the Nomad client.
• Extension points:
  • Task drivers — implement plugins/drivers.DriverPlugin interface (materialized as the Driver gRPC service). Ships as a named binary (e.g., nomad-driver-lxc).
  • Device plugins — implement plugins/device.DevicePlugin interface. Discover and expose hardware devices (GPUs, FPGAs, etc.) to Nomad.
  • CSI plugins — Container Storage Interface drivers. Communicate over a Unix socket using the standard CSI spec, managed via client/dynamicplugins.
• Plugin discovery: The pluginmanager package scans a configured plugin directory at startup. Plugins are identified by the BasePlugin.PluginInfo() RPC response.
• Built-in drivers: docker, exec, rawexec, java, qemu — all live in drivers/ and implement the same DriverPlugin interface as external drivers.
• Versioning: The plugin_api_versions field in PluginInfoResponse allows version negotiation between Nomad client and driver.

Library API (api/ package)#

The api/ package is the official Go client library for Nomad, used by the CLI and available for third-party tooling.

• Public packages: github.com/hashicorp/nomad/api — single package exposing all resources.
• API style: Resource-oriented facades. Client has accessor methods that return typed service objects:
  • c.Jobs() → *Jobs
  • c.Nodes() → *Nodes
  • c.Allocations() → *Allocations
  • c.Deployments() → *Deployments
  • c.Evaluations() → *Evaluations
  • c.ACLPolicies(), c.ACLTokens(), c.ACLRoles(), etc.
  • c.CSIVolumes(), c.Namespaces(), c.Variables(), etc.
• Blocking query support: All read methods accept *QueryOptions with WaitIndex and WaitTime. Returns *QueryMeta containing the response index for chaining.
• Write methods: All mutations accept *WriteOptions and return *WriteMeta.
• Streaming: WebSocket-based streaming for Allocations.Exec() (interactive), log following. The Events.Stream() method returns a channel of *Events.
• TLS: Full TLS config support via TLSConfig struct passed to NewClient().
• Backward compatibility: The package follows Nomad’s versioning; breaking changes tracked via changelog. No explicit semantic import versioning (v2).