HashiCorp Nomad Orchestration

advanced

Workload orchestration with Nomad cluster, Consul integration, and UI.

Overview

HashiCorp Nomad is a simple and flexible workload orchestrator that schedules containers, legacy applications, VMs, and batch jobs across on-premises and cloud environments. Unlike Kubernetes, Nomad focuses on simplicity with a single binary deployment while supporting multi-workload types beyond just containers. This makes it particularly attractive for organizations running mixed infrastructure or those seeking a lighter alternative to complex orchestration platforms. This stack combines Nomad server and client nodes with Consul for service discovery and health checking, plus Traefik for automatic load balancing and routing. Consul acts as the backbone for service registration and configuration storage, while Traefik automatically discovers services registered in Consul and routes traffic accordingly. The configuration establishes a complete orchestration environment with one server node and two client nodes, providing job scheduling, service mesh capabilities, and dynamic traffic routing. This setup is ideal for teams already invested in the HashiCorp ecosystem, organizations running heterogeneous workloads, or those transitioning from traditional infrastructure to container orchestration. The combination offers enterprise-grade scheduling with native integration between components, making it particularly valuable for companies requiring both container and non-container workload management in a unified platform.

Key Features

Multi-workload scheduling supporting Docker containers, VMs, Java applications, and batch jobs
Native Consul integration for automatic service discovery and health checking
Traefik auto-discovery of Nomad services with dynamic load balancing
Single binary Nomad deployment with minimal operational overhead
Job specification in HCL format with declarative infrastructure management
Built-in federation capabilities for multi-datacenter deployments
GPU workload support for machine learning and computational tasks
Blue-green deployment strategies with rolling updates

Common Use Cases

1Mixed workload environments running containers alongside legacy applications
2Batch processing systems requiring scheduled computational jobs
3Organizations migrating from traditional infrastructure to orchestrated environments
4Development teams needing simpler orchestration than Kubernetes
5Multi-datacenter deployments requiring federated job scheduling
6GPU-accelerated workloads for machine learning and data processing
7HashiCorp stack users integrating with existing Vault and Terraform workflows

Prerequisites

Docker Engine with privileged container support enabled
Minimum 2GB RAM available for server components (Nomad server requires 512MB, Consul 512MB)
Ports 4646-4648, 8500, 80, and 8080 available on the host system
Basic understanding of HCL configuration syntax for Nomad job specifications
Knowledge of HashiCorp Consul concepts for service registration
Familiarity with workload orchestration concepts and job scheduling

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  consul: 
3    image: hashicorp/consul:latest
4    command: agent -server -bootstrap-expect=1 -ui -client=0.0.0.0
5    ports: 
6      - "8500:8500"
7    volumes: 
8      - consul_data:/consul/data
9    networks: 
10      - nomad_net
11
12  nomad-server: 
13    image: hashicorp/nomad:latest
14    command: agent -server -bootstrap-expect=1 -bind=0.0.0.0
15    ports: 
16      - "4646:4646"
17      - "4647:4647"
18      - "4648:4648"
19    volumes: 
20      - ./nomad/server.hcl:/etc/nomad.d/nomad.hcl
21      - nomad_server:/opt/nomad/data
22    privileged: true
23    depends_on: 
24      - consul
25    networks: 
26      - nomad_net
27
28  nomad-client-1: 
29    image: hashicorp/nomad:latest
30    command: agent -client -bind=0.0.0.0
31    volumes: 
32      - ./nomad/client.hcl:/etc/nomad.d/nomad.hcl
33      - nomad_client_1:/opt/nomad/data
34      - /var/run/docker.sock:/var/run/docker.sock
35    privileged: true
36    depends_on: 
37      - nomad-server
38      - consul
39    networks: 
40      - nomad_net
41
42  nomad-client-2: 
43    image: hashicorp/nomad:latest
44    command: agent -client -bind=0.0.0.0
45    volumes: 
46      - ./nomad/client.hcl:/etc/nomad.d/nomad.hcl
47      - nomad_client_2:/opt/nomad/data
48      - /var/run/docker.sock:/var/run/docker.sock
49    privileged: true
50    depends_on: 
51      - nomad-server
52      - consul
53    networks: 
54      - nomad_net
55
56  traefik: 
57    image: traefik:v2.10
58    command: 
59      - --api.insecure=true
60      - --providers.consulcatalog=true
61      - --providers.consulcatalog.endpoint.address=consul:8500
62    ports: 
63      - "80:80"
64      - "8080:8080"
65    depends_on: 
66      - consul
67    networks: 
68      - nomad_net
69
70volumes: 
71  consul_data: 
72  nomad_server: 
73  nomad_client_1: 
74  nomad_client_2: 
75
76networks: 
77  nomad_net:

.env Template

.env

1# Nomad Cluster
2# Nomad UI at http://localhost:4646
3# Consul UI at http://localhost:8500
4# Traefik at http://localhost:8080

Usage Notes

1Nomad UI at http://localhost:4646
2Consul UI at http://localhost:8500
3Traefik for service routing
4Docker driver for containers
5Job specs in HCL format

Individual Services(5 services)

Copy individual services to mix and match with your existing compose files.

consul

consul:
  image: hashicorp/consul:latest
  command: agent -server -bootstrap-expect=1 -ui -client=0.0.0.0
  ports:
    - "8500:8500"
  volumes:
    - consul_data:/consul/data
  networks:
    - nomad_net

nomad-server

nomad-server:
  image: hashicorp/nomad:latest
  command: agent -server -bootstrap-expect=1 -bind=0.0.0.0
  ports:
    - "4646:4646"
    - "4647:4647"
    - "4648:4648"
  volumes:
    - ./nomad/server.hcl:/etc/nomad.d/nomad.hcl
    - nomad_server:/opt/nomad/data
  privileged: true
  depends_on:
    - consul
  networks:
    - nomad_net

nomad-client-1

nomad-client-1:
  image: hashicorp/nomad:latest
  command: agent -client -bind=0.0.0.0
  volumes:
    - ./nomad/client.hcl:/etc/nomad.d/nomad.hcl
    - nomad_client_1:/opt/nomad/data
    - /var/run/docker.sock:/var/run/docker.sock
  privileged: true
  depends_on:
    - nomad-server
    - consul
  networks:
    - nomad_net

nomad-client-2

nomad-client-2:
  image: hashicorp/nomad:latest
  command: agent -client -bind=0.0.0.0
  volumes:
    - ./nomad/client.hcl:/etc/nomad.d/nomad.hcl
    - nomad_client_2:/opt/nomad/data
    - /var/run/docker.sock:/var/run/docker.sock
  privileged: true
  depends_on:
    - nomad-server
    - consul
  networks:
    - nomad_net

traefik

traefik:
  image: traefik:v2.10
  command:
    - "--api.insecure=true"
    - "--providers.consulcatalog=true"
    - "--providers.consulcatalog.endpoint.address=consul:8500"
  ports:
    - "80:80"
    - "8080:8080"
  depends_on:
    - consul
  networks:
    - nomad_net

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  consul:
5    image: hashicorp/consul:latest
6    command: agent -server -bootstrap-expect=1 -ui -client=0.0.0.0
7    ports:
8      - "8500:8500"
9    volumes:
10      - consul_data:/consul/data
11    networks:
12      - nomad_net
13
14  nomad-server:
15    image: hashicorp/nomad:latest
16    command: agent -server -bootstrap-expect=1 -bind=0.0.0.0
17    ports:
18      - "4646:4646"
19      - "4647:4647"
20      - "4648:4648"
21    volumes:
22      - ./nomad/server.hcl:/etc/nomad.d/nomad.hcl
23      - nomad_server:/opt/nomad/data
24    privileged: true
25    depends_on:
26      - consul
27    networks:
28      - nomad_net
29
30  nomad-client-1:
31    image: hashicorp/nomad:latest
32    command: agent -client -bind=0.0.0.0
33    volumes:
34      - ./nomad/client.hcl:/etc/nomad.d/nomad.hcl
35      - nomad_client_1:/opt/nomad/data
36      - /var/run/docker.sock:/var/run/docker.sock
37    privileged: true
38    depends_on:
39      - nomad-server
40      - consul
41    networks:
42      - nomad_net
43
44  nomad-client-2:
45    image: hashicorp/nomad:latest
46    command: agent -client -bind=0.0.0.0
47    volumes:
48      - ./nomad/client.hcl:/etc/nomad.d/nomad.hcl
49      - nomad_client_2:/opt/nomad/data
50      - /var/run/docker.sock:/var/run/docker.sock
51    privileged: true
52    depends_on:
53      - nomad-server
54      - consul
55    networks:
56      - nomad_net
57
58  traefik:
59    image: traefik:v2.10
60    command:
61      - --api.insecure=true
62      - --providers.consulcatalog=true
63      - --providers.consulcatalog.endpoint.address=consul:8500
64    ports:
65      - "80:80"
66      - "8080:8080"
67    depends_on:
68      - consul
69    networks:
70      - nomad_net
71
72volumes:
73  consul_data:
74  nomad_server:
75  nomad_client_1:
76  nomad_client_2:
77
78networks:
79  nomad_net:
80EOF
81
82# 2. Create the .env file
83cat > .env << 'EOF'
84# Nomad Cluster
85# Nomad UI at http://localhost:4646
86# Consul UI at http://localhost:8500
87# Traefik at http://localhost:8080
88EOF
89
90# 3. Start the services
91docker compose up -d
92
93# 4. View logs
94docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/nomad-cluster/run | bash

Troubleshooting

Nomad client 'failed to fingerprint driver docker': Ensure Docker socket is properly mounted and accessible to Nomad containers
Consul UI shows unhealthy services: Verify Nomad agents can reach Consul on port 8500 and check network connectivity
Jobs stuck in pending state: Check client node resources and constraints, verify clients are connected to server
Traefik not discovering services: Confirm Consul catalog contains service registrations and Traefik can access Consul endpoint
Permission denied errors on job execution: Verify privileged mode is enabled for Nomad containers to access Docker socket
Server bootstrap fails: Ensure only one server is starting initially and bootstrap-expect matches actual server count

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

nomad-servernomad-clientconsultraefik

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download