Nomad Cluster

Defined insandbox.hcl

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"]
    }
  }
}

Fields

Field	Type	Required	Description
network	block	—	Connect this resource to a specific network so it can communicate with other containers or servicesrepeatable
image	block	—	Container image for the cluster nodes
client_nodes	number	—	Number of client nodes
environment	map(string)	—	Environment variables for the cluster
server_config	string	—	Path to server configuration file
client_config	string	—	Path to client configuration file
consul_config	string	—	Path to Consul configuration file
volume	block	—	Attach persistent storage or share data between containers using volumesrepeatable
open_in_browser	bool	—	Open the Nomad UI in the browser after creation
datacenter	string	—	Nomad datacenter, defaults to dc1
copy_image	block	—	Images to copy from local docker cache to the clusterrepeatable
port	block	—	Expose specific ports so learners can access web apps, APIs, or services running in this resourcerepeatable
port_range	block	—	Range of ports to exposerepeatable
config	block	—	Driver configuration

Network

nomad_cluster→Network

Network attachments for the cluster

Field	Type	Required	Description
id	string	—	ID of the network to attach the container
target	referencenetwork	—	The network to attach the container to
ip_address	string	—	Static IP address to assign container for the network, the ip address must be within range defined by the network subnet. If this parameter is omitted an IP address will be automatically assigned. ConstraintsMust be a valid IPv4 address (e.g., 192.168.1.10)
aliases	list(string)	—	Aliases allow alternate names to specified for the container

Image

nomad_cluster→Image

Container image for the cluster nodes

Field	Type	Required	Description
name	string	✓	Full Docker image reference, including the registry and an optional tag. Include a specific tag to ensure consistent lab environments. ConstraintsMust be a valid Docker image reference (e.g. ubuntu:24.04, docker.io/hashicorp/vault:1.14)
username	string	—	Only required for private Docker registries. Leave empty for public images.
password	string	—	Only required for private Docker registries. Leave empty for public images.

Volume

nomad_cluster→Volume

Volumes to attach to the cluster

Field	Type	Required	Description
source	string	✓	The source volume to mount in the container, can be specified as a relative `./` or absolute path `/usr/local/bin`. Relative paths are relative to the file declaring the container. ConstraintsSource path must not be empty
destination	string	✓	The destination in the container to mount the volume to, must be an absolute path ConstraintsDestination path must not be empty
type	string	—	The type of the mount, can be one of the following values: - bind: bind the source path to the destination path in the container - volume: source is a Docker volume - tmpfs: create a temporary filesystem Allowedbind volume tmpfs Defaultbind
read_only	bool	—	Whether or not the volume is read only
bind_propagation	string	—	Configures bind propagation for Docker volume mounts, only applies to bind mounts, can be one of the following values: - shared - slave - private - rslave - rprivate For more information please see the Docker documentation Allowedshared private slave rslave rprivate Defaultshared
bind_propagation_non_recursive	bool	—	Configures recursiveness of the bind mount. By default Docker mounts with the equivalent of `mount --rbind` meaning that mounts below the the source directory are visible in the container. For instance running `docker run --rm --mount type=bind,src=/,target=/host,readonly` busybox will make `/run` of the host available as `/host/run` in the container. To make matters even worse it will be writable (since only the toplevel bind is set readonly, not the children). If `bind_propagation_non_recursive` is set to true then the container will only see an empty `/host/run`, meaning the `tmpfs` which is typically mounted to `/run` on the host is not propagated into the container.
selinux_relabel	string	—	Configures Selinux relabeling for the container (usually specified as :z or :Z) and can be one of the following values: - shared (Equivalent to :z) - private (Equivalent to :Z) Allowed shared private

Copy Image

nomad_cluster→Copy Image

Images to copy from local docker cache to the cluster

Field	Type	Required	Description
name	string	✓	Full Docker image reference, including the registry and an optional tag. Include a specific tag to ensure consistent lab environments. ConstraintsMust be a valid Docker image reference (e.g. ubuntu:24.04, docker.io/hashicorp/vault:1.14)
username	string	—	Only required for private Docker registries. Leave empty for public images.
password	string	—	Only required for private Docker registries. Leave empty for public images.

Port

nomad_cluster→Port

Additional ports to expose on the server node

Field	Type	Required	Description
local	number	✓	The local port in the container ConstraintsMinimum 1; Maximum 65535
host	number	—	The host port to map the local port to ConstraintsMinimum 1; Maximum 65535
protocol	string	—	The protocol to use when exposing the port Allowedtcp udp Defaulttcp

Port Range

nomad_cluster→Port Range

Range of ports to expose

Field	Type	Required	Description
range	string	✓	Port range (e.g., '8080-8090')
enable_host	bool	—	Enable host port mapping
protocol	string	—	Protocol (tcp, udp)

Config

nomad_cluster→Config

Driver configuration

Field	Type	Required	Description
docker	block	—	Docker driver configuration

Docker

nomad_cluster→Config→Docker

Docker driver configuration

Field	Type	Required	Description
no_proxy	list(string)	—	Docker registries to exclude from the image cache
insecure_registries	list(string)	—	Docker registries to treat as insecure

Computed Attributes

These attributes are set by the system and are read-only.

Attribute	Type	Description
network[].name	string	Name will equal the name of the network as created by jumppad
network[].assigned_address	string	AssignedAddress will equal if IPAddress is set, else it will be the value automatically assigned from the network
image.id	string	Unique identifier for the image, this is independent of tag and changes each time the image is built. An image that has been tagged multiple times also shares the same ID.
copy_image[].id	string	Unique identifier for the image, this is independent of tag and changes each time the image is built. An image that has been tagged multiple times also shares the same ID.
api_port	number	Port the Nomad API is running on
connector_port	number	Port where the connector is running
config_dir	string	Directory where server and client config is written
server_container_name	string	Fully qualified docker address for the server
client_container_name	list(string)	Fully qualified docker addresses for the client nodes
external_ip	string	IP address of the cluster

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
  }
}

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