Parameterized Nomad Jobs: HCL2 Runtime Values for Multi‑Region Deployments

\n

The Problem: Duplication and Configuration Drift

\n

When you need to run the same workload across multiple Nomad regions with different container images, resource limits, or environment variables, copying and pasting job files leads to configuration drift. A change in one region must be manually replicated in others, and tracking which version runs where becomes error‑prone.

\n\n

Thesis: HCL2 Runtime Variable Interpolation

\n

Nomad's HCL2 job syntax supports ${var} interpolation. By defining variables in the job specification and supplying values via the nomad job run -var flag, you can keep a single source of truth and inject region‑specific values at dispatch time.

\n\n

Worked Example: Parameterized Job

\n

job "web-frontend" {\n  name = "web-frontend"\n  datacenters = ["${nomad_region}"]\n\n  group "api" {\n    network {\n      mode = "bridge"\n    }\n\n    task "app" {\n      driver = "docker"\n\n      # Runtime variable for container image\n      config {\n        image = "my-registry.example.com/web-app:${image_tag}"\n        ports = ["http"]\n      }\n\n      # Variable for replica count\n      count = 3\n\n      service {\n        name = "web-frontend"\n        port = "http"\n\n        check {\n          name = "HTTP health check"\n          type = "http"\n          path = "/health"\n          interval = "10s"\n          timeout = "2s"\n        }\n      }\n    }\n  }\n}

\n\n

In this job, <code>&#x24;nomad_region</code> resolves to the region supplied by the scheduler, and <code>&#x24;image_tag</code> is provided at runtime.

\n\n

Running the Job with Region‑Specific Values

\n

To deploy the job in the "us-east" region with image tag v1.4.2:

\n

nomad job run -var 'nomad_region=us-east' -var 'image_tag=v1.4.2' web-frontend.nomad

\n\n

To deploy the same job in "eu-west" with a different tag:

\n

nomad job run -var 'nomad_region=eu-west' -var 'image_tag=v1.3.9' web-frontend.nomad

\n\n

Trade‑offs and Limitations

\n

\n
• Secret exposure: Variable values are visible in the job plan and UI. Do not use -var for passwords or TLS certificates; instead integrate with Consul or Vault for secret injection.
\n
• Type constraints: Interpolation currently supports string substitution. Complex types such as lists or objects require separate configuration blocks.
\n
• Version compatibility: The ${var} syntax is available in Nomad 1.3+. Verify your cluster version before relying on this feature.
\n

\n\n

Verification Checklist

\n

\n
1. Run <code>nomad job status web-frontend</code> and confirm the job is <code>running</code> in the intended region.
\n
2. Use <code>nomad job status -verbose web-frontend</code> to inspect the resolved variables and ensure the correct image tag appears.
\n
3. Check node allocation: <code>nomad node status</code> shows the task placed on a node in the specified datacenter.
\n
4. Validate service health: <code>consul services list</code> (if Consul is integrated) should list the service instance matching the job name.
\n

\n\n

Actionable Next Steps

\n

\n
1. Identify a job you run in multiple regions and extract the variables that differ (image tag, resource limits, etc.).
\n
2. Convert the job file to use ${var} placeholders for those values.
\n
3. Start with a single‑region test: <code>nomad job run -var 'image_tag=v1.0.0' parameterized.nomad</code>
\n
4. Gradually add more regions, using the -var flag to supply region‑specific values.
\n
5. Document the variable names and expected values in your team's runbook.
\n

\n\n

Parameterizing Nomad jobs with HCL2 runtime variables reduces duplication, improves consistency across regions, and makes updates a single‑line change. Adopt this pattern early in your deployment workflow to reap long‑term operational benefits.

\n