From 7f2253451e406c7539ba040c12ecf1b657e4e891 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Fri, 4 Oct 2013 18:41:14 -0400 Subject: [PATCH] More anchors! --- docsite/latest/rst/playbooks.rst | 18 +++++++++++ docsite/latest/rst/playbooks_lookups.rst | 5 +++ docsite/latest/rst/playbooks_variables.rst | 36 +++++++++++++++++++++- 3 files changed, 58 insertions(+), 1 deletion(-) diff --git a/docsite/latest/rst/playbooks.rst b/docsite/latest/rst/playbooks.rst index 04e6c5cec64..414598620d3 100644 --- a/docsite/latest/rst/playbooks.rst +++ b/docsite/latest/rst/playbooks.rst @@ -4,6 +4,8 @@ Intro to Playbooks .. contents:: :depth: 2 +.. _about_playbooks: + About Playbooks ``````````````` @@ -33,6 +35,8 @@ There are also some full sets of playbooks illustrating a lot of these technique There are also many jumping off points after you learn playbooks, so hop back to the documentation index after you're done with this section. +.. _playbook_language_example: + Playbook Language Example ````````````````````````` @@ -77,9 +81,13 @@ For starters, here's a playbook that contains just one play:: Below, we'll break down what the various features of the playbook language are. +.. _playbook_basics: + Basics `````` +.. _playbook_hosts_and_users: + Hosts and Users +++++++++++++++ @@ -140,6 +148,8 @@ Just `Control-C` to kill it and run it again with `-K`. not come into play. Ansible also takes care to not log password parameters. +.. _tasks_list: + Tasks list ++++++++++ @@ -227,6 +237,8 @@ Those same variables are usable in templates, which we'll get to later. Now in a very basic playbook all the tasks will be listed directly in that play, though it will usually make more sense to break up tasks using the 'include:' directive. We'll show that a bit later. +.. _action_shorthand: + Action Shorthand ```````````````` @@ -242,6 +254,8 @@ You will notice in earlier versions, this was only available as:: The old form continues to work in newer versions without any plan of deprecation. +.. _handlers: + Handlers: Running Operations On Change `````````````````````````````````````` @@ -302,6 +316,8 @@ In the above example any queued up handlers would be processed early when the 'm statement was reached. This is a bit of a niche case but can come in handy from time to time. +.. _executing_a_playbook: + Executing A Playbook ```````````````````` @@ -310,6 +326,8 @@ Let's run a playbook using a parallelism level of 10:: ansible-playbook playbook.yml -f 10 +.. _tips_and_tricks: + Tips and Tricks ``````````````` diff --git a/docsite/latest/rst/playbooks_lookups.rst b/docsite/latest/rst/playbooks_lookups.rst index 122fdea342a..5d7752d2104 100644 --- a/docsite/latest/rst/playbooks_lookups.rst +++ b/docsite/latest/rst/playbooks_lookups.rst @@ -7,6 +7,8 @@ in Ansible, and are typically used to load variables or templates with informati .. note:: This is considered an advanced feature, and many users will probably not rely on these features. +.. _getting_file_contents: + Intro to Lookups: Getting File Contents ``````````````````````````````````````` @@ -20,6 +22,8 @@ Contents can be read off the filesystem as follows:: tasks: - debug: msg="the value of foo.txt is {{ contents }}" +.. _password_lookup: + The Password Lookup ``````````````````` @@ -44,6 +48,7 @@ This length can be changed by passing an extra parameter:: (...) +.. _more_lookups: More Lookups ```````````` diff --git a/docsite/latest/rst/playbooks_variables.rst b/docsite/latest/rst/playbooks_variables.rst index 6c154804f51..ba75e34bbc5 100644 --- a/docsite/latest/rst/playbooks_variables.rst +++ b/docsite/latest/rst/playbooks_variables.rst @@ -24,6 +24,8 @@ It's highly recommended that you consult `the Ansible-Examples github repository .. contents:: :depth: 2 +.. _valid_variable_names: + What Makes A Valid Variable Name ```````````````````````````````` @@ -37,6 +39,8 @@ Variable names should be letters, numbers, and underscores. Variables should al Easy enough, let's move on. +.. _variables_in_inventory: + Variables Defined in Inventory `````````````````````````````` @@ -48,6 +52,8 @@ want to use 'boston.ntp.example.com' as an NTP server. See the `intro_inventory` document for multiple ways on how to define variables in inventory. +.. _playbook_variables: + Variables Defined in a Playbook ``````````````````````````````` @@ -59,6 +65,8 @@ In a playbook, it's possible to define variables directly inline like so:: This can be nice as it's right there when you are reading the playbook. +.. _included_variables: + Variables defined from included files and roles ----------------------------------------------- @@ -67,6 +75,8 @@ It turns out we've already talked about variables in another place too. As described in `intro_roles`, variables can also be included in the playbook via include files, which may or may not be part of an "Ansible Role". Usage of roles is preferred as it provides a nice organizational system. +.. _about_jinja2: + Using Variables: About Jinja2 ````````````````````````````` @@ -96,6 +106,8 @@ it's more than that -- you can also read variables about other hosts. We'll sho pieces of files, or to have other ecosystem tools read Ansible files. Not everyone will need this but it can unlock possibilities. +.. _yaml_gotchas: + Hey Wait, A YAML Gotcha ``````````````````````` @@ -114,6 +126,7 @@ Do it like this and you'll be fine:: vars: app_path: "{{ base_path }}/22" +.. _vars_and_facts: Information discovered from systems: Facts `````````````````````````````````````````` @@ -371,6 +384,8 @@ Facts are frequently used in conditionals (see `playbook_conditionals`) and also Facts can be also used to create dynamic groups of hosts that match particular critera, see the :doc:`modules` documentation on 'group_by' for details, as well as in generalized conditional statements as discussed in the `playbook_conditionals` chapter. +.. _disabling_facts: + Turning Off Facts ````````````````` @@ -381,6 +396,8 @@ systems, mainly, or if you are using Ansible on experimental platforms. In any - hosts: whatever gather_facts: no +.. _local_facts:: + Local Facts (Facts.d) ````````````````````` @@ -389,7 +406,11 @@ Local Facts (Facts.d) As discussed in the playbooks chapter, Ansible facts are a way of getting data about remote systems for use in playbook variables. Usually these are discovered automatically by the 'setup' module in Ansible. Users can also write custom facts modules, as described in the API guide. However, what if you want to have a simple way to provide system or user -provided data for use in Ansible variables, without writing a fact module? For instance, what if you want users to be able to control some aspect about how their systems are managed? "Facts.d" is one such mechanism. +provided data for use in Ansible variables, without writing a fact module? + +For instance, what if you want users to be able to control some aspect about how their systems are managed? "Facts.d" is one such mechanism. + +.. note:: Perhaps "local facts" is a bit of a misnomer, it means "locally supplied user values" as opposed to "centrally supplied user values", or what facts are -- "locally dynamically determined values". If a remotely managed system has an "/etc/ansible/facts.d" directory, any files in this directory ending in ".fact", can be JSON, INI, or executable files returning JSON, and these can supply local facts in Ansible. @@ -423,6 +444,7 @@ And this data can be accessed in a template/playbook as:: The local namespace prevents any user supplied fact from overriding system facts or variables defined elsewhere in the playbook. +.. _registered_variables: Registered Variables ```````````````````` @@ -448,6 +470,8 @@ While it's mentioned elsewhere in that document too, here's a quick syntax examp Registered variables are valid on the host the remainder of the playbook run, which is the same as the lifetime of "facts" in Ansible. Effectively registerd variables are just like facts. +.. _accessing_complex_variable_data: + Accessing Complex Variable Data ``````````````````````````````` @@ -466,6 +490,8 @@ Similarly, this is how we access the first element of an array:: {{ foo[0] }} +.. _magic_variables_and_hostvars: + Magic Variables, and How To Access Information About Other Hosts ```````````````````````````````````````````````````````````````` @@ -514,6 +540,8 @@ Don't worry about any of this unless you think you need it. You'll know when yo Also available, *inventory_dir* is the pathname of the directory holding Ansible's inventory host file, *inventory_file* is the pathname and the filename pointing to the Ansible's inventory host file. +.. _variable_file_seperation_details: + Variable File Separation ```````````````````````` @@ -550,6 +578,8 @@ The contents of each variables file is a simple YAML dictionary, like this:: It's also possible to keep per-host and per-group variables in very similar files, this is covered in :ref:`patterns`. +.. _passing_variables_on_the_command_line: + Passing Variables On The Command Line ````````````````````````````````````` @@ -584,6 +614,8 @@ As of Ansible 1.3, extra vars can be loaded from a JSON file with the "@" syntax Also as of Ansible 1.3, extra vars can be formatted as YAML, either on the command line or in a file as above. +.. _conditional_imports: + Conditional Imports ``````````````````` @@ -637,6 +669,8 @@ from turning into arbitrary code with ugly nested ifs, conditionals, and so on - in more streamlined & auditable configuration rules -- especially because there are a minimum of decision points to track. +.. _variable_precedence: + Variable Precedence: Where Should I Put A Variable? ```````````````````````````````````````````````````