Variable inheritance is described incorrectly in delegation docs

[Dnnd]

Summary

Delegation docs states that:

The ansible_host variable and other connection variables, if present, reflects information about the host a task is delegated to, not the inventory_hostname.

The host to which a task is delegated does not inherit variables from the host that is delegating the task.

All variables except inventory_hostname will now be consumed from this host and not the original task host. If you need variables from the original task host for those options, you must use hostvars[inventory_hostname]['varname'], even inventory_hostname_short refers to the delegated host

In my understanding it means that for an inventory like this:

webservers:
    hosts:
       webserver-1:
           testvar: "var from webserver-1"
       webserver-2:
           testvar: "var from webserver-2"

the following playbook:

- hosts: webservers
  tasks:
    - ansible.builtin.shell: echo "{{ testvar }}" >> /tmp/{{ inventory_hostname }}
      delegate_to: 127.0.0.1

should fail with "The task includes an option with an undefined variable..." error, because there's no "testvar" defined for the 127.0.0.1 host.

However, this task completes successfully, and it correctly writes two files ("var from webserver-1" to /tmp/webserver-1 and "var from webserver-2" to /tmp/webserver-2).

I think, these two statements in the documentation are incorrect (or at least very confusing) because only connection variables aren't inherited by the host to which a task is delegated, not "all variables":

The host to which a task is delegated does not inherit variables from the host that is delegating the task.

All variables except inventory_hostname will now be consumed from this host and not the original task host. If you need variables from the original task host for those options, you must use hostvars[inventory_hostname]['varname'], even inventory_hostname_short refers to the delegated host

The correct version of the documentation would be:

The host to which a task is delegated does not inherit connection variables from the host that is delegating the task.

All connection variables except inventory_hostname will now be consumed from this host and not the original task host. If you need connection variables from the original task host for those options, you must use hostvars[inventory_hostname]['varname'], even inventory_hostname_short refers to the delegated host

I'd also suggest to explicitly clarify that all non-connection variables will be consumed from the original host, not from the delegated host.

The same issue was also discussed on Ansible Community forum: https://forum.ansible.com/t/variables-not-consumed-from-delegated-host/40621 a couple months ago.

Issue Type

Documentation Report

Component Name

playbook_guide/playbooks_delegation.rst

Ansible Version

$ ansible --version
ansible [core 2.18.4]
  config file = <REDACTED>/ansible/ansible.cfg
  configured module search path = ['<REDACTED>/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = <REDACTED>/ansible/.venv/lib/python3.12/site-packages/ansible
  ansible collection location = <REDACTED>/.ansible/collections:/usr/share/ansible/collections
  executable location = <REDACTED>/ansible/.venv/bin/ansible
  python version = 3.12.3 (main, Feb  4 2025, 14:48:35) [GCC 13.3.0] (<REDACTED>/ansible/.venv/bin/python3)
  jinja version = 3.1.6
  libyaml = True

Configuration

# if using a version older than ansible-core 2.12 you should omit the '-t all'
$ ansible-config dump --only-changed -t all
ANSIBLE_PIPELINING(<REDACTED>/ansible/ansible.cfg) = True
CONFIG_FILE() = <REDACTED>/ansible/ansible.cfg
EDITOR(env: EDITOR) = vim
HOST_KEY_CHECKING(<REDACTED>/ansible/ansible.cfg) = False
VARIABLE_PLUGINS_ENABLED(<REDACTED>/ansible/ansible.cfg) = ['host_group_vars', 'community.sops.sops']

GALAXY_SERVERS:


CONNECTION:
==========

local:
_____
pipelining(<REDACTED>/ansible/ansible.cfg) = True

paramiko_ssh:
____________
host_key_checking(<REDACTED>/ansible/ansible.cfg) = False

psrp:
____
pipelining(<REDACTED>/ansible/ansible.cfg) = True

ssh:
___
host_key_checking(<REDACTED>/ansible/ansible.cfg) = False
pipelining(<REDACTED>/ansible/ansible.cfg) = True

winrm:
_____
pipelining(<REDACTED>/ansible/ansible.cfg) = True

OS / Environment

Ansible is installed in WSL2 Ubuntu 24.04
Docs are accessed on Windows 11, in Edge browser

Additional Information

This change makes wording for task delegation clearer. It helps to avoid confusion: user don't need to use hostvars[inventory_hostname]['varname'] unless they're trying to access connection variables.

Code of Conduct

• I agree to follow the Ansible Code of Conduct

[ansibot]

Files identified in the description:

None

If these files are incorrect, please update the component name section of the description or use the component bot command.

[bcoca]

no, it is a bit more nuanced than that, the point is about connection variables that depend on other variables, the templating will follow the delegated host's variables, not the inventory host name. I had expected that the above had already established that all other templating, outside the connection variables, would still use the original inventory_hostname's variables.

For example, ansible_host: '{{inventory_hostname_short}}.example.com will use the variable from the delegated host (which is non connection variable) when templating the connection variable.

[ansible-documentation-bot]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on Matrix at #docs:ansible.im if you ever want to join us and chat about the docs! We meet on Matrix every Tuesday. See the Ansible calendar for meeting details. We welcome additions to our weekly agenda items too. You can add the dawgs-meeting tag to a forum topic to bring it up at the next meeting.