github.com/smintz/nomad@v0.8.3/website/source/docs/job-specification/parameterized.html.md (about)

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