nomad/website/content/docs/concepts/job.mdx

---
layout: docs
page_title: Job
description: |-
  Learn how a Nomad workload, called a job, deploys your apps, maintenance scripts, cron jobs, and similar tasks. Review job statuses and how Nomad versions your jobs.
---

# Job

This page contains conceptual information about jobs, which are the main Nomad
constructs for workloads that run your apps, maintenance scripts, cron jobs, and
other tasks. Review job statuses and how Nomad versions your jobs.

## 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][task-groups].

Declare the desired state of your job in a [job specification][job-spec], 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.

@include 'job-status-map.mdx'

### CLI statuses

Only the CLI returns these job statuses.

#### `running`

The `running` status indicates that the job has non-terminal allocations.

#### `dead`

The `dead` status indicates that all evaluations and allocations are in a
terminal state.

#### `dead (stopped)`

The `dead (stopped)` status indicates that a user has manually stopped the job.
You may start this job again.

### UI statuses

These job statuses only appear in the Nomad UI.

#### Complete

The `Complete` status indicates 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][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][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][revert-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 the same job or as
a new job. After you select the version to clone, you may edit, plan, and run
the new version.

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

Refer to the [Clone a version section][clone-version-section] of
the Job versions guide for cloning examples.

## Related resources

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

- The [job specification][job-spec] 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][quickstart] tutorials cover deploying an application and
  its resources, which include parameterized and periodic jobs.
- The [Deploy and Manage Jobs][deploy-jobs] tutorial contains examples of different types of jobs.
- The [Create Nomad Job Specifications][job-spec-tutorial] collection explains several aspects of job creation, including parameterized jobs and deploying a Java app on Nomad.


[allocations]: /nomad/docs/glossary#allocation
[deployment]: /nomad/docs/glossary/#deployment
[deploy-jobs]: /nomad/tutorials/manage-jobs/
[job-spec]: /nomad/docs/job-specification
[job-spec-tutorial]: /nomad/tutorials/job-specifications
[quickstart]: /nomad/tutorials/get-started/gs-deploy-job
[Schedulers]: /nomad/docs/schedulers
[task-groups]: /nomad/docs/glossary#task-group
[tasks]: /nomad/docs/glossary#task
[job-versions-guide]: /nomad/tutorials/manage-jobs/jobs-version
[compare-versions-section]: /nomad/tutorials/manage-jobs/jobs-version#compare-versions
[revert-version-section]: /nomad/tutorials/manage-jobs/jobs-version#revert-to-a-version
[clone-version-section]: /nomad/tutorials/manage-jobs/jobs-version#clone-a-version