From 534b8c225a22b666949799794e306542c7fdfd0c Mon Sep 17 00:00:00 2001
From: Brian Coca <bcoca@users.noreply.github.com>
Date: Fri, 22 Aug 2025 18:31:46 -0400
Subject: [PATCH] vars deprecation (#85673)

internal 'vars' dict cache has not been used for long time, but kept since we could not deprecate and some users had found it
---
 changelogs/fragments/vars_begone.yml             |  2 ++
 lib/ansible/vars/manager.py                      | 12 ++++++++++--
 test/integration/targets/var_templating/runme.sh |  3 +++
 .../targets/var_templating/vars_deprecation.yml  | 16 ++++++++++++++++
 4 files changed, 31 insertions(+), 2 deletions(-)
 create mode 100644 changelogs/fragments/vars_begone.yml
 create mode 100644 test/integration/targets/var_templating/vars_deprecation.yml

diff --git a/changelogs/fragments/vars_begone.yml b/changelogs/fragments/vars_begone.yml
new file mode 100644
index 00000000000..0bf8b8f43da
--- /dev/null
+++ b/changelogs/fragments/vars_begone.yml
@@ -0,0 +1,2 @@
+deprecated_features:
+  - vars, the internal variable cache will be removed in 2.24. This cache, once used internally exposes variables in inconsistent states, the 'vars' and 'varnames' lookups should be used instead.
diff --git a/lib/ansible/vars/manager.py b/lib/ansible/vars/manager.py
index e026ff50ec8..37615a4a704 100644
--- a/lib/ansible/vars/manager.py
+++ b/lib/ansible/vars/manager.py
@@ -56,6 +56,12 @@ _DEPRECATE_TOP_LEVEL_FACT_TAG = _tags.Deprecated(
     deprecator=_deprecator.ANSIBLE_CORE_DEPRECATOR,
     help_text='Use `ansible_facts["fact_name"]` (no `ansible_` prefix) instead.',
 )
+_DEPRECATE_VARS = _tags.Deprecated(
+    msg='The internal "vars" dictionary is deprecated.',
+    version='2.24',
+    deprecator=_deprecator.ANSIBLE_CORE_DEPRECATOR,
+    help_text='Use the `vars` and `varnames` lookups instead.',
+)
 
 
 def _deprecate_top_level_fact(value: t.Any) -> t.Any:
@@ -420,8 +426,10 @@ class VariableManager:
 
         # 'vars' magic var
         if task or play:
-            # has to be copy, otherwise recursive ref
-            all_vars['vars'] = all_vars.copy()
+            all_vars['vars'] = _DEPRECATE_VARS.tag({})
+            for k, v in all_vars.items():
+                # has to be copy, otherwise recursive ref
+                all_vars['vars'][k] = _DEPRECATE_VARS.tag(v)
 
         display.debug("done with get_vars()")
         return all_vars
diff --git a/test/integration/targets/var_templating/runme.sh b/test/integration/targets/var_templating/runme.sh
index 69782f112a0..591de012461 100755
--- a/test/integration/targets/var_templating/runme.sh
+++ b/test/integration/targets/var_templating/runme.sh
@@ -13,3 +13,6 @@ ansible-playbook task_vars_templating.yml -v "$@"
 
 # there should be an attempt to use 'sudo' in the connection debug output
 ANSIBLE_BECOME_ALLOW_SAME_USER=true ansible-playbook test_connection_vars.yml -vvvv "$@" | tee /dev/stderr | grep 'sudo \-H \-S'
+
+# test vars deprecation
+ANSIBLE_DEPRECATION_WARNINGS=1 ansible-playbook vars_deprecation.yml "$@"
diff --git a/test/integration/targets/var_templating/vars_deprecation.yml b/test/integration/targets/var_templating/vars_deprecation.yml
new file mode 100644
index 00000000000..fe0d463fe9d
--- /dev/null
+++ b/test/integration/targets/var_templating/vars_deprecation.yml
@@ -0,0 +1,16 @@
+- hosts: localhost
+  gather_facts: false
+  vars:
+    deprecation_message: 'The internal "vars" dictionary is deprecated'
+  tasks:
+    - shell: !unsafe ansible -m debug  -a "msg='{{vars}}'" localhost
+      register: just_vars
+   
+    - shell: !unsafe ansible -m debug  -a 'msg="{{vars["'"ansible_python_interpreter"'"]}}"' localhost
+      register: sub_vars 
+
+    - name: verify we got deprecation
+      assert:
+        that:
+          - deprecation_message in just_vars.stderr
+          - deprecation_message in sub_vars.stderr