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"