Job

This page explains jobs, which are the main Nomad constructs for workloads that run your apps, maintenance scripts, cron jobs, and other tasks.

Background

In Nomad, a job is a user-specified state for a workload. The user expresses the job that should be running, but not where it should run. Nomad allocates resources and ensures that the actual state matches the user's desired state. A job consists of one or more tasks that you can organize into task groups.

Declare the desired state of your job in a [job specification][job-specification], or jobspec, that describes the tasks and resources necessary for the job to run. You can also include job constraints to control which clients Nomad runs the job on.

When you submit your job specification, Nomad automatically allocates resources to run it. Nomad also makes sure that the actual job state matches your desired state.

Job statuses

After you submit your job, Nomad assigns a status to indicate how a job is performing. This status indicates how the job's current allocations compare to the desired job state.

Nomad uses one of three values to describe a job's status.

• complete
• dead
• running

The CLI and API return these rigid statuses, which are useful for scheduling and garbage collection. However, the Nomad UI displays additional human-readable statuses to help you manage jobs.

The following table maps the CLI and API statuses to the statuses that appear in the Nomad UI.

UI statuses

These job statuses only appear in the Nomad UI.

Complete

The Complete status indicated that all expected allocations are complete. This status applies to batch and sysbatch jobs only.

Degraded

The Degraded status indicates that a deployment is not taking place. Some allocations are failed, lost, or unplaced.

Deploying

The Deploying status indicates that a deployment is actively taking place.

Failed

The Failed status indicates that all allocations are failed, lost, or unplaced.

Healthy

The Healthy status indicates that all expected allocations are running and healthy.

Recovering

The Recovering status indicates that some allocations are pending.

Removed

The Removed status indicates that the job appeared in the initial query, but the garbage collector has since removed the job. This happens when the user remains on the page for a long time.

Running

The Running status indicates that all expected allocations are running. This status applies to batch and sysbatch jobs only.

Scaled Down

The Scaled Down status indicates that a user has scaled all allocations to zero. Nomad's garbage collector has not yet removed or purged the job.

Stopped

The Stopped status indicates that a user has manually stopped the job. Nomad's garbage collector has not yet removed or purged the job.

Job versions

Nomad creates a new version for your job each time you run your job. A job can have an unlimited number of versions, and version history is stored in state. Over time, Nomad garbage collects dead versions that do not have a version tag.

Tag a version

When you want to save or pin a specific version, you need to create a version tag with a unique name and optional description. Nomad does not garbage collect tagged versions even when the tagged version is dead. This lets you revert to a previous version regardless of how old the tagged version is.

You can create, modify, and remove tags using the CLI, API, and web UI. Refer to the Job versions guide for examples.

Compare versions

You can compare the current job version to all previous versions or to a specific version. Additionally, you can compare two specific versions.

Run commands like nomad job history to review differences between past versions of jobs and their immediate predecessors. Additionally, you can run nomad job plan to review the hypothetical difference of an update against the current job version.

Refer to the Compare versions section of the Job versions guide for examples.

Revert to a previous version

You can revert the current running job to a previous version. Nomad stops the running job and deploys the chosen version with a new version number.

Refer to the Revert to a version section of the Job versions guide for examples using the CLI, API, and web UI.

Clone and edit

Using the web UI, you may clone a version as a new version of same job or as a new job. After you select the version to clone, Nomad loads a screen where you can edit, plan, and run the new version.

Because Nomad passes job version attributes using query params, you can copy the browser address bar URL on the Jobs/Run screen to send a link to an editable job spec.

Related resources

Refer to the following Nomad documentation pages for more information about jobs:

• The job specification contains detailed configuration and examples.
• The Schedulers page explains the different types of Nomad schedulers and how those schedulers run jobs.

These tutorial resources contain examples of different kinds of jobs and how to configure them:

• The Quick Start tutorials cover deploying an application and its resources, which include parameterized and periodic jobs.
• The Deploy and Manage Jobs tutorial contains examples of different types of jobs.
• The Create Nomad Job Specifications collection explains several aspects of job creation, including parameterized jobs and deploying a Java app on Nomad.