github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/docs/job-specification/parameterized.mdx (about)

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