Nomad relies on a long running agent on every machine in the cluster. The agent can run either in server or client mode. The cluster servers are responsible for managing the cluster. All other agents in the cluster should be in client mode. A Nomad client is a very lightweight process that registers the host machine, performs heart-beating, and runs the tasks that are assigned to it by the servers. The agent must be run on every node that is part of the cluster so that the servers can assign work to those machines.
In this guide, you start the Nomad agent in development mode also called a dev
agent. Nomad dev agents quickly start a single agent that acts as a client and
server to test job configurations or prototype interactions. You also use the
nomad command-line tool to discover the status and server membership for your
agent. Finally, you create and start a sample job using the nomad job init and
nomad job run commands.
Warning: A single server deployment is highly discouraged as data loss is inevitable in a failure scenario. Each region must have at least one server, though a cluster of 3 or 5 servers is recommended for production.
»Start the agent
At the end of the Get Started: Install tutorial, you used the
nomad command to verify that you could perform the remaining steps in this
guide. If you are using Vagrant, make sure that you are in an SSH session to the
virtual machine by checking that the prompt is vagrant@nomad:$.
Now, use the sudo command to start a single Nomad agent in development mode
with the nomad agent command. Typically any agent in client mode must be
started with root level privilege. Nomad makes use of operating system
primitives for resource isolation which require elevated permissions. The agent
functions as non-root, but certain task drivers are not available.
Add the -bind flag and set the value to 0.0.0.0. Also, use the -log-level
flag and set the output log level to INFO. By default, Nomad dev agents bind
to 127.0.0.1 which causes issues with Vagrant port forwarding. Nomad dev agents
also default to DEBUG level logging, which can be a bit noisy.
Note: The nomad agent -dev command should only be used for experimental
environments because it does not persist state between runs.
The output indicates the agent has started in both server and client mode. Wait to continue to the next section until you see the agent has acquired leadership.
During startup, you might even see a log line that tells you that there is a new version of Nomad available.
This log line is informative and doesn't have any impact on the currently running agent.
»Discover agent information
Start another terminal session. When using Vagrant, start a new local shell and
then re-run the vagrant ssh command from your nomad-demo folder to get back
to the vagrant@nomad:$ prompt.
In that session, use nomad node status to view the registered nodes of
the Nomad cluster.
Since you only have one local agent, your output should only include one node.
The output shows your Node ID, its datacenter, node name, node class, drain mode and current status. The Node ID is a randomly generated UUID.
Notice that your node is in the ready state.
The agent is also in server mode, which means it is part of the gossip
protocol used to connect all the server instances together. You can view the
members of the gossip ring using the server members command.
Since you only have one local agent, your output should only include one node.
The output shows your agent, the address it is running on, its health state,
some version information, and the datacenter and region. Additional metadata can
be viewed by providing the -detailed flag.
»Run your first job
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 and 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, you should only use JSON when the configuration is generated by a machine.
Note: The job created by running nomad job init uses the Docker task
driver. To run it, you need a Nomad client available with Docker installed. This
is also true when running Nomad as a dev-agent using the -dev flag. Also, the
user that you are running Nomad as needs to be a member of the docker group.
»Generate the sample job
To get started, use the nomad job init command which generates a
well-documented sample job file:
You can view the contents of this file by running cat example.nomad. This
example job file declares a single task named redis, which uses the Docker
driver to run the a Redis container.
Did you know? You can use the -short flag of the nomad job init
command to create a similar job specification without comments or unnecessary
stanzas. You can also override the filename created by supplying it as the last
argument to the command.
The primary way you interact with Nomad is with the nomad job 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.
Register the example job now by running the job with the nomad job run
command.
The command outputs information about the scheduling process.
Here, the output indicates that the result evaluating your job submission was the creation of an allocation that is now running on the local node.
If the output of the nomad job run example.nomad command contains the
following message, verify that Docker is installed on your Nomad client nodes or
-dev agent node. The Vagrant environment provides this automatically for you.
This message indicates that there are no Nomad clients available running the Docker task driver. This is typically because Docker is stopped or not installed.
Anytime a job is updated, Nomad creates an evaluation to determine what actions need to take place. Because this is a new job, Nomad determined that an allocation should be created and has scheduled it on your local agent.
Use the nomad job status command to inspect the status of your job:
When Nomad runs a job it creates allocations based on the task groups within the
job. To inspect an allocation, use the nomad alloc status command. Replace
the allocation ID in the command with the allocation ID you received when
running nomad job status example in the preceding step.
Nomad reports the state of the allocation as well as its current resource usage.
»Fetch the job logs
Nomad automatically captures the information written to stdout and stderr into
log files for each task defined in the job specification. You can fetch these
logs using the nomad alloc logs command. To see the stderr log, you must
supply the -stderr flag before the allocation ID and task name in the command.
Run the nomad alloc logs command to fetch the logs from the redis task in
your allocation, again substituting your allocation ID into the proper place in
the command.
The command returns the information written to stdout by the redis task.
Congratulations! You're running a redis container with Nomad.
»Next steps
In this tutorial you started a local Nomad agent in development node. You then
used the nomad command line tool to discover information about your agent.
Finally, you generated a sample job using the nomad job init command and
submitted it to your Nomad agent.
Leave this example job running, because you learn how to modify, scale, and stop it in the next tutorials.
