github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/job-specification/index.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: Job Specification
     4  description: Learn about the Job specification used to submit jobs to Nomad.
     5  ---
     6  
     7  # Job Specification
     8  
     9  The Nomad job specification (or "jobspec" for short) defines the schema for
    10  Nomad jobs. Nomad jobs are specified in [HCL][], which aims to strike a balance
    11  between human readable and editable, and machine-friendly.
    12  
    13  The job specification is broken down into smaller pieces, which you will find
    14  expanded in the navigation menu. We recommend getting started at the [job][]
    15  stanza. Alternatively, you can keep reading to see a few examples.
    16  
    17  Nomad HCL is parsed in the command line and sent to Nomad in JSON format via
    18  the HTTP API.
    19  
    20  The general hierarchy for a job is:
    21  
    22  ```text
    23  job
    24    \_ group
    25          \_ task
    26  ```
    27  
    28  Each job file has only a single job, however a job may have multiple groups, and
    29  each group may have multiple tasks. Groups contain a set of tasks that are
    30  co-located on a machine.
    31  
    32  ## Example
    33  
    34  This example shows a sample job file. We tried to keep it as simple as possible,
    35  while still showcasing the power of Nomad. For a more detailed explanation of
    36  any of these fields, please use the navigation to dive deeper.
    37  
    38  ```hcl
    39  # This declares a job named "docs". There can be exactly one
    40  # job declaration per job file.
    41  job "docs" {
    42    # Specify this job should run in the region named "us". Regions
    43    # are defined by the Nomad servers' configuration.
    44    region = "us"
    45  
    46    # Spread the tasks in this job between us-west-1 and us-east-1.
    47    datacenters = ["us-west-1", "us-east-1"]
    48  
    49    # Run this job as a "service" type. Each job type has different
    50    # properties. See the documentation below for more examples.
    51    type = "service"
    52  
    53    # Specify this job to have rolling updates, two-at-a-time, with
    54    # 30 second intervals.
    55    update {
    56      stagger      = "30s"
    57      max_parallel = 2
    58    }
    59  
    60  
    61    # A group defines a series of tasks that should be co-located
    62    # on the same client (host). All tasks within a group will be
    63    # placed on the same host.
    64    group "webs" {
    65      # Specify the number of these tasks we want.
    66      count = 5
    67  
    68      network {
    69        # This requests a dynamic port named "http". This will
    70        # be something like "46283", but we refer to it via the
    71        # label "http".
    72        port "http" {}
    73  
    74        # This requests a static port on 443 on the host. This
    75        # will restrict this task to running once per host, since
    76        # there is only one port 443 on each host.
    77        port "https" {
    78          static = 443
    79        }
    80      }
    81  
    82      # The service block tells Nomad how to register this service
    83      # with Consul for service discovery and monitoring.
    84      service {
    85        # This tells Consul to monitor the service on the port
    86        # labelled "http". Since Nomad allocates high dynamic port
    87        # numbers, we use labels to refer to them.
    88        port = "http"
    89  
    90        check {
    91          type     = "http"
    92          path     = "/health"
    93          interval = "10s"
    94          timeout  = "2s"
    95        }
    96      }
    97  
    98      # Create an individual task (unit of work). This particular
    99      # task utilizes a Docker container to front a web application.
   100      task "frontend" {
   101        # Specify the driver to be "docker". Nomad supports
   102        # multiple drivers.
   103        driver = "docker"
   104  
   105        # Configuration is specific to each driver.
   106        config {
   107          image = "hashicorp/web-frontend"
   108          ports = ["http", "https"]
   109        }
   110  
   111        # It is possible to set environment variables which will be
   112        # available to the task when it runs.
   113        env {
   114          DB_HOST = "db01.example.com"
   115          DB_USER = "web"
   116          DB_PASS = "loremipsum"
   117        }
   118  
   119        # Specify the maximum resources required to run the task,
   120        # include CPU and memory.
   121        resources {
   122          cpu    = 500 # MHz
   123          memory = 128 # MB
   124        }
   125      }
   126    }
   127  }
   128  ```
   129  
   130  Note that starting with Nomad 0.10, the `service` stanza can also be specified at the group level. This
   131  allows job specification authors to create and register services with Consul Connect support. A service
   132  stanza specified at the group level must include a [connect][] stanza, like the following snippet.
   133  
   134  ```hcl
   135  service {
   136         name = "count-api"
   137         port = "9001"
   138  
   139         connect {
   140           sidecar_service {}
   141         }
   142       }
   143  ```
   144  
   145  [hcl]: https://github.com/hashicorp/hcl 'HashiCorp Configuration Language'
   146  [job]: /docs/job-specification/job 'Nomad job Job Specification'
   147  [connect]: /docs/job-specification/connect 'Connect Stanza Specification'