github.com/smintz/nomad@v0.8.3/website/source/docs/job-specification/update.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "update Stanza - Job Specification" 4 sidebar_current: "docs-job-specification-update" 5 description: |- 6 The "update" stanza specifies the group's update strategy. The update strategy 7 is used to control things like rolling upgrades and canary deployments. If 8 omitted, rolling updates and canaries are disabled. 9 --- 10 11 # `update` Stanza 12 13 <table class="table table-bordered table-striped"> 14 <tr> 15 <th width="120">Placement</th> 16 <td> 17 <code>job -> **update**</code> 18 <br> 19 <code>job -> group -> **update**</code> 20 </td> 21 </tr> 22 </table> 23 24 The `update` stanza specifies the group's update strategy. The update strategy 25 is used to control things like rolling upgrades and canary deployments. If 26 omitted, rolling updates and canaries are disabled. If specified at the job 27 level, the configuration will apply to all groups within the job. If multiple 28 `update` stanzas are specified, they are merged with the group stanza taking the 29 highest precedence and then the job. 30 31 ```hcl 32 job "docs" { 33 update { 34 max_parallel = 3 35 health_check = "checks" 36 min_healthy_time = "10s" 37 healthy_deadline = "10m" 38 auto_revert = true 39 canary = 1 40 stagger = "30s" 41 } 42 } 43 ``` 44 45 ~> For `system` jobs, only `max_parallel` and `stagger` are enforced. The job is 46 updated at a rate of `max_parallel`, waiting `stagger` duration before the next 47 set of updates. The `system` scheduler will be updated to support the new 48 `update` stanza in a future release. 49 50 ## `update` Parameters 51 52 - `max_parallel` `(int: 0)` - Specifies the number of task groups that can be 53 updated at the same time. 54 55 - `health_check` `(string: "checks")` - Specifies the mechanism in which 56 allocations health is determined. The potential values are: 57 58 - "checks" - Specifies that the allocation should be considered healthy when 59 all of its tasks are running and their associated [checks][] are healthy, 60 and unhealthy if any of the tasks fail or not all checks become healthy. 61 This is a superset of "task_states" mode. 62 63 - "task_states" - Specifies that the allocation should be considered healthy when 64 all its tasks are running and unhealthy if tasks fail. 65 66 - "manual" - Specifies that Nomad should not automatically determine health 67 and that the operator will specify allocation health using the [HTTP 68 API](/api/deployments.html#set-allocation-health-in-deployment). 69 70 - `min_healthy_time` `(string: "10s")` - Specifies the minimum time the 71 allocation must be in the healthy state before it is marked as healthy and 72 unblocks further allocations from being updated. This is specified using a 73 label suffix like "30s" or "15m". 74 75 - `healthy_deadline` `(string: "5m")` - Specifies the deadline in which the 76 allocation must be marked as healthy after which the allocation is 77 automatically transitioned to unhealthy. This is specified using a label 78 suffix like "2m" or "1h". 79 80 - `auto_revert` `(bool: false)` - Specifies if the job should auto-revert to the 81 last stable job on deployment failure. A job is marked as stable if all the 82 allocations as part of its deployment were marked healthy. 83 84 - `canary` `(int: 0)` - Specifies that changes to the job that would result in 85 destructive updates should create the specified number of canaries without 86 stopping any previous allocations. Once the operator determines the canaries 87 are healthy, they can be promoted which unblocks a rolling update of the 88 remaining allocations at a rate of `max_parallel`. 89 90 - `stagger` `(string: "30s")` - Specifies the delay between migrating 91 allocations off nodes marked for draining. This is specified using a label 92 suffix like "30s" or "1h". 93 94 ## `update` Examples 95 96 The following examples only show the `update` stanzas. Remember that the 97 `update` stanza is only valid in the placements listed above. 98 99 ### Parallel Upgrades Based on Checks 100 101 This example performs 3 upgrades at a time and requires the allocations be 102 healthy for a minimum of 30 seconds before continuing the rolling upgrade. Each 103 allocation is given at most 2 minutes to determine its health before it is 104 automatically marked unhealthy and the deployment is failed. 105 106 ```hcl 107 update { 108 max_parallel = 3 109 min_healthy_time = "30s" 110 healthy_deadline = "2m" 111 } 112 ``` 113 114 ### Parallel Upgrades Based on Task State 115 116 This example is the same as the last but only requires the tasks to be healthy 117 and does not require registered service checks to be healthy. 118 119 ```hcl 120 update { 121 max_parallel = 3 122 min_healthy_time = "30s" 123 healthy_deadline = "2m" 124 health_check = "task_states" 125 } 126 ``` 127 128 ### Canary Upgrades 129 130 This example creates a canary allocation when the job is updated. The canary is 131 created without stopping any previous allocations from the job and allows 132 operators to determine if the new version of the job should be rolled out. 133 134 ```hcl 135 update { 136 canary = 1 137 max_parallel = 3 138 } 139 ``` 140 141 Once the operator has determined the new job should be deployed, the deployment 142 can be promoted and a rolling update will occur performing 3 updates at a time 143 until the remainder of the groups allocations have been rolled to the new 144 version. 145 146 ```text 147 # Promote the canaries for the job. 148 $ nomad job promote <job-id> 149 ``` 150 151 ### Blue/Green Upgrades 152 153 By setting the canary count equal to that of the task group, blue/green 154 deployments can be achieved. When a new version of the job is submitted, instead 155 of doing a rolling upgrade of the existing allocations, the new version of the 156 group is deployed along side the existing set. While this duplicates the 157 resources required during the upgrade process, it allows very safe deployments 158 as the original version of the group is untouched. 159 160 ```hcl 161 group "api-server" { 162 count = 3 163 164 update { 165 canary = 3 166 max_parallel = 3 167 } 168 ... 169 } 170 ``` 171 172 Once the operator is satisfied that the new version of the group is stable, the 173 group can be promoted which will result in all allocations for the old versions 174 of the group to be shutdown. This completes the upgrade from blue to green, or 175 old to new version. 176 177 ```text 178 # Promote the canaries for the job. 179 $ nomad job promote <job-id> 180 ``` 181 182 ### Serial Upgrades 183 184 This example uses a serial upgrade strategy, meaning exactly one task group will 185 be updated at a time. The allocation must be healthy for the default 186 `min_healthy_time` of 10 seconds. 187 188 ```hcl 189 update { 190 max_parallel = 1 191 } 192 ``` 193 194 ### Upgrade Stanza Inheritance 195 196 This example shows how inheritance can simplify the job when there are multiple 197 task groups. 198 199 ```hcl 200 job "example" { 201 ... 202 203 update { 204 max_parallel = 2 205 health_check = "task_states" 206 healthy_deadline = "10m" 207 } 208 209 group "one" { 210 ... 211 212 update { 213 canary = 1 214 } 215 } 216 217 group "two" { 218 ... 219 220 update { 221 min_healthy_time = "3m" 222 } 223 } 224 } 225 ``` 226 227 By placing the shared parameters in the job's update stanza, each groups update 228 stanza may be kept to a minimum. The merged update stanzas for each group 229 becomes: 230 231 ```hcl 232 group "one" { 233 update { 234 canary = 1 235 max_parallel = 2 236 health_check = "task_states" 237 healthy_deadline = "10m" 238 } 239 } 240 241 group "two" { 242 update { 243 min_healthy_time = "3m" 244 max_parallel = 2 245 health_check = "task_states" 246 healthy_deadline = "10m" 247 } 248 } 249 ``` 250 251 [checks]: /docs/job-specification/service.html#check-parameters "Nomad check Job Specification"