From 9135b42903dffd44253bdc58a474beee6b8b8fd5 Mon Sep 17 00:00:00 2001
From: Tim Gross <tgross@hashicorp.com>
Date: Mon, 24 May 2021 10:52:41 -0400
Subject: [PATCH] docs: improve documentation for CSI create/register
 mount_options

Adds clarification to `nomad volume create` commands around how the `volume`
block in the jobspec overrides this behavior. Adds missing section to `nomad
volume register` and to example volume spec for both commands.
---
 CHANGELOG.md                                  |  1 +
 .../content/docs/commands/volume/create.mdx   | 14 +++++++---
 .../content/docs/commands/volume/register.mdx | 26 +++++++++++++++++++
 3 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 737116c7d71..b125a1691e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 BUG FIXES:
 * api: Fixed event stream connection initialization when there are no events to send [[GH-10637](https://github.com/hashicorp/nomad/issues/10637)]
 * cli: Fixed a bug where `quota status` and `namespace status` commands may panic if the CLI targets a pre-1.1.0 cluster
+* csi: Fixed a bug where `mount_options` were not passed to CSI controller plugins for validation during volume creation and mounting. [[GH-10643](https://github.com/hashicorp/nomad/issues/10643)]
 
 ## 1.1.0 (May 18, 2021)
 
diff --git a/website/content/docs/commands/volume/create.mdx b/website/content/docs/commands/volume/create.mdx
index 0701bb6d7f4..be4a203a3df 100644
--- a/website/content/docs/commands/volume/create.mdx
+++ b/website/content/docs/commands/volume/create.mdx
@@ -54,6 +54,11 @@ capability {
   attachment_mode = "file-system"
 }
 
+mount_options {
+  fs_type     = "ext4"
+  mount_flags = "noatime"
+}
+
 secrets {
   example_secret = "xyzzy"
 }
@@ -119,10 +124,11 @@ parameters {
     within the container.
 
 - `mount_options` - Options for mounting `file-system` volumes that don't
-  already have a pre-formatted file system. These field will be validated
-  during volume creation against the `capability` field. Consult the
-  documentation for your storage provider and CSI plugin as to whether these
-  options are required or necessary.
+  already have a pre-formatted file system. This block will be validated
+  during volume creation against the `capability` field. The `mount_options`
+  provided in a job specification's [`volume`] block will override this
+  block. Consult the documentation for your storage provider and CSI plugin as
+  to whether these options are required or necessary.
 
   - `fs_type` `(string <optional>)` - File system type (ex. `"ext4"`)
   - `mount_flags` `([]string: <optional>)` - The flags passed to `mount`
diff --git a/website/content/docs/commands/volume/register.mdx b/website/content/docs/commands/volume/register.mdx
index 2dc832894b6..617819026b1 100644
--- a/website/content/docs/commands/volume/register.mdx
+++ b/website/content/docs/commands/volume/register.mdx
@@ -46,6 +46,21 @@ type            = "csi"
 external_id     = "vol-23452345"
 plugin_id       = "ebs-prod"
 
+capability {
+  access_mode     = "single-node-reader-only"
+  attachment_mode = "file-system"
+}
+
+capability {
+  access_mode     = "single-node-writer"
+  attachment_mode = "file-system"
+}
+
+mount_options {
+  fs_type     = "ext4"
+  mount_flags = "noatime"
+}
+
 secrets {
   example_secret = "xyzzy"
 }
@@ -95,6 +110,16 @@ context {
     `"block-device"`, which will mount the volume with the CSI block device API
     within the container.
 
+- `mount_options` - Options for mounting `file-system` volumes that don't
+  already have a pre-formatted file system. This block will be validated
+  during volume creation against the `capability` field. The `mount_options`
+  provided in a job specification's [`volume`] block will override this
+  block. Consult the documentation for your storage provider and CSI plugin as
+  to whether these options are required or necessary.
+
+  - `fs_type`: file system type (ex. `"ext4"`)
+  - `mount_flags`: the flags passed to `mount` (ex. `"ro,noatime"`)
+
 - `secrets` <code>(map<string|string>:nil)</code> - An optional
   key-value map of strings used as credentials for publishing and
   unpublishing volumes.
@@ -123,4 +148,5 @@ set on a pre-existing volume. You should not set the `snapshot_id`,
 [volume_specification]: #volume-specification
 [csi_plugin]: /docs/job-specification/csi_plugin
 [csi_volume_source]: /docs/job-specification/volume#source
+[`volume`]: /docs/job-specification/volume
 [`volume create`]: /docs/commands/volume/create