Skip to content

quickstart.md

Latest commit

 

History

History
111 lines (77 loc) · 3.32 KB

quickstart.md

File metadata and controls

111 lines (77 loc) · 3.32 KB

Quickstart

This guide runs the example NoTailCar egress worker in Nomad. If you want private inbound access to a Nomad service instead, use one of the Serve examples in the final section.

Prerequisites

  • A Nomad cluster with Docker task driver support.
  • Tailscale account/Tailnet access.
  • A Tailscale auth key scoped for the tag you will advertise.
  • Nomad Variables enabled for storing TS_AUTHKEY.

1. Create a Tailscale auth key

Create an auth key in the Tailscale admin console.

Recommended settings for disposable Nomad allocations:

  • Ephemeral: enabled when possible.
  • Preauthorized: enabled only if automation needs it.
  • Reusable: disabled unless you understand the blast radius.
  • Tags: a narrow tag, for example tag:nomad-worker.

2. Store the auth key in Nomad Variables

nomad var put nomad/jobs/notailcar/example/secrets TS_AUTHKEY='<TAILSCALE_AUTH_KEY>'

The included examples expect that path by default.

3. Validate the example job

nomad job validate examples/egress-worker/egress-worker.nomad.hcl

4. Plan before running

nomad job plan examples/egress-worker/egress-worker.nomad.hcl

5. Run the job

nomad job run examples/egress-worker/egress-worker.nomad.hcl

6. Inspect logs

nomad job status notailcar-egress-worker
nomad alloc logs <alloc-id> egress-guard
nomad alloc logs <alloc-id> worker

A successful worker prints its observed egress IP and the guard state file.

Optional: require an exit node

Pass variables through a vars file or CLI var flags:

ts_require_exit_node   = "true"
ts_exit_node_primary   = "100.x.y.z"
ts_exit_node_fallbacks = "100.a.b.c,100.d.e.f"
ts_egress_expected_ips = "203.0.113.10"

Then run:

nomad job plan -var-file=example.vars.hcl examples/egress-worker/egress-worker.nomad.hcl
nomad job run  -var-file=example.vars.hcl examples/egress-worker/egress-worker.nomad.hcl

Do not commit vars files containing real infrastructure details.

Try Serve examples

Serve examples expose allocation-local services privately over the Tailnet:

nomad job validate examples/private-http-service/private-http-service.nomad.hcl
nomad job validate examples/private-dashboard/private-dashboard.nomad.hcl
nomad job validate examples/private-api-service/private-api-service.nomad.hcl
nomad job validate examples/private-multi-port-service/private-multi-port-service.nomad.hcl
nomad job validate examples/private-tcp-service/private-tcp-service.nomad.hcl
nomad job validate examples/private-serve-config/private-serve-config.nomad.hcl
nomad job validate examples/private-service-acl/private-service-acl.nomad.hcl

Run one with the same Nomad Variables path:

nomad job plan examples/private-api-service/private-api-service.nomad.hcl
nomad job run examples/private-api-service/private-api-service.nomad.hcl

Try Egress examples

Egress examples run workers, agents, crawlers, and scheduled jobs through the local Tailscale HTTP/SOCKS proxy:

nomad job validate examples/agent-worker-egress/agent-worker.nomad.hcl
nomad job validate examples/multi-worker-pool/multi-worker-pool.nomad.hcl
nomad job validate examples/webhook-bridge/webhook-bridge.nomad.hcl
nomad job validate examples/scheduled-batch-egress/scheduled-batch-egress.nomad.hcl

Each example directory has its own README and Mermaid diagram.