From ef3a42ceb8dfbd34e896815a7061008184cb0a53 Mon Sep 17 00:00:00 2001
From: Charlie Voiselle <464492+angrycub@users.noreply.github.com>
Date: Mon, 30 Jan 2023 15:10:15 -0500
Subject: [PATCH] docs: Add info about variable item key name restrictions
 (#15966)

While you can use any string value for a variable Item's key name
using characters that are outside of the set [unicode.Letter,
unicode.Number,`_`] will require the `index` function for direct
access.
---
 website/content/docs/commands/var/put.mdx | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/website/content/docs/commands/var/put.mdx b/website/content/docs/commands/var/put.mdx
index 4909ca8d5..0f254b641 100644
--- a/website/content/docs/commands/var/put.mdx
+++ b/website/content/docs/commands/var/put.mdx
@@ -44,6 +44,13 @@ includes alphanumeric characters and the special characters `-`, `_`, `~`, and
 `/`. Paths may be up to 128 bytes long. The following regex matches the allowed
 paths: `^[a-zA-Z0-9-_~/]{1,128}$`
 
+The keys for the items in a variable may contain any character, but keys
+containing characters outside the set of Unicode letters, Unicode digits, and
+the underscore (`_`) can not be read directly using dotted references in Nomad's
+template engine. Instead, they require the use of the `index` template function
+to directly access their values. This does not impact cases where the keys and
+values are read using the `range` function.
+
 Variable items are restricted to 16KiB in size. This limit is calculated by
 taking the sum of the length in bytes of all of the unencrypted keys and values.