docs: more notes about hcl2 compatibility (#9634)

Make backward compatibility notes about Task Driver config options. Namely, call out the use of blocks with non-identifier attributes (like in docker systctl and storage_options) or nesting block syntax within an attribute assignment. Neither of these are valid HCL2. The solution is relatively simple: We can add = and quote the non-identifier attribute names.

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

website/pages/docs/drivers/docker.mdx

@@ -128,8 +128,8 @@ config {
 
   ```hcl
   config {
-    sysctl {
-      net.core.somaxconn = "16384"
+    sysctl = {
+      "net.core.somaxconn" = "16384"
     }
   }
   ```
@@ -340,12 +340,12 @@ config {
         target = "/path/in/container"
         source = "name-of-volume"
         readonly = false
-        volume_options {
+        volume_options = {
           no_copy = false
-          labels {
+          labels = {
             foo = "bar"
           }
-          driver_config {
+          driver_config = {
             name = "pxd"
             options = {
               foo = "bar"
@@ -359,7 +359,7 @@ config {
         target = "/path/in/container"
         source = "/path/in/host"
         readonly = false
-        bind_options {
+        bind_options = {
           propagation = "rshared"
         }
       },
@@ -368,7 +368,7 @@ config {
         type = "tmpfs"
         target = "/path/in/container"
         readonly = false
-        tmpfs_options {
+        tmpfs_options = {
           size = 100000 # size in bytes
         }
       }

website/pages/docs/job-specification/hcl2/index.mdx

@@ -111,11 +111,50 @@ meta {
 Additionally, block attributes must be [HCL2 valid identifiers](https://github.com/hashicorp/hcl/blob/v2.8.0/hclsyntax/spec.md#identifiers).
 Generally, identifiers may only contain letters, numbers, underscore `_`,
 or a dash `-`, and start with a letter. Notable,
-[`meta`](https://www.nomadproject.io/docs/job-specification/meta), and
-[`env`](https://www.nomadproject.io/docs/job-specification/env) keys may not
+[`meta`](/docs/job-specification/meta), and
+[`env`](/docs/job-specification/env) keys may not
 contain other symbols (e.g. `.`, `#`).
 
-### Multiline "here doc" strings
+Task driver config fields may require extra attention if they contain invalid
+identifiers. For example, docker [`sysctl`](/docs/drivers/docker#sysctl) must
+use the map assignment syntax if the keys aren't valid:
+
+```hcl
+sysctl = {
+  "net.core.somaxconn/docs/drivers/docker#sysctl" = "16384"
+}
+```
+
+Additionally, task driver config fields may not nest block syntax within an
+assignment syntax. The following [`mounts`](/docs/drivers/docker#mounts) syntax is no longer valid:
+
+```hcl
+# INVALID in Nomad 1.0
+mounts = [
+  {
+    type = "tmpfs"
+    tmpfs_options {  # <- block syntax is not valid here
+      size = 10000
+    }
+  }
+]
+```
+
+Here, the `tmpfs_options` block declaration is invalid HCL2 syntax, and must be an assignment instead:
+
+```hcl
+# VALID in Nomad 1.0
+mounts = [
+  {
+    type = "tmpfs"
+    tmpfs_options = {
+      size = 10000
+    }
+  }
+]
+```
+
+### Multiline "here doc" string
 
 Nomad supports multi-line string literals in the so-called "heredoc" style, inspired by Unix shell languages: