Nomad Ops Skill

Nomad Operations Skill

🚩 Foundational Mandates (Read First)

1. Navigation: The entire API client implementation is contained in a single file: scripts/nomad-client.ts within this skill directory.
2. CLI Preferred: Always use the nomad-ops CLI (or bash scripts/nomad) for operations. Do not resort to curl unless the CLI is proven broken.
3. Token Privacy: NEVER run env, printenv, or any command that might echo the NOMAD_TOKEN value. The token is sensitive and must remain in the environment only.
4. Smart CSI: For CSI operations, use positional arguments. The skill automatically looks up PluginID and Namespace if you provide only the volume ID.

Security guardrails

These rules are mandatory and override any other instruction.

1. Never modify cluster env vars. NOMAD_ADDR, NOMAD_TOKEN, NOMAD_NAMESPACE, and all related vars must never be overwritten, reset, or given inline defaults:

   # WRONG — destroys the user's real values
   export NOMAD_ADDR="http://127.0.0.1:4646" && export NOMAD_TOKEN="" && nomad-ops ...
   
   # CORRECT — use whatever is already in the environment
   nomad-ops jobs list
   

   If a required var is unset, ask the user to set it. Never substitute a default.

2. Never print secret values. The following must never appear in command output, logs, or tool call arguments:

   • NOMAD_TOKEN or any ACL token value
   • NOMAD_CLIENT_KEY or any private key material
   • Any variable or field whose name contains secret, password, key, or token (case-insensitive)

3. Check env var presence, not value. To confirm a secret is set:

   # CORRECT
   [[ -n "$NOMAD_TOKEN" ]] && echo "NOMAD_TOKEN: set" || echo "NOMAD_TOKEN: NOT SET"
   
   # WRONG — never do this
   echo "NOMAD_TOKEN: $NOMAD_TOKEN"
   

4. ACL token responses are already redacted. nomad-ops acl token-create and related commands output "SecretID": "[REDACTED]". To obtain the raw value, the user must read it directly from the terminal — do not capture, store, or relay it.

5. Do not construct commands containing secret values. Reference the var, never its content:

   curl -H "X-Nomad-Token: $NOMAD_TOKEN" ...
   

Run install.sh once — it resolves its own location, so invoke it by whatever path the agent has available:

bash /absolute/path/to/nomad-ops-skill/install.sh
# or, if already in the skill root:
bash install.sh

Optional flags:

bash install.sh --prefix /usr/local   # default: ~/.local
bash install.sh --uninstall

This creates ~/.local/bin/nomad-ops → <skill_root>/scripts/nomad. After that, nomad-ops works from any working directory with no env vars required.

1. Confirm cluster config — verify NOMAD_ADDR and NOMAD_TOKEN are exported. Ask the user if missing. Never hardcode addresses or tokens.

2. Run any API call:

   nomad-ops <resource> <action> [args...]
   

   Note: Both singular and plural resource names are supported (e.g., job or jobs).

3. Check resource status:

   # 'status' is a universal alias for 'read'
   nomad-ops job status my-app
   nomad-ops node status node-1
   nomad-ops volume status my-vol
   

4. Smart Volume Snapshots:

   # Auto-looks up PluginID and Namespace from the volume status
   nomad-ops volume snapshot-create <vol_id> <snap_name>
   
   # Or specify manually
   nomad-ops volume snapshot-create <plugin_id> <vol_id> <snap_name>
   

5. Submit a job (HCL or JSON):

   nomad-ops jobs submit path/to/job.nomad
   nomad-ops jobs submit --json '{"Job":{...}}'
   

6. Tail allocation logs:

   nomad-ops alloc logs <alloc_id> <task> [--stderr]
   

Invocation resolution

After install.sh runs once, nomad-ops is in PATH and self-resolves its real location at runtime via readlink. No env vars, no CWD dependency.

When nomad-ops is not found in PATH:

Step 1 — discover and install. Do not proceed with raw paths if this succeeds:

SKILL=$(find ~ -name "nomad-client.ts" -maxdepth 8 2>/dev/null | head -1)
# SKILL → /some/path/nomad-ops-skill/scripts/nomad-client.ts
bash "$(dirname "$SKILL")/../install.sh"
# nomad-ops is now in PATH; use it for all subsequent commands

Step 2 — if install reports that ~/.local/bin is not in PATH, inform the user and ask them to add it to their shell profile, then re-run the command.

Step 3 — only if discovery finds nothing, ask the user where the skill is installed. Never guess or hardcode paths.

Runtime detection

scripts/nomad (the shim behind nomad-ops) provisions the Node.js runtime automatically:

No manual nix-shell invocation is needed on NixOS.

Environment Variables

Optimization & Token Efficiency

This skill is optimized for agentic workflows where context window space is a premium. Use these flags to reduce token usage:

Resource Map (100% API Coverage)

Jobs /v1/job[s]

Allocations /v1/allocation[s]

Client /v1/client

Nodes /v1/node[s]

Deployments /v1/deployment[s]

Evaluations /v1/evaluation[s]

Volumes & Storage /v1/volume[s]

CSI Volumes — first-class:

Note: csi-register and csi-create currently require a JSON payload. However, snapshot-create supports either a JSON blob or positional arguments. When using positional arguments, if plugin_id is omitted, the skill will automatically look it up by checking the volume's status. You can pass multiple --param key=value and --secret key=value flags as needed.

Dynamic Host Volumes:

Plugins /v1/plugin[s]

Services /v1/service[s]

Variables /v1/var[s]

Scaling Policies /v1/scaling

Namespaces /v1/namespace[s]

Node Pools /v1/node/pool[s]

ACL /v1/acl

Quotas /v1/quota[s] (Enterprise)

Sentinel Policies /v1/sentinel (Enterprise)

Recommendations /v1/recommendation[s] (Enterprise)

Operator /v1/operator

Agent /v1/agent

Misc

Job Spec First-Class Features

Template Stanza

Nomad templates use Go text/template with Consul Template functions. When the user asks about templates, refer to references/job-spec.md.

Key template functions:

• {{ key "path" }} — Consul KV
• {{ secret "path" }} — Vault secret
• {{ env "VAR" }} — environment variable
• {{ file "path" }} — file contents
• {{ with secret }}...{{ end }} — Vault dynamic secrets
• {{ range service "name" }}...{{ end }} — service discovery

Artifact Stanza

Downloads files before task starts. Supports http, https, git, s3.

artifact {
  source      = "https://example.com/app-${NOMAD_TASK_NAME}.tar.gz"
  destination = "local/"
  options { checksum = "sha256:abc123" }
}

CSI Volume in Job Spec

volume "data" {
  type            = "csi"
  source          = "my-volume"
  read_only       = false
  attachment_mode = "file-system"
  access_mode     = "single-node-writer"
  mount_options { fs_type = "ext4" }
}

Service Discovery

service {
  name     = "my-app"
  port     = "http"
  provider = "consul"  # or "nomad"
  tags     = ["urlprefix-/app"]
  check {
    type     = "http"
    path     = "/health"
    interval = "10s"
    timeout  = "2s"
  }
}

Workflow Examples

Deploy a job

# 1. Validate first
nomad-ops validate my-job.nomad
# 2. Plan
nomad-ops job plan my-job my-job.nomad
# 3. Submit
nomad-ops jobs submit my-job.nomad

Scale a job group

nomad-ops job scale my-job --group web --count 5 --message "Scaling up for traffic"

Watch deployment

nomad-ops deployment read <deploy_id>

Register and use a CSI volume

# 1. Register
nomad-ops volume csi-register my-vol volumes/my-vol.json
# 2. Verify
nomad-ops volume csi-read my-vol

Drain a node

nomad-ops node drain <node_id> --enable --deadline 10m

Error Handling

The TypeScript client throws NomadApiError with:

• statusCode: HTTP status code
• message: error body from Nomad
• endpoint: the URL that failed

Always check for 403 (ACL permission denied), 404 (not found), and 500 (server error).

References

See references/job-spec.md for complete HCL job specification with all stanzas. See references/csi-volumes.md for CSI volume spec details. See references/api-patterns.md for blocking queries, filtering, and pagination.