Introduction to Nomad
In this guide, you'll learn what Nomad is and how to run one or more instances of a
redis server with it.
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.
Introduction to Nomad
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.
To make the rest of these commands easier, you'll need to create a
JOB_ID variable with the value under
ID in the output of the last command. Copy and paste the value under ID that looks something like
Verify this by running the following command. You should see your job ID.
An allocation represents an instance of Task Group placed on a node. To inspect an allocation we use the
nomad alloc-status $JOB_ID
$ nomad alloc-status 8ba85cef ID = 8ba85cef Eval ID = 61b0b423 Name = example.cache 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
nomad logs $JOB_ID redis
$ nomad logs 8ba85cef redis _._ _.-``__ ''-._ _.-`` `. `_. ''-._ Redis 3.2.1 (00000000/0) 64 bit .-`` .-```. ```\/ _.,_ ''-._ ( ' , .-` | `, ) Running in standalone mode |`-._`-...-` __...-.``-._|'` _.-'| Port: 6379 | `-._ `._ / _.-' | PID: 1 `-._ `-._ `-./ _.-' _.-' |`-._`-._ `-.__.-' _.-'_.-'| | `-._`-._ _.-'_.-' | http://redis.io `-._ `-._`-.__.-'_.-' _.-' |`-._`-._ `-.__.-' _.-'_.-'| | `-._`-._ _.-'_.-' | `-._ `-._`-.__.-'_.-' _.-' `-._ `-.__.-' _.-' `-._ _.-' `-.__.-' ...