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

     1  ---
     2  layout: docs
     3  page_title: parameterized Stanza - Job Specification
     4  description: |-
     5    A parameterized job is used to encapsulate a set of work that can be carried
     6    out on various inputs much like a function definition. When the
     7    `parameterized` stanza is added to a job, the job acts as a function to the
     8    cluster as a whole.
     9  ---
    10  
    11  # `parameterized` Stanza
    12  
    13  <Placement groups={['job', 'parameterized']} />
    14  
    15  A parameterized job is used to encapsulate a set of work that can be carried out
    16  on various inputs much like a function definition. When the `parameterized`
    17  stanza is added to a job, the job acts as a function to the cluster as a whole.
    18  
    19  The `parameterized` stanza allows job operators to configure a job that carries
    20  out a particular action, define its resource requirements and configure how
    21  inputs and configuration are retrieved by the tasks within the job.
    22  
    23  To invoke a parameterized job, [`nomad job dispatch`][dispatch command] or the equivalent HTTP APIs are
    24  used. When dispatching against a parameterized job, an opaque payload and
    25  metadata may be injected into the job. These inputs to the parameterized job act
    26  like arguments to a function. The job consumes them to change its behavior,
    27  without exposing the implementation details to the caller.
    28  
    29  To that end, tasks within the job can add a
    30  [`dispatch_payload`][dispatch_payload] stanza that
    31  defines where on the filesystem this payload gets written to. An example payload
    32  would be a task's JSON configuration.
    33  
    34  Further, certain metadata may be marked as required when dispatching a job so it
    35  can be used to inject configuration directly into a task's arguments using
    36  [interpolation]. An example of this would be to require a run ID key that
    37  could be used to lookup the work the job is suppose to do from a management
    38  service or database.
    39  
    40  Each time a job is dispatched, a unique job ID is generated. This
    41  allows a caller to track the status of the job, much like a future or
    42  promise in some programming languages. The dispatched job cannot be
    43  updated after dispatching; to update the job definition you need to
    44  update the parent job.
    45  
    46  ```hcl
    47  job "docs" {
    48    parameterized {
    49      payload       = "required"
    50      meta_required = ["dispatcher_email"]
    51      meta_optional = ["pager_email"]
    52    }
    53  }
    54  ```
    55  
    56  See the [multiregion] documentation for additional considerations when
    57  dispatching parameterized jobs.
    58  
    59  ## `parameterized` Requirements
    60  
    61  - The job's [scheduler type][batch-type] must be `batch` or `sysbatch`.
    62  
    63  ## `parameterized` Parameters
    64  
    65  - `meta_optional` `(array<string>: nil)` - Specifies the set of metadata keys that
    66    may be provided when dispatching against the job.
    67  
    68  - `meta_required` `(array<string>: nil)` - Specifies the set of metadata keys that
    69    must be provided when dispatching against the job.
    70  
    71  - `payload` `(string: "optional")` - Specifies the requirement of providing a
    72    payload when dispatching against the parameterized job. The **maximum size of a
    73    `payload` is 16 KiB**. The options for this
    74    field are:
    75  
    76    - `"optional"` - A payload is optional when dispatching against the job.
    77  
    78    - `"required"` - A payload must be provided when dispatching against the job.
    79  
    80    - `"forbidden"` - A payload is forbidden when dispatching against the job.
    81  
    82  ## `parameterized` Examples
    83  
    84  The following examples show non-runnable example parameterized jobs:
    85  
    86  ### Required Inputs
    87  
    88  This example shows a parameterized job that requires both a payload and
    89  metadata:
    90  
    91  ```hcl
    92  job "video-encode" {
    93    # ...
    94  
    95    type = "batch"
    96  
    97    parameterized {
    98      payload       = "required"
    99      meta_required = ["dispatcher_email"]
   100    }
   101  
   102    group "encode" {
   103      # ...
   104  
   105      task "ffmpeg" {
   106        driver = "exec"
   107  
   108        config {
   109          command = "ffmpeg-wrapper"
   110  
   111          # When dispatched, the payload is written to a file that is then read by
   112          # the created task upon startup
   113          args = ["-config=${NOMAD_TASK_DIR}/config.json"]
   114        }
   115  
   116        dispatch_payload {
   117          file = "config.json"
   118        }
   119      }
   120    }
   121  }
   122  ```
   123  
   124  ### Metadata Interpolation
   125  
   126  ```hcl
   127  job "email-blast" {
   128    # ...
   129  
   130    type = "batch"
   131  
   132    parameterized {
   133      payload       = "forbidden"
   134      meta_required = ["CAMPAIGN_ID"]
   135    }
   136  
   137    group "emails" {
   138      # ...
   139  
   140      task "emailer" {
   141        driver = "exec"
   142  
   143        config {
   144          command = "emailer"
   145  
   146          # The campaign ID is interpolated and injected into the task's
   147          # arguments
   148          args = ["-campaign=${NOMAD_META_CAMPAIGN_ID}"]
   149        }
   150      }
   151    }
   152  }
   153  ```
   154  
   155  [batch-type]: /docs/job-specification/job#type 'Batch scheduler type'
   156  [dispatch command]: /docs/commands/job/dispatch 'Nomad Job Dispatch Command'
   157  [resources]: /docs/job-specification/resources 'Nomad resources Job Specification'
   158  [interpolation]: /docs/runtime/interpolation 'Nomad Runtime Interpolation'
   159  [dispatch_payload]: /docs/job-specification/dispatch_payload 'Nomad dispatch_payload Job Specification'
   160  [multiregion]: /docs/job-specification/multiregion#parameterized-dispatch