From ca25191181ef1d1269afe95ad0911bac8d4d0610 Mon Sep 17 00:00:00 2001
From: Dmitriy Rabotyagov <dmitriy.rabotyagov@cleura.com>
Date: Thu, 4 Jan 2024 13:42:30 +0100
Subject: [PATCH] [doc] Document limitation and workaround for variables in
 mapping keys

Related-Bug: #2048036
Change-Id: Iadaab9c1d9af63bb32a2f9f6977b08fa7f643165
---
 doc/source/index.rst | 70 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2dcb34f..ad08f3e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -153,6 +153,76 @@ Resulting file on the remote host:
   [hello]
   cruel = world
 
+Example of overrides with variable in mapping key
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Due to Ansible design `dictionary keys are not templated`_, which means that
+override like that will not work as might be expected:
+
+.. code-block :: yaml
+
+  - hosts: remote_host
+    gather_facts: no
+    tasks:
+      - config_template:
+          remote_src: true
+          content: |
+            [foo]
+            bar = baz
+          dest: "/etc/test_dst.ini"
+          config_type: "ini"
+          config_overrides:
+            "{{ inventory_hostname }}":
+              cruel: world
+
+Resulting file of such override will be following on the remote host:
+
+.. code-block :: ini
+
+  [foo]
+  bar = baz
+
+  [{{ inventory_hostname }}]
+  cruel = world
+
+In order to properly render dictionary keys it's proposed to workaround the
+limitation by defining dictionary as Jinja2 template, rather then Ansible
+mapping.
+
+Working as expected example can be found below:
+
+.. code-block :: yaml
+
+  - hosts: remote_host
+    gather_facts: no
+    tasks:
+      - config_template:
+          remote_src: true
+          content: |
+            [foo]
+            bar = baz
+          dest: "/etc/test_dst.ini"
+          config_type: "ini"
+          config_overrides: |-
+            {{
+              {
+                inventory_hostname: {
+                  'cruel': 'world'
+                }
+              }
+            }}
+
+Resulting file of the override above will be following file on the remote host:
+
+.. code-block :: ini
+
+  [foo]
+  bar = baz
+
+  [remote_host]
+  cruel = world
+
+.. _dictionary keys are not templated: https://github.com/ansible/ansible/issues/17324
 
 Preventing content from renderring
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^