Install Nomad

Nomad is available as a pre-compiled binary or as a package for several operating systems. You can also build Nomad from source.

If you are interested in trialing Nomad without installing it locally, see the Quickstart for options to get started with Nomad.

Install the required packages.

$ sudo apt-get update && \
  sudo apt-get install wget gpg coreutils

Add the HashiCorp GPG key.

$ wget -O- https://apt.releases.hashicorp.com/gpg | \
  sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

Add the official HashiCorp Linux repository.

$ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" \
| sudo tee /etc/apt/sources.list.d/hashicorp.list

Update and install.

$ sudo apt-get update && sudo apt-get install nomad

Install yum-config-manager to manage your repositories.

$ sudo yum install -y yum-utils

Use yum-config-manager to add the official HashiCorp Linux repository.

$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

Install.

$ sudo yum -y install nomad

Install dnf config-manager to manage your repositories.

$ sudo dnf install -y dnf-plugins-core

Use dnf config-manager to add the official HashiCorp Linux repository.

$ sudo dnf config-manager \
  --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo

Install.

$ sudo dnf -y install nomad

Install yum-config-manager to manage your repositories.

$ sudo yum install -y yum-utils

Use yum-config-manager to add the official HashiCorp Linux repository.

$ sudo yum-config-manager \
  --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo

Install.

$ sudo yum -y install nomad

Homebrew is a free and open source package management system for Mac OS X. Install the official Nomad formula from the terminal.

First, install the HashiCorp tap, a repository of all of the HashiCorp Homebrew packages.

$ brew tap hashicorp/tap

Now, install Nomad with hashicorp/tap/nomad.

$ brew install hashicorp/tap/nomad

This installs a signed binary and is automatically updated with every new official release.

To update to the latest, run

$ brew upgrade hashicorp/tap/nomad

Chocolatey is a free and open-source package management system for Windows. Install the Nomad package from the command-line.

$ choco install nomad

Chocolatey and the Nomad package are NOT directly maintained by HashiCorp. The latest version of Nomad is always available by manual installation.

Linux post-installation steps

These steps are optional but can be helpful for running Nomad and to take advantage of additional Nomad functionalities.

You need to run client agents as root (or with sudo) so that cpuset accounting and network namespaces work correctly.

Install CNI reference plugins

Nomad uses CNI plugins to configure network namespaces when using the bridge network mode. You must install the CNI plugins on all Linux Nomad client nodes that use network namespaces. Refer to the CNI Plugins external guide for details on individual plugins.

The following series of commands determines your operating system architecture, downloads the CNI 1.5.1 release, and then extracts the CNI plugin binaries into the /opt/cni/bin directory. Update the CNI_PLUGIN_VERSION value to use a different release version.

$ export ARCH_CNI=$( [ $(uname -m) = aarch64 ] && echo arm64 || echo amd64)
$ export CNI_PLUGIN_VERSION=v1.5.1
$ curl -L -o cni-plugins.tgz "https://github.com/containernetworking/plugins/releases/download/${CNI_PLUGIN_VERSION}/cni-plugins-linux-${ARCH_CNI}-${CNI_PLUGIN_VERSION}".tgz && \
  sudo mkdir -p /opt/cni/bin && \
  sudo tar -C /opt/cni/bin -xzf cni-plugins.tgz

Nomad looks for CNI plugin binaries by default in the /opt/cni/bin directory. However, you may install in the binaries in a different directory and then configure using the cni_path attribute.

Install consul-cni plugin

When you use the transparent_proxy block for Consul service mesh, you must also install the consul-cni plugin on each client node for Consul to properly redirect inbound and outbound traffic for services to the Envoy proxy. For more information, refer to Enable the Consul CNI plugin in the Consul documentation.

You must install the CNI plugins before you install the Consul CNI plugin. The following commands assume that you already installed the CNI plugins.

Install the consul-cni plugin on each client node.

$ sudo apt-get install -y consul-cni

$ export ARCH_CNI=$( [ $(uname -m) = aarch64 ] && echo arm64 || echo amd64)
$ curl -L -o consul-cni.zip "https://releases.hashicorp.com/consul-cni/1.5.1/consul-cni_1.5.1_linux_${ARCH_CNI}".zip && \
  sudo unzip consul-cni.zip -d /opt/cni/bin -x LICENSE.txt

Configure bridge network to route traffic through iptables

Nomad's task group networks integrate with Consul's service mesh using bridge networking and iptables to send traffic between containers.

Warning: New Linux versions, such as Ubuntu 24.04, may not enable bridge networking by default. Use sudo modprobe bridge to load the bridge module if it is missing.

The Linux kernel bridge module has three tunable parameters that control whether iptables processes traffic crossing the bridge. Some operating systems, including RedHat, CentOS, and Fedora, might have iptables rules that are not correctly configured for guest traffic because these tunable parameters are optimized for VM workloads.

Ensure your Linux operating system distribution is configured to allow iptables to route container traffic through the bridge network. Run the following commands to set the tunable parameters to allow iptables processing for the bridge network.

$ echo 1 > /proc/sys/net/bridge/bridge-nf-call-arptables
$ echo 1 > /proc/sys/net/bridge/bridge-nf-call-ip6tables
$ echo 1 > /proc/sys/net/bridge/bridge-nf-call-iptables

To preserve these settings on startup of a client node, add a file to /etc/sysctl.d/ or remove the file your Linux distribution puts in that directory. The following example configures the tunable parameters for a client node.

/etc/sysctl.d/bridge.conf

net.bridge.bridge-nf-call-arptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1

Verify cgroup controllers

On Linux, Nomad uses cgroups to control access to resources like CPU and memory. Nomad supports both cgroups v2 and the legacy cgroups v1. When Nomad clients start, they determine the available cgroup controllers and include the attribute os.cgroups.version in their fingerprint.

On cgroups v2, you can run the following command to verify that you have all required controllers.

$ cat /sys/fs/cgroup/cgroup.controllers
cpuset cpu io memory pids

On legacy cgroups v1, this same list of required controllers appears as a series of sub-directories under the directory /sys/fs/cgroup.

Refer to the cgroup controller requirements for more details and to enable missing cgroups.

Verify the Installation

To verify Nomad was installed correctly, try the nomad command.

$ nomad

You should see help output, similar to the following.

Usage: nomad [-version] [-help] [-autocomplete-(un)install] <command> [args]

Common commands:
    run         Run a new job or update an existing job
    stop        Stop a running job
    status      Display the status output for a resource
    alloc       Interact with allocations
    job         Interact with jobs
    node        Interact with nodes
    agent       Runs a Nomad agent

Other commands:
    acl                 Interact with ACL policies and tokens
    agent-info          Display status information about the local agent
    config              Interact with configurations
    deployment          Interact with deployments
    eval                Interact with evaluations
    exec                Execute commands in task
    fmt                 Rewrites Nomad config and job files to canonical format
    license             Interact with Nomad Enterprise License
    login               Login to Nomad using an auth method
    monitor             Stream logs from a Nomad agent
    namespace           Interact with namespaces
    operator            Provides cluster-level tools for Nomad operators
    plugin              Inspect plugins
    quota               Interact with quotas
    recommendation      Interact with the Nomad recommendation endpoint
    scaling             Interact with the Nomad scaling endpoint
    sentinel            Interact with Sentinel policies
    server              Interact with servers
    service             Interact with registered services
    system              Interact with the system API
    tls                 Generate Self Signed TLS Certificates for Nomad
    ui                  Open the Nomad Web UI
    var                 Interact with variables
    version             Prints the Nomad version
    volume              Interact with volumes

Compiling from Source

To compile from source, you will need Go installed at the version described by the .go-version file. You should properly configure your Go environment, including setting a GOPATH environment variable and ensuring GOPATH/bin is within your PATH. A copy of git is also needed in your PATH.

Clone the Nomad repository from GitHub into your GOPATH:

$ mkdir -p $GOPATH/src/github.com/hashicorp && cd $_
$ git clone https://github.com/hashicorp/nomad.git
$ cd nomad

Bootstrap the project. This will download and compile libraries and tools needed to compile Nomad:
```
$ make bootstrap
```
Build Nomad for your current system and put the binary in ./bin/ (relative to the git checkout). The make dev target is just a shortcut that builds nomad for only your local build environment (no cross-compiled targets).
```
$ make dev
```