open-nomad/website/content/docs/job-specification/update.mdx
Yorick Gersie 2a5c423ae0
Allow per_alloc to be used with host volumes (#15780)
Disallowing per_alloc for host volumes in some cases makes life of a nomad user much harder.
When we rely on the NOMAD_ALLOC_INDEX for any configuration that needs to be re-used across
restarts we need to make sure allocation placement is consistent. With CSI volumes we can
use the `per_alloc` feature but for some reason this is explicitly disabled for host volumes.

Ensure host volumes understand the concept of per_alloc
2023-01-26 09:14:47 -05:00

276 lines
8.9 KiB
Plaintext

---
layout: docs
page_title: update Stanza - Job Specification
description: |-
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, a default update strategy is applied.
---
# `update` Stanza
<Placement
groups={[
['job', 'update'],
['job', 'group', 'update'],
]}
/>
The `update` stanza specifies the group's update strategy. The update strategy
is used to control things like [rolling upgrades][rolling] and [canary
deployments][canary]. If omitted, a default update strategy is applied. 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
health_check = "checks"
min_healthy_time = "10s"
healthy_deadline = "5m"
progress_deadline = "10m"
auto_revert = true
auto_promote = true
canary = 1
stagger = "30s"
}
}
```
~> For `system` jobs, only [`max_parallel`](#max_parallel) and
[`stagger`](#stagger) are enforced. The job is updated at a rate of
`max_parallel`, waiting `stagger` duration before the next set of updates.
The `system` scheduler will be updated to support the new `update` stanza in
a future release.
## `update` Parameters
- `max_parallel` `(int: 1)` - Specifies the number of allocations within a task group that can be
updated at the same time. The task groups themselves are updated in parallel.
- `max_parallel = 0` - Specifies that the allocation should use forced updates instead of deployments
- `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](/nomad/api-docs/deployments#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 healthy after which the allocation is
automatically transitioned to unhealthy. This is specified using a label suffix
like "2m" or "1h". If [`progress_deadline`](#progress_deadline) is non-zero, it
must be greater than `healthy_deadline`. Otherwise the `progress_deadline` may
fail a deployment before an allocation reaches its `healthy_deadline`.
- `progress_deadline` `(string: "10m")` - Specifies the deadline in which an
allocation must be marked as healthy. The deadline begins when the first
allocation for the deployment is created and is reset whenever an allocation
as part of the deployment transitions to a healthy state or when a
deployment is manually promoted. If no allocation transitions to the healthy
state before the progress deadline, the deployment is marked as failed. If
the `progress_deadline` is set to `0`, the first allocation to be marked as
unhealthy causes the deployment to fail. 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.
- `auto_promote` `(bool: false)` - Specifies if the job should auto-promote to
the canary version when all canaries become healthy during a
deployment. Defaults to false which means canaries must be manually updated
with the `nomad deployment promote` command. If a job has multiple task
groups, all must be set to `auto_promote = true` in order for the deployment
to be promoted automatically.
- `canary` `(int: 0)` - Specifies that changes to the job that would result in
destructive updates should create the specified number of canaries without
stopping any previous allocations. Once the operator determines the canaries
are healthy, they can be promoted which unblocks a rolling update of the
remaining allocations at a rate of `max_parallel`. Canary deployments cannot
be used with volumes when `per_alloc = true`.
- `stagger` `(string: "30s")` - Specifies the delay between each set of
[`max_parallel`](#max_parallel) updates when updating system jobs. This
setting no longer applies to service jobs which use
[deployments.][strategies]
## `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.
```hcl
update {
canary = 1
max_parallel = 3
}
```
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
until the remainder of the groups allocations have been rolled to the new
version.
```text
# Promote the canaries for the job.
$ nomad job promote <job-id>
```
### Blue/Green Upgrades
By setting the canary count equal to that of the task group, blue/green
deployments can be achieved. When a new version of the job is submitted, instead
of doing a rolling upgrade of the existing allocations, the new version of the
group is deployed along side the existing set. While this duplicates the
resources required during the upgrade process, it allows very safe deployments
as the original version of the group is untouched.
```hcl
group "api-server" {
count = 3
update {
canary = 3
max_parallel = 3
}
...
}
```
Once the operator is satisfied that the new version of the group is stable, the
group can be promoted which will result in all allocations for the old versions
of the group to be shutdown. This completes the upgrade from blue to green, or
old to new version.
```text
# Promote the canaries for the job.
$ nomad job promote <job-id>
```
### Serial Upgrades
This example uses a serial upgrade strategy, meaning exactly one task group will
be updated at a time. The allocation must be healthy for the default
`min_healthy_time` of 10 seconds.
```hcl
update {
max_parallel = 1
}
```
### Update Stanza Inheritance
This example shows how inheritance can simplify the job when there are multiple
task groups.
```hcl
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"
}
}
```
[canary]: /nomad/tutorials/job-updates/job-blue-green-and-canary-deployments 'Nomad Canary Deployments'
[checks]: /nomad/docs/job-specification/service#check-parameters 'Nomad check Job Specification'
[rolling]: /nomad/tutorials/job-updates/job-rolling-update 'Nomad Rolling Upgrades'
[strategies]: /nomad/tutorials/job-updates 'Nomad Update Strategies'