Getting Started: Start a Nomad Agent | Nomad

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 heartbeating, 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 will start the Nomad agent in development mode. This mode is used to quickly start an agent that is acting as a client and server to test job configurations or prototype interactions. You will also use the nomad command line tool to discover the status and server membership for your agent. Finally, you will stop the agent.

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

Start a single Nomad agent in development mode with the nomad agent command. Note, this command should not be used in production as it does not persist state.

$ sudo nomad agent -dev

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.

==> No configuration files loaded
==> Starting Nomad agent...
==> Nomad agent configuration:

       Advertise Addrs: HTTP: 127.0.0.1:4646; RPC: 127.0.0.1:4647; Serf: 127.0.0.1:4648
            Bind Addrs: HTTP: 127.0.0.1:4646; RPC: 127.0.0.1:4647; Serf: 127.0.0.1:4648
                Client: true
             Log Level: DEBUG
                Region: global (DC: dc1)
                Server: true
               Version: 0.10.4

==> Nomad agent started! Log data will stream in below:

  [DEBUG] agent.plugin_loader.docker: using client connection initialized from environment: plugin_dir=
  [DEBUG] agent.plugin_loader.docker: using client connection initialized from environment: plugin_dir=
  [INFO]  agent: detected plugin: name=raw_exec type=driver plugin_version=0.1.0
  [INFO]  agent: detected plugin: name=exec type=driver plugin_version=0.1.0
  [INFO]  agent: detected plugin: name=qemu type=driver plugin_version=0.1.0
  [INFO]  agent: detected plugin: name=java type=driver plugin_version=0.1.0
  [INFO]  agent: detected plugin: name=docker type=driver plugin_version=0.1.0
  [INFO]  nomad: raft: Initial configuration (index=1): [{Suffrage:Voter ID:127.0.0.1:4647 Address:127.0.0.1:4647}]
  [INFO]  nomad: raft: Node at 127.0.0.1:4647 [Follower] entering Follower state (Leader: "")
  [INFO]  nomad: serf: EventMemberJoin: Kaitlins-MBP.global 127.0.0.1
  [INFO]  nomad: starting scheduling worker(s): num_workers=8 schedulers=[service, batch, system, _core]    2020-03-21T12:37:19.707-0500 [INFO]  client: node registration complete
  [INFO]  nomad: adding server: server="Kaitlins-MBP.global (Addr: 127.0.0.1:4647) (DC: dc1)"
  [DEBUG] nomad: lost contact with Nomad quorum, falling back to Consul for server list
  [INFO]  client: using state directory: state_dir=/private/var/folders/92/ctgjkbzx3718ws9q0vmp3v700000gp/T/NomadClient596211523
  [ERROR] nomad: error looking up Nomad servers in Consul: error="server.nomad: unable to query Consul datacenters: Get http://127.0.0.1:8500/v1/catalog/datacenters: dial tcp 127.0.0.1:8500: connect: connection refused"
  [INFO]  client: using alloc directory: alloc_dir=/private/var/folders/92/ctgjkbzx3718ws9q0vmp3v700000gp/T/NomadClient805410758
  ...
  [WARN]  nomad: raft: Heartbeat timeout from "" reached, starting election
  [INFO]  nomad: raft: Node at 127.0.0.1:4647 [Candidate] entering Candidate state in term 2
  [DEBUG] nomad: raft: Votes needed: 1
  [DEBUG] nomad: raft: Vote granted from 127.0.0.1:4647 in term 2. Tally: 1
  [INFO]  nomad: raft: Election won. Tally: 1
  [INFO]  nomad: raft: Node at 127.0.0.1:4647 [Leader] entering Leader state
  [INFO]  nomad: cluster leadership acquired

The Consul datacenter error is expected on Nomad agents that do not have a local Consul agent. The development Nomad agent will be able to operate without Consul and will not impact your progress through the Getting Started guides.

Note: 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 will function as non-root, but certain task drivers will not be available.

»Discover agent information

In another terminal, use nomad node status to view the registered nodes of the Nomad cluster.

$ nomad node status

Since you only have one local agent, your output should only include one node.

ID        DC   Name          Class   Drain  Eligibility  Status
3f12597f  dc1  Kaitlins-MBP  <none>  false  eligible     ready

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 and task draining is currently off.

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.

$ nomad server members

Since you only have one local agent, your output should only include one node.

Name                 Address    Port  Status  Leader  Protocol  Build   Datacenter  Region
Kaitlins-MBP.global  127.0.0.1  4648  alive   true    2         0.10.4  dc1         global

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.

»Stop the agent

You can use Ctrl-C, the interrupt signal, to stop the agent. By default, all signals will cause the agent to forcefully shutdown. The agent can be configured to gracefully leave on either the interrupt or terminate signals.

After interrupting the agent, the logs will show the cluster shutting down:

^C==> Caught signal: interrupt
  [DEBUG] http: shutting down http server
  [INFO]  agent: requesting shutdown
  [INFO]  client: shutting down
  [INFO]  client.plugin: shutting down plugin manager: plugin-type=device
  [INFO]  client.plugin: plugin manager finished: plugin-type=device
  [INFO]  client.plugin: shutting down plugin manager: plugin-type=driver
  [INFO]  client.plugin: plugin manager finished: plugin-type=driver
  [DEBUG] client.server_mgr: shutting down
  [INFO]  nomad: shutting down server
  [WARN]  nomad: serf: Shutdown without a Leave
  [INFO]  agent: shutdown complete

By gracefully leaving, Nomad servers notify their peers they intend to leave. When a server leaves, replication to that server stops. Nomad clients update their status to prevent further tasks from being scheduled and to start migrating any tasks that are already assigned.

»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.

Start the agent again with the sudo nomad agent -dev command before continuing to the next section.

$ sudo nomad agent -dev

Infrastructure

Security

Networking

Applications

»Start the agent

»Discover agent information

»Stop the agent

»Next steps