Nomad Cluster

The nomad_cluster resource creates HashiCorp Nomad clusters as Docker containers. Nomad clusters can be configured as single-node combined server/client instances or multi-node setups with dedicated server and client nodes.

Use Cases

As a lab author, you can use nomad_cluster resources to:

• Container Orchestration Learning: Provide hands-on experience with HashiCorp Nomad for container scheduling and management
• Multi-Node Cluster Scenarios: Create realistic distributed computing environments with server and client nodes
• Microservices Architecture: Deploy and manage complex multi-tier applications using Nomad job specifications

Nomad cluster resources enable realistic container orchestration scenarios for learning HashiCorp’s workload scheduler.

HCL Syntax

Basic Syntax

resource "nomad_cluster" "name" {
  network {
    id = resource.network.main
  }
}

Full Syntax

resource "nomad_cluster" "name" {
  # Network configuration
  network {
    id = resource.network.main
    ip_address = "10.0.0.10"
    aliases = ["nomad", "server"]
  }

  # Optional cluster configuration
  client_nodes = 3
  datacenter = "dc1"
  environment = {
    NOMAD_LOG_LEVEL = "INFO"
    CUSTOM_VAR = "value"
  }

  # Configuration files
  server_config = "./nomad/server.hcl"
  client_config = "./nomad/client.hcl"
  consul_config = "./consul/config.hcl"

  # Image configuration
  image {
    name = "hashicorp/nomad:1.8.4"
    username = "username"
    password = "password"
  }

  # Volume mounts
  volume {
    source = "./nomad-data"
    destination = "/opt/nomad/data"
    type = "bind"
    read_only = false
  }

  # Port mappings
  port {
    local = 4646
    host = 4646
    protocol = "tcp"
  }

  port_range {
    local_range = "8000-8010"
    host_range = "8000-8010"
    protocol = "tcp"
  }

  # Image copying
  copy_image {
    name = "myapp:latest"
    username = "registry_user"
    password = "registry_pass"
  }

  # Driver configuration
  config {
    docker {
      no_proxy = ["registry.local"]
      insecure_registries = ["registry.local:5000"]
    }
  }

  open_in_browser = false
}

Fields

Field	Required	Type	Description
network	✓	block	Network attachments (repeatable)
client_nodes		number	Number of dedicated client nodes. Defaults to 0 (combined server/client).
datacenter		string	Nomad datacenter name. Defaults to “dc1”.
environment		map(string)	Environment variables for all nodes. Defaults to empty map.
server_config		string	Path to custom server configuration file
client_config		string	Path to custom client configuration file
consul_config		string	Path to custom Consul configuration file
open_in_browser		bool	Open Nomad UI in browser after creation. Defaults to false.
image		block	Docker image configuration
volume		block	Volume mounts (repeatable)
port		block	Port mappings (repeatable)
port_range		block	Port range mappings (repeatable)
copy_image		block	Images to copy to cluster (repeatable)
config		block	Driver configuration

Image Block

nomad_cluster → image

Configures the Docker image for cluster nodes.

Field	Required	Type	Description
name		string	Docker image name with tag. Defaults to ghcr.io/jumppad-labs/nomad:v1.8.4.
username		string	Username for private registry authentication
password		string	Password for private registry authentication

Network Block

nomad_cluster → network

Defines network attachments for the cluster.

Field	Required	Type	Description
id	✓	reference to network	Reference to a network resource
ip_address		string	Static IP address for the server node. Auto-assigned if not specified.
aliases		list(string)	Network aliases for service discovery. Defaults to empty list.

Volume Block

nomad_cluster → volume

Configures volume mounts for persistent data and configuration.

Field	Required	Type	Description
source	✓	string	Source path on host or volume name
destination	✓	string	Mount path inside container
type		string	Volume type: “bind”, “volume”, or “tmpfs”. Defaults to “bind”.
read_only		bool	Mount as read-only. Defaults to false.
bind_propagation		string	Bind propagation: “shared”, “private”, “slave”, “rslave”, “rprivate”
bind_propagation_non_recursive		bool	Non-recursive bind mount. Defaults to false.
selinux_relabel		string	SELinux relabeling: “shared” or “private”

Port Configuration

Port mappings and exposure settings.

Field	Type	Required	Description
port	block		Port mappings (repeatable)
↳ local	int	✓	Container port
↳ host	int		Host port (default: same as local)
↳ protocol	string		Protocol: “tcp” or “udp” (default: “tcp”)
port_range	block		Port range mappings (repeatable)
↳ local_range	string	✓	Container port range (e.g., “3000-3010”)
↳ host_range	string		Host port range (default: same as local_range)
↳ protocol	string		Protocol: “tcp” or “udp” (default: “tcp”)

Image Management

Docker images to copy to cluster nodes.

Field	Type	Required	Description
copy_image	block		Images to copy to cluster (repeatable)
↳ name	string	✓	Docker image name to copy from local cache
↳ username	string		Username for private registry
↳ password	string		Password for private registry

Driver Configuration

Configuration for Nomad task drivers.

Field	Type	Required	Description
config	block		Driver configuration

Config Block

config → docker

Configures Docker driver settings for the Nomad cluster.

Field	Type	Required	Description
docker	block		Docker driver configuration
↳ no_proxy	list(string)		Registries to exclude from image cache (default: [])
↳ insecure_registries	list(string)		Registries to treat as insecure (default: [])

Computed Attributes

These attributes are set by the system after the cluster is created:

Field	Type	Description
external_ip	string	IP address of the Nomad cluster
api_port	int	Port where the Nomad API is exposed (default: 4646)
connector_port	int	Port where the Jumppad connector runs
config_dir	string	Directory containing server and client configurations
server_container_name	string	Fully qualified container name for the server
client_container_name	list(string)	Container names for client nodes (if any)

Validation Rules

• Configuration file paths are made absolute relative to the config file location
• Network attachments must reference valid network resources
• Client nodes value must be non-negative
• Volume source paths must exist for bind mounts
• Port mappings must use valid port numbers (1-65535)

Examples

Single Node Cluster

resource "network" "nomad" {
  subnet = "10.0.0.0/24"
}

resource "nomad_cluster" "dev" {
  network {
    id = resource.network.nomad
  }
}

Multi-Node Cluster

resource "network" "nomad" {
  subnet = "10.0.0.0/24"
}

resource "nomad_cluster" "production" {
  client_nodes = 3
  datacenter = "east"

  network {
    id = resource.network.nomad
    ip_address = "10.0.0.10"
    aliases = ["nomad-server", "server"]
  }

  environment = {
    NOMAD_LOG_LEVEL = "INFO"
    DATACENTER = "east"
  }

  volume {
    source = "./nomad-data"
    destination = "/opt/nomad/data"
    type = "bind"
  }

  port {
    local = 4646
    host = 4646
  }
}

Cluster with Custom Configuration

resource "nomad_cluster" "custom" {
  client_nodes = 2

  network {
    id = resource.network.main
  }

  server_config = "./config/server.hcl"
  client_config = "./config/client.hcl"
  consul_config = "./config/consul.hcl"

  config {
    docker {
      no_proxy = ["registry.internal.com"]
      insecure_registries = ["registry.internal.com:5000"]
    }
  }

  copy_image {
    name = "myapp:latest"
  }

  copy_image {
    name = "postgres:13"
  }

  volume {
    source = "./nomad-jobs"
    destination = "/opt/nomad/jobs"
    type = "bind"
    read_only = true
  }
}

Development Cluster with Port Ranges

resource "nomad_cluster" "dev" {
  network {
    id = resource.network.dev
  }

  environment = {
    NOMAD_LOG_LEVEL = "DEBUG"
  }

  port_range {
    local_range = "8000-8010"
    host_range = "8000-8010"
    protocol = "tcp"
  }

  port {
    local = 4646
    host = 4646
  }

  open_in_browser = true
}

Usage with Jobs

Nomad clusters are commonly used with nomad_job resources:

resource "nomad_cluster" "app" {
  client_nodes = 2

  network {
    id = resource.network.app
  }
}

resource "nomad_job" "web" {
  cluster = resource.nomad_cluster.app

  jobspec = <<-EOF
    job "web" {
      datacenters = ["dc1"]

      group "web" {
        count = 2

        task "nginx" {
          driver = "docker"

          config {
            image = "nginx:latest"
            ports = ["http"]
          }

          resources {
            cpu    = 100
            memory = 128
          }
        }
      }
    }
  EOF
}

Best Practices

1. Network Planning: Use dedicated networks for Nomad clusters to isolate traffic
2. Resource Limits: Configure appropriate resource limits for production workloads
3. Configuration Files: Use external configuration files for complex setups
4. Data Persistence: Mount volumes for Nomad data directories in production
5. Security: Use private registries and secure configuration for sensitive environments
6. Monitoring: Expose necessary ports for monitoring and observability tools
7. Image Management: Pre-load frequently used images using copy_image blocks