Add variable evaluation notes to docs #39302

maxamillion · 2018-04-25T15:33:19Z

Signed-off-by: Adam Miller admiller@redhat.com

SUMMARY

Docs update to explain variable evaluation

ISSUE TYPE

Docs Pull Request

COMPONENT NAME

docs

ANSIBLE VERSION

ansible 2.6.0 (docs 9a20967402) last updated 2018/04/25 10:31:49 (GMT -500)
  config file = /etc/ansible/ansible.cfg
  configured module search path = [u'/home/admiller/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
  ansible python module location = /home/admiller/src/dev/ansible/lib/ansible
  executable location = /home/admiller/src/dev/ansible/bin/ansible
  python version = 2.7.14 (default, Mar 14 2018, 13:36:31) [GCC 7.3.1 20180303 (Red Hat 7.3.1-5)]

Signed-off-by: Adam Miller <admiller@redhat.com>

ansibot · 2018-04-25T15:39:46Z

cc @dharmabumstead
click here for bot help

jim-minter · 2018-04-25T15:48:10Z

docs/docsite/rst/shared_snippets/variable_evaluation.rst

@@ -0,0 +1,30 @@
+.. _variable_evaluation:
+
+Variable Evaluation


My impression is that this topic is more about the lazy evaluation of templates rather than variables

jim-minter · 2018-04-25T15:49:23Z

docs/docsite/rst/shared_snippets/variable_evaluation.rst

+In general, Ansible evaluates any variables in playbook content at the last
+possible second, which means that if you define a data structure that data
+structure itself can define variable values within it, and everything “just
+works” as you would expect. This also means variable strings can include other


I disagree with the phrase "just works" as you would expect: it is subjective and does not illuminate the actual behaviour. In my case, the fact that lazy evaluation is used came as a complete surprise.

jim-minter · 2018-04-25T15:51:05Z

docs/docsite/rst/shared_snippets/variable_evaluation.rst

+        b: 3
+
+
+When using an Ansible :ref:`Lookup Plugin`, do note that the value will be


This paragraph seems to conflate at least two important points which may merit separate paragraphs:

lazy template evaluation has the knock-on effect that lookup plugins may be executed more than once, take care if these are not idempotent or if they have side effects

set_fact is a mechanism by which you can "fix" template evaluation at a point in time

jim-minter · 2018-04-25T15:52:40Z

docs/docsite/rst/shared_snippets/variable_evaluation.rst

+var with the result of the Lookup Plugin be stored in the variable, effectively
+resulting in a single evaluation of the variable.
+
+::


I think it would be useful to define more precisely the point(s) at which template evaluation is carried out, perhaps e.g. "templates passed in as arguments to module invocations are fully evaluated at the point of invocation" (which is why set_fact "fixes" template values)

ansibot · 2018-04-25T15:54:55Z

The test ansible-test sanity --test docs-build [explain] failed with 1 error:

docs/docsite/rst/shared_snippets/variable_evaluation.rst:4:0: duplicate-label: duplicate label variable_evaluation, other instance in /root/ansible/docs/docsite/rst/user_guide/playbooks_lookups.rst

The test ansible-test sanity --test no-smart-quotes [explain] failed with 2 errors:

docs/docsite/rst/shared_snippets/variable_evaluation.rst:8:71: use ASCII quotes `'` and `"` instead of Unicode quotes
docs/docsite/rst/shared_snippets/variable_evaluation.rst:9:6: use ASCII quotes `'` and `"` instead of Unicode quotes

click here for bot help

Signed-off-by: Adam Miller <admiller@redhat.com>

ansibot · 2018-04-26T15:00:43Z

The test ansible-test sanity --test no-smart-quotes [explain] failed with 2 errors:

docs/docsite/rst/reference_appendices/glossary.rst:481:79: use ASCII quotes `'` and `"` instead of Unicode quotes
docs/docsite/rst/reference_appendices/glossary.rst:482:14: use ASCII quotes `'` and `"` instead of Unicode quotes

click here for bot help

Signed-off-by: Adam Miller <admiller@redhat.com>

maxamillion · 2018-04-26T16:09:03Z

ping @bcoca - would you mind responding to the comments from @jim-minter, I don't think I know the vars code well enough to properly answer a couple of the outlying questions.

bcoca · 2018-05-15T22:18:32Z

docs/docsite/rst/reference_appendices/glossary.rst

+
+        When using an Ansible :ref:`Lookup Plugin`, do note that the value will be
+        evaluated every time the variable is expanded in a template or in a playbook
+        unless it is explicitly used with ``set_fact`` which will evaluate and define


dont put set_fact here, explain below that how it works as it is a task option

I'm sorry but I don't follow ... what do you mean "how it works as it is a task option"?

friendly nag: ping @bcoca

that 'set_fact' is not magic onto itself, the reason it works is because module options are evaluated

ansibot · 2018-08-03T04:58:53Z

cc @acozine
click here for bot help

Add variable evaluation notes to docs

9a20967

Signed-off-by: Adam Miller <admiller@redhat.com>

maxamillion requested review from dharmabumstead and bcoca April 25, 2018 15:33

ansibot added docs This issue/PR relates to or includes documentation. needs_triage Needs a first human triage before being processed. support:core This issue/PR relates to code supported by the Ansible Engineering Team. labels Apr 25, 2018

jim-minter reviewed Apr 25, 2018

View reviewed changes

ansibot added ci_verified Changes made in this PR are causing tests to fail. needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. labels Apr 25, 2018

jborean93 removed the needs_triage Needs a first human triage before being processed. label Apr 26, 2018

re-org variable evaluaton to be a glossary term with shared_snippet note

0c5837b

Signed-off-by: Adam Miller <admiller@redhat.com>

ansibot removed the ci_verified Changes made in this PR are causing tests to fail. label Apr 26, 2018

ansibot added the ci_verified Changes made in this PR are causing tests to fail. label Apr 26, 2018

remove unicode quotes

6ce3cd7

Signed-off-by: Adam Miller <admiller@redhat.com>

ansibot removed ci_verified Changes made in this PR are causing tests to fail. needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. labels Apr 26, 2018

bcoca reviewed May 15, 2018

View reviewed changes

ansibot added the affects_2.6 This issue/PR affects Ansible v2.6 label May 22, 2018

maxamillion closed this Aug 14, 2018

maxamillion deleted the docs branch August 14, 2018 20:54

ansible locked and limited conversation to collaborators Jul 22, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add variable evaluation notes to docs #39302

Add variable evaluation notes to docs #39302

maxamillion commented Apr 25, 2018

ansibot commented Apr 25, 2018

jim-minter Apr 25, 2018

jim-minter Apr 25, 2018

jim-minter Apr 25, 2018

jim-minter Apr 25, 2018

ansibot commented Apr 25, 2018

ansibot commented Apr 26, 2018

maxamillion commented Apr 26, 2018

bcoca May 15, 2018

maxamillion May 15, 2018

maxamillion May 22, 2018

bcoca May 23, 2018

ansibot commented Aug 3, 2018

		b: 3


		When using an Ansible :ref:`Lookup Plugin`, do note that the value will be

Add variable evaluation notes to docs #39302

Add variable evaluation notes to docs #39302

Conversation

maxamillion commented Apr 25, 2018

SUMMARY

ISSUE TYPE

COMPONENT NAME

ANSIBLE VERSION

ansibot commented Apr 25, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ansibot commented Apr 25, 2018

ansibot commented Apr 26, 2018

maxamillion commented Apr 26, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ansibot commented Aug 3, 2018