mirror of
https://github.com/kemko/nomad.git
synced 2026-01-06 18:35:44 +03:00
Merge pull request #2806 from hashicorp/d-update-stanza
Document new upgrade stanza
This commit is contained in:
Alex Dadgar
@@ -3,9 +3,9 @@ layout: "docs"
|
||||
page_title: "update Stanza - Job Specification"
|
||||
sidebar_current: "docs-job-specification-update"
|
||||
description: |-
|
||||
The "update" stanza specifies the job update strategy. The update strategy is
|
||||
used to control things like rolling upgrades. If omitted, rolling updates are
|
||||
disabled.
|
||||
The "update" stanza specifies the group's update strategy. The update strategy
|
||||
is used to control things like rolling upgrades and canary deployments. If
|
||||
omitted, rolling updates and canaries are disabled.
|
||||
---
|
||||
|
||||
# `update` Stanza
|
||||
@@ -16,55 +16,189 @@ description: |-
|
||||
<td>
|
||||
<code>job -> **update**</code>
|
||||
</td>
|
||||
<td>
|
||||
<code>job -> group -> **update**</code>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
The `update` stanza specifies the job update strategy. The update strategy is
|
||||
used to control things like rolling upgrades. If omitted, rolling updates are
|
||||
disabled.
|
||||
The `update` stanza specifies the group's update strategy. The update strategy
|
||||
is used to control things like rolling upgrades and canary deployments. If
|
||||
omitted, rolling updates and canaries are disabled. If specified at the job
|
||||
level, the configuration will apply to all groups within the job. If multiple
|
||||
`update` stanzas are specified, they are merged with the group stanza taking the
|
||||
highest precedence and then the job.
|
||||
|
||||
```hcl
|
||||
job "docs" {
|
||||
update {
|
||||
max_parallel = 3
|
||||
stagger = "30s"
|
||||
max_parallel = 3
|
||||
health_check = "checks"
|
||||
min_healthy_time = "10s"
|
||||
healthy_deadline = "10m"
|
||||
auto_revert = true
|
||||
canary = 1
|
||||
stagger = "30s"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## `update` Parameters
|
||||
|
||||
- `max_parallel` `(int: 0)` - Specifies the number of task groups that can be
|
||||
updated at the same time.
|
||||
|
||||
- `stagger` `(string: "0ms")` - Specifies the delay between sets of updates.
|
||||
This is specified using a label suffix like "30s" or "1h".
|
||||
- `health_check` `(string: "checks")` - Specifies the mechanism in which
|
||||
allocations health is determined. The potential values are:
|
||||
|
||||
- "checks" - Specifies that the allocation should be considered healthy when
|
||||
all of its tasks are running and their associated [checks][] are healthy,
|
||||
and unhealthy if any of the tasks fail or not all checks become healthy.
|
||||
This is a superset of "task_states" mode.
|
||||
|
||||
- "task_states" - Specifies that the allocation should be considered healthy when
|
||||
all its tasks are running and unhealthy if tasks fail.
|
||||
|
||||
- "manual" - Specifies that Nomad should not automatically determine health
|
||||
and that the operator will specify allocation health using the [HTTP
|
||||
API](/api/deployments.html#set-allocation-health-in-deployment).
|
||||
|
||||
- `min_healthy_time` `(string: "10s")` - Specifies the minimum time the
|
||||
allocation must be in the healthy state before it is marked as healthy and
|
||||
unblocks further allocations from being updated. This is specified using a
|
||||
label suffix like "30s" or "15m".
|
||||
|
||||
- `healthy_deadline` `(string: "5m")` - Specifies the deadline in which the
|
||||
allocation must be marked as heatlhy after which the allocation is
|
||||
automatically transistioned to unhealthy. This is specified using a label
|
||||
suffix like "2m" or "1h".
|
||||
|
||||
- `auto_revert` `(bool: false)` - Specifies if the job should auto-revert to the
|
||||
last stable job on deployment failure. A job is marked as stable if all the
|
||||
allocations as part of its deployment were marked healthy.
|
||||
|
||||
- `stagger` `(string: "30s")` - Specifies the delay between migrating
|
||||
allocations off nodes marked for draining. This is specified using a label
|
||||
suffix like "30s" or "1h".
|
||||
|
||||
## `update` Examples
|
||||
|
||||
The following examples only show the `update` stanzas. Remember that the
|
||||
`update` stanza is only valid in the placements listed above.
|
||||
|
||||
### Parallel Upgrades Based on Checks
|
||||
|
||||
This example performs 3 upgrades at a time and requires the allocations be
|
||||
healthy for a minimum of 30 seconds before continuing the rolling upgrade. Each
|
||||
allocation is given at most 2 minutes to determine its health before it is
|
||||
automatically marked unhealthy and the deployment is failed.
|
||||
|
||||
```hcl
|
||||
update {
|
||||
max_parallel = 3
|
||||
min_healthy_time = "30s"
|
||||
healthy_deadline = "2m"
|
||||
}
|
||||
```
|
||||
|
||||
### Parallel Upgrades Based on Task State
|
||||
|
||||
This example is the same as the last but only requires the tasks to be healthy
|
||||
and does not require registered service checks to be healthy.
|
||||
|
||||
```hcl
|
||||
update {
|
||||
max_parallel = 3
|
||||
min_healthy_time = "30s"
|
||||
healthy_deadline = "2m"
|
||||
health_check = "task_states"
|
||||
}
|
||||
```
|
||||
|
||||
### Canary Upgrades
|
||||
|
||||
This example creates a canary allocation when the job is updated. The canary is
|
||||
created without stopping any previous allocations from the job and allows
|
||||
operators to determine if the new version of the job should be rolled out. Once
|
||||
the operator has determined the new job should be deployed, the deployment can
|
||||
be promoted and a rolling update will occur performing 3 updates at a time till
|
||||
the remainder of the groups allocations have been rolled to the new version.
|
||||
|
||||
```hcl
|
||||
update {
|
||||
canary = 1
|
||||
max_parallel = 3
|
||||
}
|
||||
```
|
||||
|
||||
### Serial Upgrades
|
||||
|
||||
This example uses a serial upgrade strategy, meaning exactly one task group will
|
||||
be updated at a time, waiting 60 seconds until the next task group is upgraded.
|
||||
be updated at a time. The allocation must be healthy for the default
|
||||
`min_healthy_time` of 10 seconds.
|
||||
|
||||
```hcl
|
||||
update {
|
||||
max_parallel = 1
|
||||
stagger = "60s"
|
||||
}
|
||||
```
|
||||
|
||||
### Parallel Upgrades
|
||||
### Upgrade Stanza Inheritance
|
||||
|
||||
This example performs 10 upgrades at a time, waiting 30 seconds before moving on
|
||||
to the next batch:
|
||||
This example shows how inheritance can simplify the job when there are multiple
|
||||
task groups.
|
||||
|
||||
```hcl
|
||||
update {
|
||||
max_parallel = 10
|
||||
stagger = "30s"
|
||||
job "example" {
|
||||
...
|
||||
|
||||
update {
|
||||
max_parallel = 2
|
||||
health_check = "task_states"
|
||||
healthy_deadline = "10m"
|
||||
}
|
||||
|
||||
group "one" {
|
||||
...
|
||||
|
||||
update {
|
||||
canary = 1
|
||||
}
|
||||
}
|
||||
|
||||
group "two" {
|
||||
...
|
||||
|
||||
update {
|
||||
min_healthy_time = "3m"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
By placing the shared parameters in the job's update stanza, each groups update
|
||||
stanza may be kept to a minimum. The merged update stanzas for each group
|
||||
becomes:
|
||||
|
||||
```hcl
|
||||
group "one" {
|
||||
update {
|
||||
canary = 1
|
||||
max_parallel = 2
|
||||
health_check = "task_states"
|
||||
healthy_deadline = "10m"
|
||||
}
|
||||
}
|
||||
|
||||
group "two" {
|
||||
update {
|
||||
min_healthy_time = "3m"
|
||||
max_parallel = 2
|
||||
health_check = "task_states"
|
||||
healthy_deadline = "10m"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[checks]: /docs/job-specification/service.html#check-parameters "Nomad check Job Specification"
|
||||
|
||||
Reference in New Issue
Block a user