Difficulty: Beginner
Estimated Time: 10 minutes

Introduction to Nomad

Welcome to the intro guide to Nomad! This guide is the best place to start with Nomad. We cover what Nomad is, what problems it can solve, how it compares to existing software, and contains a quick start for using Nomad.

We have pre-configured a single node Nomad and Consul environment, using the terminal window built into this tutorial you will be able try out many of Nomad's fantastic features. First we are going to take a look at how you can run a simple Job in Nomad.

If you are already familiar with the basics of Nomad, the documentation provides a better reference guide for all available features as well as internals.

This is just a simple introduction to operating jobs with Nomad, why not take a look at the documentation and create your own job files https://www.nomadproject.io/docs/job-specification/index.html. The playground environment has only a single node but is fully featured for you to experiment with.

Don’t stop now! The next scenario will only take about 10 minutes to complete.

Introduction to Nomad

Step 1 of 3

Creating and Running Jobs

This tutorial has a fully featured Nomad and Consul environment configured for you to play with. You can execute commands in the terminal window on the right or you can also click on the code examples which have the return symbol to automatically execute the snippet in the terminal.

Jobs are the primary configuration that users interact with when using Nomad. A job is a declarative specification of tasks that Nomad should run. Jobs have a globally unique name, one or many task groups, which are themselves collections of one or many tasks.

The format of the jobs is documented in the job specification. They can either be specified in HashiCorp Configuration Language or JSON, however we recommend only using JSON when the configuration is generated by a machine.

Running a Job

To get started, we are going to use the example file example.nomad which you can see open in the editor window.

In this example job file, we have declared a single task 'redis' which is using the Docker driver to run the task. The primary way you interact with Nomad is with the run command. The run command takes a job file and registers it with Nomad. This is used both to register new jobs and to update existing jobs.

We can register our example job now:

nomad run example.nomad

==> Monitoring evaluation "26cfc69e"
    Evaluation triggered by job "example"
    Allocation "8ba85cef" created: node "171a583b", group "cache"
    Evaluation status changed: "pending" -> "complete"
==> Evaluation "26cfc69e" finished with status "complete"

Anytime a job is updated, Nomad creates an evaluation to determine what actions need to take place. In this case, because this is a new job, Nomad has determined that an allocation should be created and has scheduled it on our local agent.

To inspect the status of our job we use the status command:

nomad status example

ID            = example
Name          = example
Submit Date   = 07/25/17 23:14:43 UTC
Type          = service
Priority      = 50
Datacenters   = dc1
Status        = running
Periodic      = false
Parameterized = false

Summary
Task Group  Queued  Starting  Running  Failed  Complete  Lost
cache       0       0         1        0       0         0

Latest Deployment
ID          = 11c5cdc8
Status      = successful
Description = Deployment completed successfully

Deployed
Task Group  Desired  Placed  Healthy  Unhealthy
cache       1        1       1        0

Allocations
ID        Node ID   Task Group  Version  Desired  Status   Created At
8ba85cef  171a583b  cache       0        run      running  07/25/17 23:14:43 UTC

Here we can see that the result of our evaluation was the creation of an allocation that is now running on the local node.

An allocation represents an instance of Task Group placed on a node. To inspect an allocation we use the alloc-status command:

$ nomad alloc-status 8ba85cef
ID                  = 8ba85cef
Eval ID             = 61b0b423
Name                = example.cache[0]
Node ID             = 171a583b
Job ID              = example
Job Version         = 0
Client Status       = running
Client Description  = <none>
Desired Status      = run
Desired Description = <none>
Created At          = 07/25/17 23:14:43 UTC
Deployment ID       = fa882a5b
Deployment Health   = healthy

Task "redis" is "running"
Task Resources
CPU    Memory           Disk     IOPS  Addresses
2/500  6.3 MiB/256 MiB  300 MiB  0     db: 127.0.0.1:30329

Recent Events:
Time                   Type      Description
07/25/17 23:14:53 UTC  Started     Task started by client
07/25/17 23:14:43 UTC  Driver      Downloading image redis:3.2
07/25/17 23:14:43 UTC  Task Setup  Building Task Directory
07/25/17 23:14:43 UTC  Received    Task received by client

We can see that Nomad reports the state of the allocation as well as its current resource usage. By supplying the -stats flag, more detailed resource usage statistics will be reported.

To see the logs of a task, we can use the logs command:

$ nomad logs 8ba85cef redis
                 _._
            _.-``__ ''-._
       _.-``    `.  `_.  ''-._           Redis 3.2.1 (00000000/0) 64 bit
   .-`` .-```.  ```\/    _.,_ ''-._
  (    '      ,       .-`  | `,    )     Running in standalone mode
  |`-._`-...-` __...-.``-._|'` _.-'|     Port: 6379
  |    `-._   `._    /     _.-'    |     PID: 1
   `-._    `-._  `-./  _.-'    _.-'
  |`-._`-._    `-.__.-'    _.-'_.-'|
  |    `-._`-._        _.-'_.-'    |           http://redis.io
   `-._    `-._`-.__.-'_.-'    _.-'
  |`-._`-._    `-.__.-'    _.-'_.-'|
  |    `-._`-._        _.-'_.-'    |
   `-._    `-._`-.__.-'_.-'    _.-'
       `-._    `-.__.-'    _.-'
           `-._        _.-'
               `-.__.-'
...