---
layout: "docs"
page_title: "job Stanza - Job Specification"
sidebar_current: "docs-job-specification-job"
description: |-
  The "job" stanza is the top-most configuration option in the job
  specification. A job is a declarative specification of tasks that Nomad
  should run.
---

# `job` Stanza

The `job` stanza is the top-most configuration option in the job specification.
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.

```hcl
job "docs" {
  all_at_once = true

  constraint {
    # ...
  }

  datacenters = ["us-east-1"]

  group "example" {
    # ...
  }

  meta {
    "my-key" = "my-value"
  }

  priority = 100

  region = "north-america"

  task "docs" {
    # ...
  }

  update {
    # ...
  }

  periodic {
    # ...
  }
}
```

## `job` Parameters

- `all_at_once` `(bool: false)` - Controls if the entire set of tasks in the job
  must be placed atomically or if they can be scheduled incrementally. This
  should only be used for special circumstances.

- `constraint` <code>([Constraint][constraint]: nil)</code> -
  This can be provided multiple times to define additional constraints. See the
  [Nomad constraint reference](/docs/job-specification/constraint.html) for more
  details.

- `datacenters` `(array<string>: required)` - A list of datacenters in the region which are eligible
  for task placement. This must be provided, and does not have a default.

- `group` <code>([Group][group]: required)</code> - Specifies the start of a
  group of tasks. This can be provided multiple times to define additional
  groups. Group names must be unique within the job file.

- `meta` <code>([Meta][]: nil)</code> - Specifies a key-value map that annotates
  with user-defined metadata.

- `periodic` <code>([Periodic][]: nil)</code> - Allows the job to be scheduled
  at fixed times, dates or intervals.

- `priority` `(int: 50)` - Specifies the job priority which is used to
  prioritize scheduling and access to resources. Must be between 1 and 100
  inclusively, with a larger value corresponding to a higher priority.

- `region` `(string: "global")` - The region in which to execute the job.

- `type` `(string: "service")` - Specifies the  [Nomad scheduler][scheduler] to
  use. Nomad provides the `service`, `system` and `batch` schedulers.

- `update` <code>([Update][update]: nil)</code> - Specifies the task's update
  strategy. When omitted, rolling updates are disabled.

## `job` Examples

### Docker Container

This example job starts a Docker container which runs as a service. Even though
the type is not specified as "service", that is the default job type.

```hcl
job "docs" {
  datacenters = ["default"]

  group "example" {
    task "server" {
      driver = "docker"
      config {
        image = "hashicorp/http-echo"
        args  = ["-text", "hello"]
      }

      resources {
        memory = 128
      }
    }
  }
}
```

### Batch Job

This example job executes the `uptime` command across all Nomad clients in the
fleet, as long as those machines are running Linux.

```hcl
job "docs" {
  datacenters = ["default"]

  type = "batch"

  constraint {
    attribute = "${attr.kernel.name}"
    value     = "linux"
  }

  group "example" {
    task "uptime" {
      driver = "exec"
      config {
        command = "uptime"
      }

      resources {
        cpu = 10
      }
    }
  }
}
```

[constraint]: /docs/job-specification/constraint.html "Nomad constraint Job Specification"
[group]: /docs/job-specification/group.html "Nomad group Job Specification"
[meta]: /docs/job-specification/meta.html "Nomad meta Job Specification"
[periodic]: /docs/job-specification/periodic.html "Nomad periodic Job Specification"
[task]: /docs/job-specification/task.html "Nomad task Job Specification"
[update]: /docs/job-specification/update.html "Nomad update Job Specification"
[meta]: /docs/job-specification/meta.html "Nomad meta Job Specification"
[scheduler]: /docs/runtime/schedulers.html "Nomad Scheduler Types"