NACP — Nomad Admission Control Proxy

NACP is a reverse proxy for the HashiCorp Nomad API. It intercepts job registration, planning, and validation requests, then runs configured mutation and validation policies before forwarding accepted jobs to Nomad.

Capabilities

Stage	Integration	Configuration type
Mutation	Embedded OPA returning JSON Patch	opa_json_patch
Mutation	OPA SDK/bundle returning JSON Patch	opa_bundle_json_patch
Mutation	JSON-Patch webhook	json_patch_webhook
Validation	Embedded OPA	opa
Validation	OPA SDK/bundle	opa_bundle
Validation	Validation webhook	webhook
Validation	Notation container-image verification	notation

Policies receive a shared payload containing the rendered Nomad job and optional request context:

{
"job": { "ID": "example" },
"context": {
"clientIP": "192.0.2.10",
"accessorID": "optional-nomad-token-accessor",
"resolveToken": true,
"tokenInfo": {
"Policies": ["example-policy"]
}
}
}

tokenInfo is deliberately sanitized and never includes the Nomad token SecretID. See types.Payload and config.RequestContext for the source contract.

Admission flow

NACP applies mutators in configuration order, then runs validators against the final mutated job. Validators receive isolated job copies and cannot alter the job forwarded to Nomad.

Admission runs for PUT and POST requests to:

• /v1/jobs
• /v1/job/<id>
• /v1/job/<id>/plan
• /v1/validate/job

Other Nomad API traffic is proxied without admission processing. Mutator or integration failures stop the request. Validation errors stop registration and planning; for Nomad's validation endpoint they are merged into the Nomad-compatible validation response. Policy warnings are merged into successful Nomad responses.

Install

Release binary

Download an archive and its signed checksum from GitHub Releases.

Go

go install github.com/mxab/nacp/cmd/nacp@latest

Container

Release images are published to ghcr.io/mxab/nacp and run as a non-root user:

docker run --rm -p 6464:6464 \
-v "$PWD/config.hcl:/etc/nacp/config.hcl:ro" \
ghcr.io/mxab/nacp:latest \
-config /etc/nacp/config.hcl

Pin a version tag rather than latest for production deployments.

Quickstart

The module's required Go version is declared in go.mod. Build and run the first embedded-OPA example from its directory so its relative Rego path resolves correctly:

go build -o nacp ./cmd/nacp
cd example/example1
../../nacp -config example1.conf.hcl

In another terminal, point the Nomad CLI at NACP:

NOMAD_ADDR=http://localhost:6464 nomad job run example/example1/example1.nomad

Without -config, NACP listens on 0.0.0.0:6464 and proxies Nomad at http://localhost:4646.

Configuration

Top-level server settings are not wrapped in a server block:

bind="0.0.0.0"port=6464nomad {
address="http://localhost:4646"
}
validator"opa""costcenter" {
opa_rule {
filename="policies/costcenter.rego"query=<<EOHerrors = data.costcenter.errorswarnings = data.costcenter.warningsEOH
}
}

Configuration is validated before the server starts. Missing controller blocks, invalid HTTP endpoints, invalid ports, incomplete TLS key pairs, and bundle controllers without an opa_sdk block are rejected with actionable startup errors. An explicitly supplied but missing configuration file is also an error.

Current combined examples:

• example/example1 — embedded OPA validation
• example/example2 — embedded OPA JSON-Patch mutation
• example/demo — webhooks, OPA SDK bundles, and telemetry
• example/notation — signed image validation

Transport and telemetry

NACP supports separate TLS configuration for its listener and upstream Nomad connection. OpenTelemetry logging, metrics, and tracing use the standard OTLP environment variables.

telemetry {
logging {
level="info"slog {
json=true
}
otel {
enabled=true
}
}
metrics {
enabled=true
}
tracing {
enabled=true
}
}

Security and availability

• Run NACP only on a trusted network path and use TLS for production traffic.
• If policies consume clientIP, ensure the proxy in front of NACP sanitizes X-Forwarded-For; NACP uses its first value.
• Enabling resolve_token performs a Nomad /v1/acl/token/self lookup. Lookup failures stop admission rather than continuing without identity context.
• Webhooks receive the full job and sanitized request context. They should use HTTPS and be treated as trusted policy services.
• Webhook requests have a 30-second timeout and bounded responses. Network, timeout, malformed-response, and non-2xx failures fail admission closed.
• OPA SDK/bundle support is currently experimental. Validate bundle refresh and degraded-mode behavior in your environment before relying on it in production.
• insecure_skip_verify and repo_plain_http are intended only for controlled development environments.

Development

Run the default checks:

test -z "$(gofmt -l .)"
go vet ./...
go test ./...

Notation registry tests require Docker and are opt-in locally:

go test -tags=integration ./pkg/admissionctrl/notation

CI runs the full suite with the integration tag and publishes coverage to SonarCloud.

Documentation

Start with the generated OpenWiki quickstart, then continue to:

• Architecture and request lifecycle
• Policy integrations and contracts
• Operations and testing
• Source map
• Examples
• Contributing
• Security policy
• Changelog

OpenWiki pages are generated by automation. Correct source code and maintained documentation first, then allow the OpenWiki workflow to refresh generated pages.

License

See LICENSE.