As I work through my Ansible education, I’m currently trying to understand variables. I wonder if the online docs would be improved by breaking out the discussion of variables onto a separate page. Currently there is some good information about variables on the command-line examples page (examples.html) and the playbooks page (playbooks.html), but I’d like it if there were more. Things I would like to be able to find in the docs, and am having trouble finding currently, are:
-
More comprehensive explanation of the use of ansible, facter, and ohai variables. I haven’t used facter or ohai in the past. (I’m somewhat familiar with facter, at least, but have never actually used it myself). How and why might these variables be used? A more-detailed discussion might be helpful for a newbie like me.
-
Is it possible to output all the variables currently available in a playbook as a an aid to development and debugging? How would that be done? (I feel like I came across a mention of that at one point, but now I can’t find it.)
-
More (and more-detailed) examples of using variables to do tricky things would be nice. The “Power Tricks” section of playbooks.html has some interesting examples of using variables to create playbooks that can alter their behavior for different circumstances, but the examples don’t go into much detail. I realize that every case will be different, and especially as one gets into larger and more-complex scenarios it’s going to be impossible to cover every possibility in the documentation. But it would be really nice, I think, if some of the more-common use cases could be presented in more detail in some documentation examples.
-
At one point recently I found myself wanting to pass in variables on the command line to ansible-playbook, so a single playbook’s behavior could be customized as one would do with vars_prompt, but without actually prompting for those vars (that is, with the user pre-supplying those vars on the ansible-playbook command line). This would make it easier for me to automate the running of playbooks that were flexible enough to handle installation or deployment across a range of node types and/or environments. Is that possible to do? If not, it might be a feature worth adding. Thoughts?
Thanks.
Replying to my own earlier comment to suggest again that a separate page at ansible.github.com that is specifically about variables, their definition, and their use, might be a good idea for inclusion in 0.5. The documentation improvements that Michael did for 0.4 are great, but I still find myself wrestling a bit to understand the big picture on variables. I think it would be really helpful for me if a document existed that covered:
-
Where and how variables can be defined
** the hosts (inventory) file (INI and YAML versions)
** magic variables from inventory: “groups” and “Inventory_hostname”
** passed to a module via -a “foo=bar baz=walnuts”
** ansible_* vars (and facter_* and ohai_*)
** defined in a playbook’s vars: section
** defined via an external vars_file: file (including conditional imports)
** prompted for via vars_prompt:
** passed on the command line via --extra-vars
-
Jinja2 basics, including complex variables
-
variable scoping issues (which variables are available where)
-
how and where variables can be used ($foo vs. {{ foo }}, in a task’s name: line or not, various parts of a playbook’s YAML definition, etc.
-
best-practice examples of how variables might be used to accomplish various things
A lot of this information is present already (in playbooks.html and playbooks2.html, for example). But if and when things settle down in the journey to 0.5, it might be nice if there could be a single doc that gathers all the variable-specific stuff into one place.
John Callender
jbc@jbcsystems.com
I think the DRY principle does not necessarily have to apply to docs. It would be possible to introduce the various variable-related features the way they are now, and still have a page on variables like I’ve described here, with significant overlap in the information presented in both places. A lot of the best technical documentation ends up having both approaches: a step-by-step tutorial that introduces different concepts all mixed together; and reference documentation that covers individual topics more exhaustively.
I guess there’s a third form that good documentation tends to have, too: the FAQ/cookbook style, where specific questions get canonical best-practice answers. Like the O’Reilly Perl books: you’ve got the llama book (Learning Perl, a tutorial), the camel book (Programming Perl, a reference), and the ram book (The Perl Cookbook). They’re all quite useful, though in different contexts.
It may be too soon to worry about this for Ansible. It’s a moving target, and effort spent maintaining multiple treatments of the same subject matter would probably be better spent on something else. But when things settle down, consider this a +1 vote for some reference-style documentation on variables.
Thanks.
John