nomad-holepunch

README

nomad-holepunch

Proxy the Nomad API via Workload Identity.

Overview

This nomad-holepunch program can be run as a Nomad task that proxies the Nomad API by making use of Nomad's Workload Identity authorization token and Unix domain socket.

Configuration

nomad-holepunch is configured via environment variables.

Environment Variable	Description	Default
HOLEPUNCH_BIND	The TCP address to bind to	0.0.0.0
HOLEPUNCH_PORT	The TCP port to listen on	3030
HOLEPUNCH_ALLOW_ALL	Allow access to all Nomad endpoints	false
HOLEPUNCH_ALLOW_METRICS	Allow access to Nomad /metrics API endpoints	true

Local Development

For local development, hack/localdev.hcl provides a convenient way to run the nomad-holepunch program as a raw_exec nomad job. It is assumed that nomad-holepunch is present somewhere on the user's $PATH (see Compile), and that Nomad agent is running.

running a nomad agent

sudo nomad agent -dev

compile and install

into $GOPATH/bin, assumed to be on $PATH

go install

run the localdev nomad job

nomad job run -var=user=$USER ./hack/localdev.hcl

Compile

The Makefile provides targets for building nomad-holepunch locally.

• make build (default) - compile and place binary into output/

• make test - run go test to run test cases

Container

A container is built for every version. They live in the GitHub Container Registry.

Although it isn't useful to run the container outside of Nomad, it is still possible, e.g.

➜ podman run --rm ghcr.io/shoenig/nomad-holepunch:v0.1.1
2023/06/25 19:23:52 INFO  [main] ^^ startup nomad-holepunch ^^
2023/06/25 19:23:52 TRACE [main] HOLEPUNCH_BIND = 0.0.0.0
2023/06/25 19:23:52 TRACE [main] HOLEPUNCH_PORT = 3333
2023/06/25 19:23:52 TRACE [main] HOLEPUNCH_TOKEN = <redacted>
2023/06/25 19:23:52 TRACE [main] socket path = secrets/api.sock
2023/06/25 19:23:52 TRACE [main] HOLEPUNCH_ALLOW_ALL = false
2023/06/25 19:23:52 TRACE [main] HOLEPUNCH_ALLOW_METRICS = true