From 34cb05d297f5c5b4396212cf6cff5106efcc5e0c Mon Sep 17 00:00:00 2001
From: Michael Schurter <mschurter@hashicorp.com>
Date: Fri, 27 Sep 2024 10:02:50 -0700
Subject: [PATCH] docs: explain how to use dots in docker labels (#24074)

Nomad v1.9.0 (finally!) removes support for HCL1 and the `-hcl1` flag.
See #23912 for details.

One of the uses of HCL1 over HCL2 was that HCL1 allowed quoted keys in
blocks such as env, meta, and Docker's labels:

```hcl
some_block {
  "foo.bar" = "baz"
}
```

This works in HCL1 but is invalid HCL2. In HCL2 you must use a map
instead of a block:

```hcl
some_map = {
  "eggs.spam" = "works!"
}
```

This was such a hassle for users we special cased the `env` and `meta`
blocks to be accepted as blocks or maps in #9936.

However Docker `labels`, being a task config option, is much harder to
special case and commonly needs dots-in-keys for things like DataDog
autodiscovery via Docker container labels:
https://docs.datadoghq.com/containers/docker/integrations/?tab=labels

Luckily `labels` can be specified as a list-of-maps instead:

```hcl
labels = [
  {
    "com.datadoghq.ad.check_names"  = "[\"openmetrics\"]"
    "com.datadoghq.ad.init_configs" = "[{}]"
  }
]
```

So instead of adding more awkward hcl1/2 backward compat code to Nomad,
I just updated the docs to hopefully help people hit by this.

The only other known workaround is dropping HCL in favor of JSON
jobspecs altogether, but that forces a huge migration and maintenance
burden on users:
https://discuss.hashicorp.com/t/docker-based-autodiscovery-with-datadog-how-can-we-make-it-work/18870
---
 website/content/docs/drivers/docker.mdx       | 15 +++++++++++
 .../content/docs/upgrade/upgrade-specific.mdx | 25 +++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/website/content/docs/drivers/docker.mdx b/website/content/docs/drivers/docker.mdx
index 29bb6f7fff1..881a66afd35 100644
--- a/website/content/docs/drivers/docker.mdx
+++ b/website/content/docs/drivers/docker.mdx
@@ -205,6 +205,21 @@ The `docker` driver supports the following configuration in the job spec. Only
   }
   ```
 
+  A more verbose syntax must be used to specify labels with keys that require
+  quoting. For example DataDog's autodiscovery mechanism looks for labels with
+  dots in the key which must be quoted:
+
+  ```hcl
+  config {
+    labels = [
+      {
+        "com.datadoghq.ad.check_names"  =  "[\"openmetrics\"]"
+        "com.datadoghq.ad.init_configs" = "[{}]"
+      }
+    ]
+  }
+  ```
+
 - `load` - (Optional) Load an image from a `tar` archive file instead of from a
   remote repository. Equivalent to the `docker load -i <filename>` command. If
   you're using an `artifact` block to fetch the archive file, you'll need to
diff --git a/website/content/docs/upgrade/upgrade-specific.mdx b/website/content/docs/upgrade/upgrade-specific.mdx
index 662a5ba29a9..40053416a35 100644
--- a/website/content/docs/upgrade/upgrade-specific.mdx
+++ b/website/content/docs/upgrade/upgrade-specific.mdx
@@ -44,6 +44,31 @@ Nomad 1.9.0 no longer supports the HCLv1 format for job specifications. Using
 the `-hcl1` option for the `job run`, `job plan`, and `job validate` commands
 will no longer work.
 
+One common use of `-hcl1` was when specifying [Docker
+labels](/nomad/docs/drivers/docker#labels) with dots in their keys such as for
+DataDog autodiscovery:
+
+```hcl
+labels {
+  "com.datadoghq.ad.check_names"  = "[\"openmetrics\"]"
+  "com.datadoghq.ad.init_configs" = "[{}]"
+  # ...
+}
+```
+
+Quoted keys are invalid in HCLv2 blocks and must be specified with a
+list-of-maps syntax:
+
+```hcl
+labels = [
+  {
+    "com.datadoghq.ad.check_names"  = "[\"openmetrics\"]"
+    "com.datadoghq.ad.init_configs" = "[{}]"
+    # ...
+  }
+]
+```
+
 ## Nomad 1.8.4
 
 #### Default Docker `infra_image` changed