nomad/website/content/docs/job-specification/task.mdx

---
layout: docs
page_title: task block in the job specification
description: |-
  The `task` block creates an individual unit of work, such as a Docker
  container, web application, or batch processing.
---

# `task` block in the job specification

<Placement groups={['job', 'group', 'task']} />

The `task` block creates an individual unit of work, such as a Docker
container, web application, or batch processing.

```hcl
job "docs" {
  group "example" {
    task "server" {
      # ...
    }
  }
}
```

## Parameters

- `artifact` <code>([Artifact][]: nil)</code> - Defines an artifact to download
  before running the task. This may be specified multiple times to download
  multiple artifacts.

- `config` `(map<string|string>: nil)` - Specifies the driver configuration,
  which is passed directly to the driver to start the task. The details of
  configurations are specific to each driver, so please see specific driver
  documentation for more information.

- `consul` <code>([Consul][consul_jobspec]: nil)</code> - Specifies Consul
  configuration options specific to the task.

- `constraint` <code>([Constraint][]: nil)</code> - Specifies user-defined
  constraints on the task. This can be provided multiple times to define
  additional constraints.

- `affinity` <code>([Affinity][]: nil)</code> - This can be provided
  multiple times to define preferred placement criteria.

- `dispatch_payload` <code>([DispatchPayload][]: nil)</code> - Configures the
  task to have access to dispatch payloads.

- `driver` - Specifies the task driver that should be used to run the
  task. See the [driver documentation](/nomad/docs/drivers) for what
  is available. Examples include `docker`, `qemu`, `java` and `exec`.

- `env` <code>([Env][]: nil)</code> - Specifies environment variables that will
  be passed to the running process.

- `identity` <code>([Identity][]: nil)</code> - Expose [Workload Identity][] to
  the task.

- `kill_timeout` `(string: "5s")` - Specifies the duration to wait for an
  application to gracefully quit before force-killing. Nomad first sends a
  [`kill_signal`][kill_signal]. If the task does not exit before the configured
  timeout, `SIGKILL` is sent to the task. Note that the value set here is capped
  at the value set for [`max_kill_timeout`][max_kill] on the agent running the
  task, which has a default value of 30 seconds.

- `kill_signal` `(string)` - Specifies a configurable kill signal for a task,
  where the default is SIGINT (or SIGTERM for `docker`, or CTRL_BREAK_EVENT
  for `raw_exec` on Windows). Note that this is only supported for drivers
  sending signals (currently `docker`, `exec`, `raw_exec`, and `java`
  drivers).

- `leader` `(bool: false)` - Specifies whether the task is the leader task of
  the task group. If set to `true`, when the leader task completes, all other
  tasks within the task group will be gracefully shutdown. The shutdown process
  starts by applying the `shutdown_delay` if configured. It then stops the the
  leader task first, if any, followed by non-sidecar and non-poststop tasks, and
  finally sidecar tasks. Once this process completes, post-stop tasks are
  triggered. See the [lifecycle][] documentation for a complete description of
  task lifecycle management.

- `lifecycle` <code>([Lifecycle][]: nil)</code> - Specifies when a task is run
  within the lifecycle of a task group. Added in Nomad v0.11.

- `logs` <code>([Logs][]: nil)</code> - Specifies logging configuration for the
  `stdout` and `stderr` of the task.

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

- `resources` <code>([Resources][]: &lt;required&gt;)</code> - Specifies the minimum
  resource requirements such as RAM, CPU and devices.

- `service` <code>([Service][]: nil)</code> - Specifies integrations with Nomad
  or [Consul][] for service discovery. Nomad automatically registers when a task
  is started and de-registers it when the task dies.

- `shutdown_delay` `(string: "0s")` - Specifies the duration to wait when
  killing a task between removing its service registrations from Consul or Nomad,
  and sending it a shutdown signal. Ideally services would fail health checks
  once they receive a shutdown signal. Alternatively, `shutdown_delay` may be
  set to give in flight requests time to complete before shutting down. This
  `shutdown_delay` only applies to services defined at the task level by the
  [`service`](/nomad/docs/job-specification/task#service) block. In addition, task
  groups have their own [`shutdown_delay`](/nomad/docs/job-specification/group#shutdown_delay)
  which waits between de-registering group services and stopping tasks.

- `user` `(string: <varies>)` - Specifies the user that will run the task.
  Defaults to `nobody` for the [`exec`][exec] and [`java`][java] drivers.
  [Docker][] images specify their own default users. Clients can restrict
  [which drivers][user_drivers] are allowed to run tasks as [certain
  users][user_denylist]. On UNIX-like systems, setting `user` also affects
  the environment variables `HOME` and `USER` available to the task.  On
  Windows, when Nomad is running as a [system service][service] for the
  [`raw_exec`][raw_exec] driver, you may specify a less-privileged service user.
  For example, `NT AUTHORITY\LocalService`, `NT AUTHORITY\NetworkService`.

- `template` <code>([Template][]: nil)</code> - Specifies the set of templates
  to render for the task. Templates can be used to inject both static and
  dynamic configuration with data populated from environment variables, Consul
  and Vault.

- `vault` <code>([Vault][]: nil)</code> - Specifies the set of Vault policies
  required by the task. This overrides any `vault` block set at the `group` or
  `job` level.

- `volume_mount` <code>([VolumeMount][]: nil)</code> - Specifies where a group
  volume should be mounted.

- `kind` `(string: <varies>)` - Used internally to manage tasks according to
  the value of this field. Initial use case is for Consul Connect.

## Examples

The following examples only show the `task` blocks. Remember that the
`task` block is only valid in the placements listed above.

### Docker container

This example defines a task that starts a Docker container as a service. Docker
is just one of many drivers supported by Nomad. Read more about drivers in the
[Nomad drivers documentation](/nomad/docs/drivers).

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

  resources {
    cpu = 20
  }
}
```

### Metadata and environment variables

This example uses custom metadata and environment variables to pass information
to the task.

```hcl
task "server" {
  driver = "exec"
  config {
    command = "/bin/env"
  }

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

  env {
    MY_KEY = "${meta.my-key}"
  }

  resources {
    cpu = 20
  }
}
```

### Service discovery

This example creates a service in Consul. To read more about service discovery
in Nomad, please see the [Nomad service discovery documentation][service_discovery].

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

  service {
    tags = ["default"]

    check {
      type     = "tcp"
      interval = "10s"
      timeout  = "2s"
    }
  }

  resources {
    cpu = 20
  }
}
```

[artifact]: /nomad/docs/job-specification/artifact 'Nomad artifact Job Specification'
[consul]: https://www.consul.io/ 'Consul by HashiCorp'
[consul_jobspec]: /nomad/docs/job-specification/consul
[constraint]: /nomad/docs/job-specification/constraint 'Nomad constraint Job Specification'
[affinity]: /nomad/docs/job-specification/affinity 'Nomad affinity Job Specification'
[dispatchpayload]: /nomad/docs/job-specification/dispatch_payload 'Nomad dispatch_payload Job Specification'
[env]: /nomad/docs/job-specification/env 'Nomad env Job Specification'
[Identity]: /nomad/docs/job-specification/identity 'Nomad identity Job Specification'
[meta]: /nomad/docs/job-specification/meta 'Nomad meta Job Specification'
[resources]: /nomad/docs/job-specification/resources 'Nomad resources Job Specification'
[lifecycle]: /nomad/docs/job-specification/lifecycle 'Nomad lifecycle Job Specification'
[logs]: /nomad/docs/job-specification/logs 'Nomad logs Job Specification'
[service]: /nomad/docs/job-specification/service 'Nomad service Job Specification'
[vault]: /nomad/docs/job-specification/vault 'Nomad vault Job Specification'
[volumemount]: /nomad/docs/job-specification/volume_mount 'Nomad volume_mount Job Specification'
[exec]: /nomad/docs/drivers/exec 'Nomad exec Driver'
[raw_exec]: /nomad/docs/drivers/raw_exec 'Nomad raw_exec Driver'
[java]: /nomad/docs/drivers/java 'Nomad Java Driver'
[docker]: /nomad/docs/drivers/docker 'Nomad Docker Driver'
[rkt]: /nomad/plugins/drivers/community/rkt 'Nomad rkt Driver'
[service_discovery]: /nomad/docs/integrations/consul-integration#service-discovery 'Nomad Service Discovery'
[template]: /nomad/docs/job-specification/template 'Nomad template Job Specification'
[user_drivers]: /nomad/docs/configuration/client#user-checked_drivers
[user_denylist]: /nomad/docs/configuration/client#user-denylist
[max_kill]: /nomad/docs/configuration/client#max_kill_timeout
[kill_signal]: /nomad/docs/job-specification/task#kill_signal
[Workload Identity]: /nomad/docs/concepts/workload-identity 'Nomad Workload Identity'
[service]: /nomad/docs/install/windows-service