diff --git a/website/source/docs/job-specification/update.html.md b/website/source/docs/job-specification/update.html.md index 28e740747..8ffd5ba4d 100644 --- a/website/source/docs/job-specification/update.html.md +++ b/website/source/docs/job-specification/update.html.md @@ -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: |- job -> **update** + + job -> group -> **update** + -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"