docs for unique volumes per alloc

client/allocrunner/csi_hook.go

@@ -94,6 +94,7 @@ func (c *csiHook) Postrun() error {
 
 		source := pair.request.Source
 		if pair.request.PerAlloc {
+			// NOTE: PerAlloc can't be set if we have canaries
 			source = source + structs.AllocSuffix(c.alloc.Name)
 		}
 

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

@@ -105,7 +105,8 @@ a future release.
   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`.
+  remaining allocations at a rate of `max_parallel`. Canary deployments cannot
+  be used with CSI 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

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

@@ -49,6 +49,13 @@ the [volume_mount][volume_mount] stanza in the `task` configuration.
   name of the host volume. When using `csi` volumes, this should match
   the ID of the registered volume.
 
+- `per_alloc` `(bool: false)` - Specifies that the `source` of the volume
+  should have the suffix `[n]`, where `n` is the allocation index. This allows
+  mounting a unique volume per allocation, so long as the volume's source is
+  named appropriately. For example, with the source `myvolume` and `per_alloc
+  = true`, the allocation named `myjob.mygroup.mytask[0]` will require a
+  volume ID `myvolume[0]`.
+
 - `read_only` `(bool: false)` - Specifies that the group only requires
   read only access to a volume and is used as the default value for
   the `volume_mount -> read_only` configuration. This value is also
@@ -74,64 +81,62 @@ There are two limitations to using HCL2 interpolation for `volume` blocks:
 
 - The `volume` block is used to schedule workloads, so any interpolation needs
   to be done before placement. This means that variables like
-  `NOMAD_ALLOC_INDEX` can't be used for interpolation.
+  `NOMAD_ALLOC_INDEX` can't be used for interpolation. Use the `per_alloc`
+  field described above.
 - Nomad does not yet support dynamic volume creation (see [GH-8212]), so volumes
   must be created and registered before being used as a `volume.source`.
 
 The following job specification demonstrates how to use multiple volumes with
-multiple allocations. It uses a `dynamic` block to create a new task group for
-each of the two volumes. This job specification also shows using HCL2
-variables interpolation to expose information to the task's environment.
+multiple allocations, using the `per_alloc` field. This job specification also
+shows using HCL2 -variables interpolation to expose information to the task's
+environment.
 
 ```hcl
 variables {
-  volume_index = ["0", "1"]
-  path         = "test"
+  path = "test"
 }
 
 job "example" {
   datacenters = ["dc1"]
 
-  dynamic "group" {
-    for_each = var.volume_index
-    labels   = ["cache-${group.value}"]
+  group "cache" {
+
+    count = 2
 
-    content {
+    volume "cache-volume" {
+      type      = "csi"
+      source    = "test-volume"
+      per_alloc = true
+    }
 
-      volume "cache-volume" {
-        type   = "csi"
-        source = "test-volume${group.value}"
+    network {
+      port "db" {
+        to = 6379
       }
+    }
 
-      network {
-        port "db" {
-          to = 6379
-        }
+    task "redis" {
+      driver = "docker"
+      config {
+        image = "redis:3.2"
+        ports = ["db"]
+      }
+      resources {
+        cpu    = 500
+        memory = 256
       }
 
-      task "redis" {
-        driver = "docker"
-        config {
-          image = "redis:3.2"
-          ports = ["db"]
-        }
-        resources {
-          cpu    = 500
-          memory = 256
-        }
-
-        env {
-          # this will be available as the MOUNT_PATH environment
-          # variable in the task
-          MOUNT_PATH = "${NOMAD_ALLOC_DIR}/${var.path}"
-        }
-
-        volume_mount {
-          volume      = "cache-volume"
-          destination = "${NOMAD_ALLOC_DIR}/${var.path}"
-        }
+      env {
+        # this will be available as the MOUNT_PATH environment
+        # variable in the task
+        MOUNT_PATH = "${NOMAD_ALLOC_DIR}/${var.path}"
+      }
 
+      volume_mount {
+        volume      = "cache-volume"
+        destination = "${NOMAD_ALLOC_DIR}/${var.path}"
       }
+
     }
   }
 }
@@ -150,13 +155,13 @@ ID        Node ID   Task Group  Version  Desired  Status   Created  Modified
 81d32909  352c6926  cache-1     0        run      running  4s ago   3s ago
 ce6fbfc8  352c6926  cache-0     0        run      running  4s ago   3s ago
 
-$ nomad volume status test-volume0
+$ nomad volume status 'test-volume[0]'
 ...
 Allocations
 ID        Node ID   Task Group  Version  Desired  Status   Created  Modified
 ce6fbfc8  352c6926  cache-0     0        run      running  29s ago  18s ago
 
-$ nomad volume status test-volume1
+$ nomad volume status 'test-volume[1]'
 ...
 Allocations
 ID        Node ID   Task Group  Version  Desired  Status   Created  Modified