Nomad
CLI Quick Start

Install Nomad

  • 9min

  • Nomad

Nomad is an orchestration tool for deploying and managing applications. It is flexible and can run either containerized or non-containerized workloads.

In these getting started guides, you will learn about Nomad's core capabilities by installing and running a local Nomad cluster.

You can install Nomad to your local machine or you can use a pre-built Vagrant environment to run the steps in this tutorial. Choose one of the following ways of installing Nomad, follow the steps, and then continue to "Verify the installation."

Local install

Nomad is available as a pre-compiled binary or as a package for several operating systems.

To simplify the getting started experience, you can download a precompiled binary and run it on your machine locally.

After downloading Nomad, unzip the package. Make sure that the nomad binary is available on your PATH, before continuing with the other guides.

You can inspect the locations available on your path by running this command.

$ echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

The output is a list of locations separated by colons. You can make Nomad available by moving the binary to one of the listed locations, or by adding Nomad's location to your PATH.

Post-installation steps

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

Add the Nomad binary to your system path

Permanently add a new location to your path by editing your shell's settings file (usually called something like ~/.bashrc, where the part of the filename after the . and before rc is the name of your shell). In that file you should see a line that starts with export PATH=, followed by a colon-separated list of locations. Add the location of the Nomad binary to that list and save the file. Then reload your shell's configuration with the command source ~/.bashrc, replacing bash with the name of your shell.

Install CNI plugins

Nomad uses CNI plugins to configure network namespaces when using the bridge network mode. All Linux Nomad client nodes using network namespaces must have CNI plugins installed.

The following commands install the CNI reference plugins.

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

Ensure your Linux operating system distribution has been configured to allow container traffic through the bridge network to be routed via iptables. These tunables can be set as follows.

$ echo 1 | sudo tee /proc/sys/net/bridge/bridge-nf-call-arptables && \
  echo 1 | sudo tee /proc/sys/net/bridge/bridge-nf-call-ip6tables && \
  echo 1 | sudo tee /proc/sys/net/bridge/bridge-nf-call-iptables

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

/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

Use Vagrant

You can use a Vagrant to set up a development environment for Nomad. Vagrant is a tool for building and managing virtual machine environments.

NOTE: To use the Vagrant environment, first install Vagrant following these instructions. You also need a virtualization tool, such as VirtualBox.

You can download a Vagrantfile which starts a small Nomad cluster. First create a new directory for your Vagrant environment.

$ mkdir nomad-demo

Change into the directory you made with the previous command.

$ cd nomad-demo

Now you can get the Nomad installation configuration.

$ curl -O https://raw.githubusercontent.com/hashicorp/nomad/master/demo/vagrant/Vagrantfile

Now that you have created a new directory and downloaded the Vagrantfile you must create the virtual machine with the vagrant up command.

$ vagrant up

This takes a few minutes as the base Ubuntu box must be downloaded and provisioned with both Docker and Nomad. Once this completes, you should see this output.

Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'bento/ubuntu-18.04'...
...
==> default: Running provisioner: docker...

At this point the Vagrant box is running and ready to use. Once the Vagrant box is running, use the vagrant ssh command to start a shell session on it.

$ vagrant ssh

If you connect to the virtual machine properly, you should find yourself at a shell prompt for vagrant@nomad:~$

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
    deployment          Interact with deployments
    eval                Interact with evaluations
    exec                Execute commands in task
    license             Interact with Nomad Enterprise License
    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
    system              Interact with the system API
    ui                  Open the Nomad Web UI
    version             Prints the Nomad version
    volume              Interact with volumes

Next steps

In this tutorial you installed Nomad on your local machine. Continue to the next guide where you will be introduced to some of the critical vocabulary related to Nomad.

Previous
Next