docs: clarify relationship between max_parallel and canary for system jobs (#27075)

Co-authored-by: Tim Gross <[email protected]>
Co-authored-by: Aimee Ukasick <[email protected]>

Author: 3 people

website/content/docs/job-specification/update.mdx

@@ -41,10 +41,18 @@ job "docs" {
 
 ## 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` `(int: 1)` - Specifies the number of allocations within a task
+  group that can be destructively updated at the same time. The task groups themselves are
+  updated in parallel. In-place updates are performed all at once.
 
-  - `max_parallel = 0` - Specifies that the allocation should use forced updates instead of deployments
+  - `max_parallel = 0` - Specifies that the allocation should use forced updates
+    instead of deployments
+
+  ~> **Note:** System jobs only support one allocation per node. When `canary`
+  is set, system job updates make up to `max_parallel` destructive updates *or*
+  destructively update enough allocations to place on `canary` percent of
+  feasible nodes, whichever is lower. You should adjust the `max_parallel` value
+  to allow deploying all desired canaries.
 
 - `health_check` `(string: "checks")` - Specifies the mechanism in which
   allocations health is determined. The potential values are:
@@ -101,11 +109,20 @@ job "docs" {
   remaining allocations at a rate of `max_parallel`. Canary deployments cannot
   be used with volumes when `per_alloc = true`.
 
-  In system jobs, the `canary` setting indicates the percentage of eligible nodes to
-  which allocations will be deployed. System jobs do not support more than one allocation
-  per node, so effectively setting `canary` to a positive integer means this percentage of
-  eligible nodes will get a new version of the job. Setting `canary` to 100 updates the job
-  on all nodes. Percentage of nodes is always rounded up to the nearest integer.
+  In system jobs, the `canary` setting indicates the percentage of feasible
+  nodes to which Nomad makes destructive allocation updates. System jobs do
+  not support more than one allocation per node, so effectively setting `canary`
+  to a positive integer means this percentage of feasible nodes gets a new
+  version of the job if the update is destructive. Non-destructive updates
+  ignore the `canary` field. Setting `canary` to 100 updates the job on all
+  nodes. Percentage of nodes is always rounded up to the nearest integer. If
+  `canary` is set, nodes that register during a deployment do not receive
+  placements until after the deployment is promoted.
+
+  ~> **Note:** Updates when `canary` is set make up to `max_parallel`
+  destructive updates *or* destructively update enough allocations to place on
+  `canary` percent of feasible nodes, whichever is lower. You should adjust the
+  `max_parallel` value to allow deploying all desired canaries.
 
 - `stagger` `(string: "30s")` - Specifies the delay between each set of
   [`max_parallel`](#max_parallel) updates when updating system jobs. This