• Overview
    • Batch Processing Workloads
    • Edge Workload Management
    • Non-Containerized Application Orchestration
    • Simple Container Orchestration
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Plugins
  • Tools
  • Community
GitHub—Stars on GitHub
Download
    • v1.3.x (latest)
    • v1.2.x
    • v1.1.x
    • v1.0.x
    • v0.12.x
    • v0.11.x
    • Overview
    • Quickstart
      • Overview
      • Requirements
      • Reference Architecture
      • Deployment Guide
    • Windows Service
    • Overview
    • Specific Version Details
    • Overview
    • Consul
    • Consul Service Mesh
    • Vault Integration

    • Overview
    • Architecture
      • Overview
      • Base
      • Task Drivers
      • Devices
      • Storage
      • Overview
      • Internals
      • Preemption
    • Consensus Protocol
    • Filesystem
    • Gossip Protocol
    • Security Model
    • Overview
    • acl
    • audit
    • autopilot
    • client
    • consul
    • plugin
    • sentinel
    • search
    • server
    • server_join
    • telemetry
    • tls
    • ui
    • vault
    • Overview
      • Overview
      • bootstrap
      • policy apply
      • policy delete
      • policy info
      • policy list
      • token create
      • token delete
      • token info
      • token list
      • token self
      • token update
    • agent
    • agent-info
      • Overview
      • exec
      • fs
      • logs
      • restart
      • signal
      • status
      • stop
      • Overview
      • validate
      • Overview
      • fail
      • list
      • pause
      • promote
      • resume
      • status
      • unblock
      • Overview
      • list
      • status
      • Overview
      • allocs
      • deployments
      • dispatch
      • eval
      • history
      • init
      • inspect
      • plan
      • periodic force
      • promote
      • revert
      • run
      • scale
      • scaling-events
      • status
      • stop
      • validate
      • Overview
      • get
    • monitor
      • Overview
      • apply
      • delete
      • inspect
      • list
      • status
      • Overview
      • config
      • drain
      • eligibility
      • status
      • Overview
      • api
      • autopilot get-config
      • autopilot set-config
      • debug
      • keygen
      • keyring
      • metrics
      • raft info
      • raft list-peers
      • raft logs
      • raft remove-peer
      • raft state
      • snapshot agent
      • snapshot inspect
      • snapshot restore
      • snapshot save
      • snapshot state
      • Overview
      • status
      • Overview
      • apply
      • delete
      • init
      • inspect
      • list
      • status
      • Overview
      • apply
      • dismiss
      • info
      • list
      • Overview
      • policy info
      • policy list
      • Overview
      • apply
      • delete
      • list
      • read
      • Overview
      • force-leave
      • join
      • members
      • Overview
      • service delete
      • service info
      • service list
    • status
      • Overview
      • gc
      • reconcile summaries
    • ui
    • version
      • Overview
      • create
      • delete
      • deregister
      • detach
      • init
      • register
      • snapshot create
      • snapshot delete
      • snapshot list
      • status

    • Overview
      • Overview
      • Expressions
        • Overview
          • chunklist
          • coalesce
          • coalescelist
          • compact
          • concat
          • contains
          • distinct
          • element
          • flatten
          • index
          • keys
          • length
          • lookup
          • merge
          • range
          • reverse
          • setintersection
          • setproduct
          • setunion
          • slice
          • sort
          • values
          • zipmap
          • can
          • convert
          • try
          • bcrypt
          • md5
          • rsadecrypt
          • sha1
          • sha256
          • sha512
          • formatdate
          • timeadd
          • base64decode
          • base64encode
          • csvdecode
          • jsondecode
          • jsonencode
          • urlencode
          • yamldecode
          • yamlencode
          • abspath
          • basename
          • dirname
          • file
          • fileexists
          • fileset
          • pathexpand
          • cidrhost
          • cidrnetmask
          • cidrsubnet
          • cidrsubnets
          • abs
          • ceil
          • floor
          • log
          • max
          • min
          • parseint
          • pow
          • signum
          • chomp
          • format
          • formatlist
          • indent
          • join
          • lower
          • regex_replace
          • replace
          • split
          • strrev
          • substr
          • title
          • trim
          • trimprefix
          • trimspace
          • trimsuffix
          • upper
          • uuidv4
          • uuidv5
      • Locals
      • Syntax
      • Variables
    • artifact
    • affinity
    • check_restart
    • connect
    • constraint
    • csi_plugin
    • device
    • dispatch_payload
    • env
    • ephemeral_disk
    • expose
    • gateway
    • group
    • job
    • lifecycle
    • logs
    • meta
    • migrate
    • multiregion
    • network
    • parameterized
    • periodic
    • proxy
    • reschedule
    • resources
    • restart
    • scaling
    • service
    • sidecar_service
    • sidecar_task
    • spread
    • task
    • template
    • update
    • upstreams
    • vault
    • volume
    • volume_mount
    • Overview
      • Overview
      • capability
      • mount_options
      • topology_request
    • Overview
    • Docker
    • Isolated Fork/Exec
    • Java
    • Podman
    • QEMU
    • Raw Fork/Exec
      • Overview
      • containerd
      • Firecracker driver
      • Jailtask driver
      • Lightrun
      • LXC
      • Pot
      • Rkt Deprecated
      • Rookout
      • Singularity
      • systemd-nspawn
      • Windows IIS
      • Overview
      • ECS
    • Overview
      • Overview
      • Nvidia
      • USB Beta
  • Schedulers
    • Overview
    • Runtime Environment
    • Variable Interpolation
    • Overview
      • Overview
      • apm
      • dynamic_application_sizing
      • http
      • nomad
      • policy
      • policy_eval
      • source
      • strategy
      • target
      • telemetry
    • API
    • CLI
    • Policy
    • Telemetry
      • Overview
        • Overview
        • Datadog
        • Nomad API
        • Prometheus
        • Overview
        • Dynamic Application Sizing Average
        • Dynamic Application Sizing Max
        • Dynamic Application Sizing Percentile
        • Fixed Value
        • Pass-Through
        • Target Value
        • Threshold
        • Overview
        • Amazon Web Services Autoscaling Group
        • Azure Virtual Machine Scale Set
        • Dynamic Application Sizing
        • Google Cloud Engine Managed Instance Group
        • Nomad Task Group
      • Community
      • Overview
      • Checks
      • Node Selector Strategy
        • Overview
        • Base
        • APM
        • Strategy
        • Target
    • Overview
    • Operating Nomad Agents
    • Monitoring Nomad
    • Metrics Reference
    • Cluster Management
    • Transport Security
    • Access Control

    • Overview
    • Alternative to Kubernetes
    • Supplement to Kubernetes
  • Nomad Ecosystem
  • Nomad Partnerships
  • Who Uses Nomad
    • Overview
      • Overview
      • FAQ
  • FAQ
Type '/' to Search

»job Stanza

Placementjob

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 one or more task groups, which are themselves collections of one or more tasks. Job names are unique per region or namespace.

job "docs" {
  constraint {
    # ...
  }

  datacenters = ["us-east-1"]

  group "example" {
    # ...
  }

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

  parameterized {
    # ...
  }

  periodic {
    # ...
  }

  priority = 100

  region = "north-america"

  task "docs" {
    # ...
  }

  update {
    # ...
  }
}
job "docs" {
  constraint {
    # ...
  }

  datacenters = ["us-east-1"]

  group "example" {
    # ...
  }

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

  parameterized {
    # ...
  }

  periodic {
    # ...
  }

  priority = 100

  region = "north-america"

  task "docs" {
    # ...
  }

  update {
    # ...
  }
}

»job Parameters

  • all_at_once (bool: false) - Controls whether the scheduler can make partial placements if optimistic scheduling resulted in an oversubscribed node. This does not control whether all allocations for the job, where all would be the desired count for each task group, must be placed atomically. This should only be used for special circumstances.

  • constraint (Constraint: nil) - This can be provided multiple times to define additional constraints. See the Nomad constraint reference for more details.

  • affinity (Affinity: nil) - This can be provided multiple times to define preferred placement criteria. See the Nomad affinity reference for more details.

  • spread (Spread: nil) - This can be provided multiple times to define criteria for spreading allocations across a node attribute or metadata. See the Nomad spread reference 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 (Group: <required>) - 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 (Meta: nil) - Specifies a key-value map that annotates with user-defined metadata.

  • name (string: <optional>) - Specifies a name for the job, which otherwise defaults to the job ID.

  • migrate (Migrate: nil) - Specifies the groups strategy for migrating off of draining nodes. If omitted, a default migration strategy is applied. Only service jobs with a count greater than 1 support migrate stanzas.

  • namespace (string: "default") - The namespace in which to execute the job. Prior to Nomad 1.0 namespaces were Enterprise-only.

  • parameterized (Parameterized: nil) - Specifies the job as a parameterized job such that it can be dispatched against.

  • periodic (Periodic: nil) - 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.

  • reschedule (Reschedule: nil) - Allows to specify a rescheduling strategy. Nomad will then attempt to schedule the task on another node if any of its allocation statuses become "failed".

  • type (string: "service") - Specifies the Nomad scheduler to use. Nomad provides the service, system, batch, and sysbatch (new in Nomad 1.2) schedulers.

  • update (Update: nil) - Specifies the task's update strategy. When omitted, a default update strategy is applied.

  • vault (Vault: nil) - Specifies the set of Vault policies required by all tasks in this job.

  • vault_token (string: "") - Specifies the Vault token that proves the submitter of the job has access to the specified policies in the vault stanza. This field is only used to transfer the token and is not stored after job submission.

    It is strongly discouraged to place the token as a configuration parameter like this, since the token could be checked into source control accidentally. Users should set the VAULT_TOKEN environment variable when running the job instead.

  • consul_token (string: "") - Specifies the Consul token that proves the submitter of the job has access to the Service Identity policies associated with the job's Consul Connect enabled services. This field is only used to transfer the token and is not stored after job submission.

    It is strongly discouraged to place the token as a configuration parameter like this, since the token could be checked into source control accidentally. Users should set the CONSUL_HTTP_TOKEN environment variable when running the job instead.

»job Examples

The following examples only show the job stanzas. Remember that the job stanza is only valid in the placements listed above.

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

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

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

      resources {
        memory = 128
      }
    }
  }
}
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 on 10 Nomad clients in the fleet, restricting the eligible nodes to Linux machines.

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

  type = "batch"

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

  group "example" {
    count = 10
    task "uptime" {
      driver = "exec"
      config {
        command = "uptime"
      }
    }
  }
}
job "docs" {
  datacenters = ["default"]

  type = "batch"

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

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

»Consuming Secrets

This example shows a job which retrieves secrets from Vault and writes those secrets to a file on disk, which the application then consumes. Nomad handles all interactions with Vault.

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

  group "example" {
    task "cat" {
      driver = "exec"

      config {
        command = "cat"
        args    = ["local/secrets.txt"]
      }

      template {
        data        = "{{ secret \"secret/data\" }}"
        destination = "local/secrets.txt"
      }

      vault {
        policies = ["secret-readonly"]
      }
    }
  }
}
job "docs" {
  datacenters = ["default"]

  group "example" {
    task "cat" {
      driver = "exec"

      config {
        command = "cat"
        args    = ["local/secrets.txt"]
      }

      template {
        data        = "{{ secret \"secret/data\" }}"
        destination = "local/secrets.txt"
      }

      vault {
        policies = ["secret-readonly"]
      }
    }
  }
}

When submitting this job, you would run:

$ VAULT_TOKEN="..." nomad job run example.nomad
$ VAULT_TOKEN="..." nomad job run example.nomad
github logoEdit this page
DocsAPIResourcesPrivacySecurityPress KitConsent Manager