cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

removes last :doc: links in user guide (#58433)

Browse source 
* removes last :doc: links in user guide
This commit is contained in:
Alicia Cozine 2019-06-26 16:07:27 -05:00 committed by Sandra McCann
parent 9ba7015458
commit d4f0bc183e
30 changed files with 112 additions and 124 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/docsite/rst/user_guide/become.rst
View file

@ -74,7 +74,7 @@ ansible_become_user
set the user you become through privilege escalation; does not imply ``ansible_become: yes`` set the user you become through privilege escalation; does not imply ``ansible_become: yes``
ansible_become_password ansible_become_password
set the privilege escalation password. See :doc:`playbooks_vault` for details on how to avoid having secrets in plain text set the privilege escalation password. See :ref:`playbooks_vault` for details on how to avoid having secrets in plain text
For example, if you want to run all tasks as ``root`` on a server named ``webserver``, but you can only connect as the ``manager`` user, you could use an inventory entry like this:: For example, if you want to run all tasks as ``root`` on a server named ``webserver``, but you can only connect as the ``manager`` user, you could use an inventory entry like this::
@ -302,7 +302,7 @@ If you need a password to enter ``enable`` mode, you can specify it in one of tw
.. warning:: .. warning::
As a reminder passwords should never be stored in plain text. For information on encrypting your passwords and other secrets with Ansible Vault, see :doc:`playbooks_vault`. As a reminder passwords should never be stored in plain text. For information on encrypting your passwords and other secrets with Ansible Vault, see :ref:`vault`.
authorize and auth_pass authorize and auth_pass
----------------------- -----------------------

24
docs/docsite/rst/user_guide/intro_adhoc.rst
View file

@ -6,7 +6,7 @@ Introduction To Ad-Hoc Commands
.. contents:: Topics .. contents:: Topics
The following examples show how to use `/usr/bin/ansible` for running The following examples show how to use `/usr/bin/ansible` for running
ad hoc tasks. ad hoc tasks.
What's an ad-hoc command? What's an ad-hoc command?
@ -27,9 +27,9 @@ For configuration management and deployments, though, you'll want to pick up on
using '/usr/bin/ansible-playbook' -- the concepts you will learn here will using '/usr/bin/ansible-playbook' -- the concepts you will learn here will
port over directly to the playbook language. port over directly to the playbook language.
(See :doc:`playbooks` for more information about those) (See :ref:`working_with_playbooks` for more information about those)
If you haven't read :doc:`intro_inventory` already, please look that over a bit first If you haven't read :ref:`intro_inventory` already, please look that over a bit first
and then we'll get going. and then we'll get going.
.. _parallelism_and_shell_commands: .. _parallelism_and_shell_commands:
@ -91,7 +91,7 @@ take a little longer. Feel free to push this value as high as your system can h
You can also select what Ansible "module" you want to run. Normally commands also take a ``-m`` for module name, but You can also select what Ansible "module" you want to run. Normally commands also take a ``-m`` for module name, but
the default module name is 'command', so we didn't need to the default module name is 'command', so we didn't need to
specify that all of the time. We'll use ``-m`` in later examples to specify that all of the time. We'll use ``-m`` in later examples to
run some other :doc:`modules`. run some other modules.
.. note:: .. note::
The :ref:`command module <command_module>` does not support extended shell syntax like piping and The :ref:`command module <command_module>` does not support extended shell syntax like piping and
@ -104,7 +104,7 @@ Using the :ref:`shell module <shell_module>` looks like this::
$ ansible raleigh -m shell -a 'echo $TERM' $ ansible raleigh -m shell -a 'echo $TERM'
When running any command with the Ansible *ad hoc* CLI (as opposed to When running any command with the Ansible *ad hoc* CLI (as opposed to
:doc:`Playbooks <playbooks>`), pay particular attention to shell quoting rules, so :ref:`Playbooks <working_with_playbooks>`), pay particular attention to shell quoting rules, so
the local shell doesn't eat a variable before it gets passed to Ansible. the local shell doesn't eat a variable before it gets passed to Ansible.
For example, using double rather than single quotes in the above example would For example, using double rather than single quotes in the above example would
evaluate the variable on the box you were on. evaluate the variable on the box you were on.
@ -168,9 +168,9 @@ Ensure a package is not installed::
$ ansible webservers -m yum -a "name=acme state=absent" $ ansible webservers -m yum -a "name=acme state=absent"
Ansible has modules for managing packages under many platforms. If there isn't Ansible has modules for managing packages under many platforms. If there isn't
a module for your package manager, you can install packages using the a module for your package manager, you can install packages using the
command module or (better!) contribute a module for your package manager. command module or (better!) contribute a module for your package manager.
Stop by the mailing list for info/details. Stop by the mailing list for info/details.
.. _users_and_groups: .. _users_and_groups:
@ -186,7 +186,7 @@ exist::
$ ansible all -m user -a "name=foo state=absent" $ ansible all -m user -a "name=foo state=absent"
See the :doc:`modules` section for details on all of the available options, including See the :ref:`Module Docs <modules_by_category>` section for details on all of the available options, including
how to manipulate groups and group membership. how to manipulate groups and group membership.
.. _from_source_control: .. _from_source_control:
@ -227,7 +227,7 @@ Time Limited Background Operations
Long running operations can be run in the background, and it is possible to Long running operations can be run in the background, and it is possible to
check their status later. For example, to execute ``long_running_operation`` check their status later. For example, to execute ``long_running_operation``
asynchronously in the background, with a timeout of 3600 seconds (``-B``), asynchronously in the background, with a timeout of 3600 seconds (``-B``),
and without polling (``-P``):: and without polling (``-P``)::
$ ansible all -B 3600 -P 0 -a "/usr/bin/long_running_operation --do-stuff" $ ansible all -B 3600 -P 0 -a "/usr/bin/long_running_operation --do-stuff"
@ -251,7 +251,7 @@ very quickly. After the time limit (in seconds) runs out (``-B``), the process o
the remote nodes will be terminated. the remote nodes will be terminated.
Typically you'll only be backgrounding long-running Typically you'll only be backgrounding long-running
shell commands or software upgrades. Backgrounding the copy module does not do a background file transfer. :doc:`Playbooks <playbooks>` also support polling, and have a simplified syntax for this. shell commands or software upgrades. Backgrounding the copy module does not do a background file transfer. :ref:`Playbooks <working_with_playbooks>` also support polling, and have a simplified syntax for this.
.. _checking_facts: .. _checking_facts:
@ -265,7 +265,7 @@ system. These can be used to implement conditional execution of tasks but also
It's also possible to filter this output to just export certain facts, see the "setup" module documentation for details. It's also possible to filter this output to just export certain facts, see the "setup" module documentation for details.
Read more about facts at :doc:`playbooks_variables` once you're ready to read up on :doc:`Playbooks <playbooks>`. Read more about facts at :ref:`playbooks_variables` once you're ready to read up on :ref:`Playbooks <playbooks_intro>`.
.. seealso:: .. seealso::

2
docs/docsite/rst/user_guide/intro_dynamic_inventory.rst
View file

@ -356,7 +356,7 @@ the dynamic groups as empty in the static inventory file. For example::
.. seealso:: .. seealso::
:doc:`intro_inventory` :ref:`intro_inventory`
All about static inventory files All about static inventory files
`Mailing List <https://groups.google.com/group/ansible-project>`_ `Mailing List <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups Questions? Help? Ideas? Stop by the list on Google Groups

10
docs/docsite/rst/user_guide/intro_getting_started.rst
View file

@ -16,7 +16,7 @@ started with some ad-hoc commands.
What we are showing first are not the powerful configuration/deployment/orchestration features of Ansible. What we are showing first are not the powerful configuration/deployment/orchestration features of Ansible.
These features are handled by playbooks which are covered in a separate section. These features are handled by playbooks which are covered in a separate section.
This section is about how to initially get Ansible running. Once you understand these concepts, read :doc:`intro_adhoc` for some more detail, and then you'll be ready to begin learning about playbooks and explore the most interesting parts! This section is about how to initially get Ansible running. Once you understand these concepts, read :ref:`intro_adhoc` for some more detail, and then you'll be ready to begin learning about playbooks and explore the most interesting parts!
.. _remote_connection_information: .. _remote_connection_information:
@ -55,7 +55,7 @@ public SSH key should be located in ``authorized_keys`` on those systems::
bserver.example.org bserver.example.org
This is an inventory file, which is also explained in greater depth here: :doc:`intro_inventory`. This is an inventory file, which is also explained in greater depth here: :ref:`intro_inventory`.
We'll assume you are using SSH keys for authentication. To set up SSH agent to avoid retyping passwords, you can We'll assume you are using SSH keys for authentication. To set up SSH agent to avoid retyping passwords, you can
do: do:
@ -64,7 +64,7 @@ do:
$ ssh-agent bash $ ssh-agent bash
$ ssh-add ~/.ssh/id_rsa $ ssh-add ~/.ssh/id_rsa
Depending on your setup, you may wish to use Ansible's ``--private-key`` command line option to specify a pem file instead. You can also add the private key file: Depending on your setup, you may wish to use Ansible's ``--private-key`` command line option to specify a pem file instead. You can also add the private key file:
$ ssh-agent bash $ ssh-agent bash
@ -102,9 +102,9 @@ Now run a live command on all of your nodes:
$ ansible all -a "/bin/echo hello" $ ansible all -a "/bin/echo hello"
Congratulations! You've just contacted your nodes with Ansible. It's Congratulations! You've just contacted your nodes with Ansible. It's
soon going to be time to: read about some more real-world cases in :doc:`intro_adhoc`, soon going to be time to: read about some more real-world cases in :ref:`intro_adhoc`,
explore what you can do with different modules, and to learn about the Ansible explore what you can do with different modules, and to learn about the Ansible
:doc:`playbooks` language. Ansible is not just about running commands, it :ref:`working_with_playbooks` language. Ansible is not just about running commands, it
also has powerful configuration management and deployment features. There's more to also has powerful configuration management and deployment features. There's more to
explore, but you already have a fully working infrastructure! explore, but you already have a fully working infrastructure!

10
docs/docsite/rst/user_guide/intro_patterns.rst
View file

@ -6,9 +6,9 @@ Working with Patterns
.. contents:: Topics .. contents:: Topics
Patterns in Ansible are how we decide which hosts to manage. This can mean what hosts to communicate with, but in terms Patterns in Ansible are how we decide which hosts to manage. This can mean what hosts to communicate with, but in terms
of :doc:`playbooks` it actually means what hosts to apply a particular configuration or IT process to. of :ref:`playbooks<playbooks_intro>` it actually means what hosts to apply a particular configuration or IT process to.
We'll go over how to use the command line in :doc:`intro_adhoc` section, however, basically it looks like this:: We'll go over how to use the command line in :ref:`intro_adhoc` section, however, basically it looks like this::
ansible <pattern_goes_here> -m <module_name> -a <arguments> ansible <pattern_goes_here> -m <module_name> -a <arguments>
@ -100,15 +100,15 @@ And if you want to read the list of hosts from a file, prefix the file name with
ansible-playbook site.yml --limit @retry_hosts.txt ansible-playbook site.yml --limit @retry_hosts.txt
Easy enough. See :doc:`intro_adhoc` and then :doc:`playbooks` for how to apply this knowledge. Easy enough. See :ref:`intro_adhoc` and then :ref:`playbooks_intro` for how to apply this knowledge.
.. note:: You can use ',' instead of ':' as a host list separator. The ',' is preferred specially when dealing with ranges and ipv6. .. note:: You can use ',' instead of ':' as a host list separator. The ',' is preferred specially when dealing with ranges and ipv6.
.. seealso:: .. seealso::
:doc:`intro_adhoc` :ref:`intro_adhoc`
Examples of basic commands Examples of basic commands
:doc:`playbooks` :ref:`working_with_playbooks`
Learning ansible's configuration management language Learning ansible's configuration management language
`Mailing List <https://groups.google.com/group/ansible-project>`_ `Mailing List <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups Questions? Help? Ideas? Stop by the list on Google Groups

2
docs/docsite/rst/user_guide/intro_windows.rst
View file

@ -1,4 +1,4 @@
Windows Support Windows Support
=============== ===============
This page has been split up and moved to the new section :doc:`windows`. This page has been split up and moved to the new section :ref:`windows`.

14
docs/docsite/rst/user_guide/modules.rst
View file

@ -13,7 +13,7 @@ Working With Modules
Ansible ships with a number of modules (called the 'module library') Ansible ships with a number of modules (called the 'module library')
that can be executed directly on remote hosts or through :doc:`Playbooks <playbooks>`. that can be executed directly on remote hosts or through :ref:`Playbooks <working_with_playbooks>`.
Users can also write their own modules. These modules can control system resources, Users can also write their own modules. These modules can control system resources,
like services, packages, or files (anything really), or handle executing system commands. like services, packages, or files (anything really), or handle executing system commands.
@ -21,15 +21,15 @@ like services, packages, or files (anything really), or handle executing system
.. seealso:: .. seealso::
:doc:`intro_adhoc` :ref:`intro_adhoc`
Examples of using modules in /usr/bin/ansible Examples of using modules in /usr/bin/ansible
:doc:`playbooks` :ref:`playbooks_intro`
Examples of using modules with /usr/bin/ansible-playbook Introduction to using modules with /usr/bin/ansible-playbook
:doc:`../dev_guide/developing_modules` :ref:`developing_modules_general`
How to write your own modules How to write your own modules
:doc:`../dev_guide/developing_api` :ref:`developing_api`
Examples of using modules with the Python API Examples of using modules with the Python API
:doc:`../reference_appendices/interpreter_discovery` :ref:`interpreter_discovery`
Configuring the right Python interpreter on target hosts Configuring the right Python interpreter on target hosts
`Mailing List <https://groups.google.com/group/ansible-project>`_ `Mailing List <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups Questions? Help? Ideas? Stop by the list on Google Groups

3
docs/docsite/rst/user_guide/modules_intro.rst
View file

@ -44,7 +44,7 @@ Documentation for each module can be accessed from the command line with the ans
ansible-doc yum ansible-doc yum
For a list of all available modules, see :doc:`../modules/modules_by_category`, or run the following at a command prompt:: For a list of all available modules, see the :ref:`Module Docs <modules_by_category>`, or run the following at a command prompt::
ansible-doc -l ansible-doc -l
@ -63,4 +63,3 @@ For a list of all available modules, see :doc:`../modules/modules_by_category`,
Questions? Help? Ideas? Stop by the list on Google Groups Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_ `irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel #ansible IRC chat channel

4
docs/docsite/rst/user_guide/modules_support.rst
View file

@ -42,7 +42,7 @@ If you believe you have found a bug in a module and are already running the late
Should you have a question rather than a bug report, inquiries are welcome on the `ansible-project Google group <https://groups.google.com/forum/#%21forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Should you have a question rather than a bug report, inquiries are welcome on the `ansible-project Google group <https://groups.google.com/forum/#%21forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net.
For development-oriented topics, use the `ansible-devel Google group <https://groups.google.com/forum/#%21forum/ansible-devel>`_ or Ansible's #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read :doc:`Community Information & Contributing <../community/index>`, :doc:`Testing Ansible <../dev_guide/testing>`, and :doc:`Developing Modules <../dev_guide/developing_modules>`. For development-oriented topics, use the `ansible-devel Google group <https://groups.google.com/forum/#%21forum/ansible-devel>`_ or Ansible's #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read the :ref:`Community Guide <ansible_community_guide>`, :ref:`Testing Ansible <developing_testing>`, and the :ref:`Developer Guide <developer_guide>`.
The modules are hosted on GitHub in a subdirectory of the `Ansible <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ repo. The modules are hosted on GitHub in a subdirectory of the `Ansible <https://github.com/ansible/ansible/tree/devel/lib/ansible/modules>`_ repo.
@ -56,7 +56,7 @@ please refer to the following `knowledge base article <https://access.redhat.com
.. seealso:: .. seealso::
:ref:`Modules by category<modules_by_category>` :ref:`Module index<modules_by_category>`
A complete list of all available modules. A complete list of all available modules.
:ref:`intro_adhoc` :ref:`intro_adhoc`
Examples of using modules in /usr/bin/ansible Examples of using modules in /usr/bin/ansible

2
docs/docsite/rst/user_guide/playbooks_advanced_syntax.rst
View file

@ -104,7 +104,7 @@ You've anchored the value of ``version`` with the ``&my_version`` anchor, and re
.. seealso:: .. seealso::
:doc:`playbooks_variables` :ref:`playbooks_variables`
All about variables All about variables
`User Mailing List <https://groups.google.com/group/ansible-project>`_ `User Mailing List <https://groups.google.com/group/ansible-project>`_
Have a question? Stop by the google group! Have a question? Stop by the google group!

4
docs/docsite/rst/user_guide/playbooks_async.rst
View file

@ -42,7 +42,7 @@ poll value is set by the ``DEFAULT_POLL_INTERVAL`` setting if you do not specify
.. note:: .. note::
As of Ansible 2.3, async does not support check mode and will fail the As of Ansible 2.3, async does not support check mode and will fail the
task when run in check mode. See :doc:`playbooks_checkmode` on how to task when run in check mode. See :ref:`check_mode_dry` on how to
skip a task in check mode. skip a task in check mode.
@ -149,7 +149,7 @@ of tasks running concurrently, you can do it this way::
.. seealso:: .. seealso::
:doc:`playbooks` :ref:`playbooks_intro`
An introduction to playbooks An introduction to playbooks
`User Mailing List <https://groups.google.com/group/ansible-devel>`_ `User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group! Have a question? Stop by the google group!

13
docs/docsite/rst/user_guide/playbooks_best_practices.rst
View file

@ -19,7 +19,7 @@ The following section shows one of many possible ways to organize playbook conte
Your usage of Ansible should fit your needs, however, not ours, so feel free to modify this approach and organize as you see fit. Your usage of Ansible should fit your needs, however, not ours, so feel free to modify this approach and organize as you see fit.
One crucial way to organize your playbook content is Ansible's "roles" organization feature, which is documented as part One crucial way to organize your playbook content is Ansible's "roles" organization feature, which is documented as part
of the main playbooks page. You should take the time to read and understand the roles documentation which is available here: :doc:`playbooks_reuse_roles`. of the main playbooks page. You should take the time to read and understand the roles documentation which is available here: :ref:`playbooks_reuse_roles`.
.. _directory_layout: .. _directory_layout:
@ -120,7 +120,7 @@ This layout gives you more flexibility for larger environments, as well as a tot
Use Dynamic Inventory With Clouds Use Dynamic Inventory With Clouds
````````````````````````````````` `````````````````````````````````
If you are using a cloud provider, you should not be managing your inventory in a static file. See :doc:`intro_dynamic_inventory`. If you are using a cloud provider, you should not be managing your inventory in a static file. See :ref:`intro_dynamic_inventory`.
This does not just apply to clouds -- If you have another system maintaining a canonical list of systems This does not just apply to clouds -- If you have another system maintaining a canonical list of systems
in your infrastructure, usage of dynamic inventory is a great idea in general. in your infrastructure, usage of dynamic inventory is a great idea in general.
@ -282,7 +282,7 @@ of each play::
name: ntpd name: ntpd
state: restarted state: restarted
See :doc:`playbooks_reuse_roles` for more information. See :ref:`playbooks_reuse_roles` for more information.
.. _organization_examples: .. _organization_examples:
@ -359,7 +359,7 @@ Rolling Updates
Understand the 'serial' keyword. If updating a webserver farm you really want to use it to control how many machines you are Understand the 'serial' keyword. If updating a webserver farm you really want to use it to control how many machines you are
updating at once in the batch. updating at once in the batch.
See :doc:`playbooks_delegation`. See :ref:`playbooks_delegation`.
.. _mention_the_state: .. _mention_the_state:
@ -374,13 +374,13 @@ parameter in your playbooks to make it clear, especially as some modules support
Group By Roles Group By Roles
++++++++++++++ ++++++++++++++
We're somewhat repeating ourselves with this tip, but it's worth repeating. A system can be in multiple groups. See :doc:`intro_inventory` and :doc:`intro_patterns`. Having groups named after things like We're somewhat repeating ourselves with this tip, but it's worth repeating. A system can be in multiple groups. See :ref:`intro_inventory` and :ref:`intro_patterns`. Having groups named after things like
*webservers* and *dbservers* is repeated in the examples because it's a very powerful concept. *webservers* and *dbservers* is repeated in the examples because it's a very powerful concept.
This allows playbooks to target machines based on role, as well as to assign role specific variables This allows playbooks to target machines based on role, as well as to assign role specific variables
using the group variable system. using the group variable system.
See :doc:`playbooks_reuse_roles`. See :ref:`playbooks_reuse_roles`.
.. _os_variance: .. _os_variance:
@ -509,4 +509,3 @@ This best practice has no limit on the amount of variable and vault files or the
Complete playbook files from the github project source Complete playbook files from the github project source
`Mailing List <https://groups.google.com/group/ansible-project>`_ `Mailing List <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups Questions? Help? Ideas? Stop by the list on Google Groups

4
docs/docsite/rst/user_guide/playbooks_blocks.rst
View file

@ -155,9 +155,9 @@ ansible_failed_result
.. seealso:: .. seealso::
:doc:`playbooks` :ref:`playbooks_intro`
An introduction to playbooks An introduction to playbooks
:doc:`playbooks_reuse_roles` :ref:`playbooks_reuse_roles`
Playbook organization by roles Playbook organization by roles
`User Mailing List <https://groups.google.com/group/ansible-devel>`_ `User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group! Have a question? Stop by the google group!

8
docs/docsite/rst/user_guide/playbooks_checkmode.rst
View file

@ -26,7 +26,7 @@ Enabling or disabling check mode for tasks
.. versionadded:: 2.2 .. versionadded:: 2.2
Sometimes you may want to modify the check mode behavior of individual tasks. This is done via the ``check_mode`` option, which can Sometimes you may want to modify the check mode behavior of individual tasks. This is done via the ``check_mode`` option, which can
be added to tasks. be added to tasks.
There are two options: There are two options:
@ -54,8 +54,8 @@ Example::
Running single tasks with ``check_mode: yes`` can be useful to write tests for Running single tasks with ``check_mode: yes`` can be useful to write tests for
ansible modules, either to test the module itself or to the conditions under ansible modules, either to test the module itself or to the conditions under
which a module would make changes. which a module would make changes.
With ``register`` (see :doc:`playbooks_conditionals`) you can check the With ``register`` (see :ref:`playbooks_conditionals`) you can check the
potential changes. potential changes.
Information about check mode in variables Information about check mode in variables
@ -100,7 +100,7 @@ Since the diff feature produces a large amount of output, it is best used when c
.. versionadded:: 2.4 .. versionadded:: 2.4
The ``--diff`` option can reveal sensitive information. This option can disabled for tasks by specifying ``diff: no``. The ``--diff`` option can reveal sensitive information. This option can disabled for tasks by specifying ``diff: no``.
Example:: Example::

8
docs/docsite/rst/user_guide/playbooks_conditionals.rst
View file

@ -118,7 +118,7 @@ As the examples show, you don't need to use `{{ }}` to use variables inside cond
Loops and Conditionals Loops and Conditionals
`````````````````````` ``````````````````````
Combining `when` with loops (see :doc:`playbooks_loops`), be aware that the `when` statement is processed separately for each item. This is by design:: Combining `when` with loops (see :ref:`playbooks_loops`), be aware that the `when` statement is processed separately for each item. This is by design::
tasks: tasks:
- command: echo {{ item }} - command: echo {{ item }}
@ -174,7 +174,7 @@ Or with a role::
when: ansible_facts['os_family'] == 'Debian' when: ansible_facts['os_family'] == 'Debian'
You will note a lot of 'skipped' output by default in Ansible when using this approach on systems that don't match the criteria. You will note a lot of 'skipped' output by default in Ansible when using this approach on systems that don't match the criteria.
In many cases the ``group_by`` module (see :doc:`modules`) can be a more streamlined way to accomplish the same thing; see In many cases the :ref:`group_by module <group_by_module>` can be a more streamlined way to accomplish the same thing; see
:ref:`os_variance`. :ref:`os_variance`.
When a conditional is used with ``include_*`` tasks instead of imports, it is applied `only` to the include task itself and not When a conditional is used with ``include_*`` tasks instead of imports, it is applied `only` to the include task itself and not
@ -242,7 +242,7 @@ As a reminder, the various YAML files contain just keys and values::
somethingelse: 42 somethingelse: 42
How does this work? For Red Hat operating systems ('CentOS', for example), the first file Ansible tries to import How does this work? For Red Hat operating systems ('CentOS', for example), the first file Ansible tries to import
is 'vars/RedHat.yml'. If that file does not exist, Ansible attempts to load 'vars/os_defaults.yml'. If no files in is 'vars/RedHat.yml'. If that file does not exist, Ansible attempts to load 'vars/os_defaults.yml'. If no files in
the list were found, an error is raised. the list were found, an error is raised.
On Debian, Ansible first looks for 'vars/Debian.yml' instead of 'vars/RedHat.yml', before On Debian, Ansible first looks for 'vars/Debian.yml' instead of 'vars/RedHat.yml', before
@ -330,7 +330,7 @@ You may check the registered variable's string contents for emptiness::
register: contents register: contents
- name: check contents for emptiness - name: check contents for emptiness
debug: debug:
msg: "Directory is empty" msg: "Directory is empty"
when: contents.stdout == "" when: contents.stdout == ""

2
docs/docsite/rst/user_guide/playbooks_debugger.rst
View file

@ -285,7 +285,7 @@ may cause the rescheduled task to execute after subsequent tasks listed in your
.. seealso:: .. seealso::
:doc:`playbooks` :ref:`playbooks_intro`
An introduction to playbooks An introduction to playbooks
`User Mailing List <https://groups.google.com/group/ansible-devel>`_ `User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group! Have a question? Stop by the google group!

20
docs/docsite/rst/user_guide/playbooks_delegation.rst
View file

@ -13,9 +13,9 @@ Additional features allow for tuning the orders in which things complete, and as
This section covers all of these features. For examples of these items in use, `please see the ansible-examples repository <https://github.com/ansible/ansible-examples/>`_. There are quite a few examples of zero-downtime update procedures for different kinds of applications. This section covers all of these features. For examples of these items in use, `please see the ansible-examples repository <https://github.com/ansible/ansible-examples/>`_. There are quite a few examples of zero-downtime update procedures for different kinds of applications.
You should also consult the :doc:`modules` section, various modules like 'ec2_elb', 'nagios', and 'bigip_pool', and 'netscaler' dovetail neatly with the concepts mentioned here. You should also consult the :ref:`module documentation<modules_by_category>` section. Modules like :ref:`ec2_elb<ec2_elb_module>`, :ref:`nagios<nagios_module>`, :ref:`bigip_pool<bigip_pool_module>`, and other :ref:`network_modules` dovetail neatly with the concepts mentioned here.
You'll also want to read up on :doc:`playbooks_reuse_roles`, as the 'pre_task' and 'post_task' concepts are the places where you would typically call these modules. You'll also want to read up on :ref:`playbooks_reuse_roles`, as the 'pre_task' and 'post_task' concepts are the places where you would typically call these modules.
Be aware that certain tasks are impossible to delegate, i.e. `include`, `add_host`, `debug`, etc as they always execute on the controller. Be aware that certain tasks are impossible to delegate, i.e. `include`, `add_host`, `debug`, etc as they always execute on the controller.
@ -130,7 +130,7 @@ In the above example, if more than 3 of the 10 servers in the group were to fail
.. note:: .. note::
The percentage set must be exceeded, not equaled. For example, if serial were set to 4 and you wanted the task to abort The percentage set must be exceeded, not equaled. For example, if serial were set to 4 and you wanted the task to abort
when 2 of the systems failed, the percentage should be set at 49 rather than 50. when 2 of the systems failed, the percentage should be set at 49 rather than 50.
.. _delegation: .. _delegation:
@ -158,7 +158,7 @@ Using this with the 'serial' keyword to control the number of hosts executing at
delegate_to: 127.0.0.1 delegate_to: 127.0.0.1
- name: actual steps would go here - name: actual steps would go here
yum: yum:
name: acme-web-stack name: acme-web-stack
state: latest state: latest
@ -298,8 +298,8 @@ use the default remote connection type::
connection: local connection: local
.. note:: .. note::
If you set the connection to local and there is no ansible_python_interpreter set, modules will run under /usr/bin/python and not If you set the connection to local and there is no ansible_python_interpreter set, modules will run under /usr/bin/python and not
under {{ ansible_playbook_python }}. Be sure to set ansible_python_interpreter: "{{ ansible_playbook_python }}" in under {{ ansible_playbook_python }}. Be sure to set ansible_python_interpreter: "{{ ansible_playbook_python }}" in
host_vars/localhost.yml, for example. You can avoid this issue by using ``local_action`` or ``delegate_to: localhost`` instead. host_vars/localhost.yml, for example. You can avoid this issue by using ``local_action`` or ``delegate_to: localhost`` instead.
@ -330,14 +330,14 @@ For datacenter "A", the playbook can be written this way::
tasks: tasks:
- name: 'shutting down datacenter [ A ]' - name: 'shutting down datacenter [ A ]'
command: /usr/bin/disable-dc command: /usr/bin/disable-dc
- hosts: frontends_dc_a - hosts: frontends_dc_a
tasks: tasks:
- name: 'stopping service' - name: 'stopping service'
command: /usr/bin/stop-software command: /usr/bin/stop-software
- name: 'updating software' - name: 'updating software'
command: /usr/bin/upgrade-software command: /usr/bin/upgrade-software
- hosts: load_balancers_dc_a - hosts: load_balancers_dc_a
tasks: tasks:
- name: 'Starting datacenter [ A ]' - name: 'Starting datacenter [ A ]'
@ -348,7 +348,7 @@ In this example Ansible will start the software upgrade on the front ends only i
.. seealso:: .. seealso::
:doc:`playbooks` :ref:`playbooks_intro`
An introduction to playbooks An introduction to playbooks
`Ansible Examples on GitHub <https://github.com/ansible/ansible-examples>`_ `Ansible Examples on GitHub <https://github.com/ansible/ansible-examples>`_
Many examples of full-stack deployments Many examples of full-stack deployments
@ -356,5 +356,3 @@ In this example Ansible will start the software upgrade on the front ends only i
Have a question? Stop by the google group! Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_ `irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel #ansible IRC chat channel

6
docs/docsite/rst/user_guide/playbooks_environment.rst
View file

@ -6,7 +6,7 @@ Setting the Environment (and Working With Proxies)
.. versionadded:: 1.1 .. versionadded:: 1.1
It is quite possible that you may need to get package updates through a proxy, or even get some package It is quite possible that you may need to get package updates through a proxy, or even get some package
updates through a proxy and access other packages not through a proxy. Or maybe a script you might wish to updates through a proxy and access other packages not through a proxy. Or maybe a script you might wish to
call may also need certain environment variables set to run properly. call may also need certain environment variables set to run properly.
Ansible makes it easy for you to configure the remote execution environment by using the 'environment' keyword. Here is an example:: Ansible makes it easy for you to configure the remote execution environment by using the 'environment' keyword. Here is an example::
@ -124,11 +124,9 @@ You might also want to simply specify the environment for a single task::
.. seealso:: .. seealso::
:doc:`playbooks` :ref:`playbooks_intro`
An introduction to playbooks An introduction to playbooks
`User Mailing List <https://groups.google.com/group/ansible-devel>`_ `User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group! Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_ `irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel #ansible IRC chat channel

8
docs/docsite/rst/user_guide/playbooks_error_handling.rst
View file

@ -186,13 +186,13 @@ See :ref:`block_error_handling` for more examples.
.. seealso:: .. seealso::
:doc:`playbooks` :ref:`playbooks_intro`
An introduction to playbooks An introduction to playbooks
:doc:`playbooks_best_practices` :ref:`playbooks_best_practices`
Best practices in playbooks Best practices in playbooks
:doc:`playbooks_conditionals` :ref:`playbooks_conditionals`
Conditional statements in playbooks Conditional statements in playbooks
:doc:`playbooks_variables` :ref:`playbooks_variables`
All about variables All about variables
`User Mailing List <https://groups.google.com/group/ansible-devel>`_ `User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group! Have a question? Stop by the google group!

9
docs/docsite/rst/user_guide/playbooks_intro.rst
View file

@ -5,6 +5,7 @@ Intro to Playbooks
:local: :local:
.. _about_playbooks: .. _about_playbooks:
.. _playbooks_intro:
About Playbooks About Playbooks
``````````````` ```````````````
@ -48,7 +49,7 @@ Each playbook is composed of one or more 'plays' in a list.
The goal of a play is to map a group of hosts to some well defined roles, represented by The goal of a play is to map a group of hosts to some well defined roles, represented by
things ansible calls tasks. At a basic level, a task is nothing more than a call things ansible calls tasks. At a basic level, a task is nothing more than a call
to an ansible module (see :doc:`modules`). to an ansible module.
By composing a playbook of multiple 'plays', it is possible to By composing a playbook of multiple 'plays', it is possible to
orchestrate multi-machine deployments, running certain steps on all orchestrate multi-machine deployments, running certain steps on all
@ -141,7 +142,7 @@ For each play in a playbook, you get to choose which machines in your infrastruc
to target and what remote user to complete the steps (called tasks) as. to target and what remote user to complete the steps (called tasks) as.
The ``hosts`` line is a list of one or more groups or host patterns, The ``hosts`` line is a list of one or more groups or host patterns,
separated by colons, as described in the :doc:`intro_patterns` separated by colons, as described in the :ref:`intro_patterns`
documentation. The ``remote_user`` is just the name of the user account:: documentation. The ``remote_user`` is just the name of the user account::
--- ---
@ -162,7 +163,7 @@ Remote users can also be defined per task::
ping: ping:
remote_user: yourname remote_user: yourname
Support for running things as another user is also available (see :doc:`become`):: Support for running things as another user is also available (see :ref:`become`)::
--- ---
- hosts: webservers - hosts: webservers
@ -337,7 +338,7 @@ a variable called ``vhost`` in the ``vars`` section, you could do this::
Those same variables are usable in templates, which we'll get to later. 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 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 as described in :doc:`playbooks_reuse`. make more sense to break up tasks as described in :ref:`playbooks_reuse`.
.. _action_shorthand: .. _action_shorthand:

12
docs/docsite/rst/user_guide/playbooks_prompts.rst
View file

@ -2,7 +2,7 @@ Prompts
======= =======
When running a playbook, you may wish to prompt the user for certain input, and can When running a playbook, you may wish to prompt the user for certain input, and can
do so with the 'vars_prompt' section. do so with the 'vars_prompt' section.
A common use for this might be for asking for sensitive data that you do not want to record. A common use for this might be for asking for sensitive data that you do not want to record.
@ -23,9 +23,9 @@ Here is a most basic example::
- name: password - name: password
prompt: "What is your password?" prompt: "What is your password?"
tasks: tasks:
- debug: - debug:
msg: 'Logging in as {{ username }}' msg: 'Logging in as {{ username }}'
The user input is hidden by default but it can be made visible by setting ``private: no``. The user input is hidden by default but it can be made visible by setting ``private: no``.
@ -101,11 +101,11 @@ If you need to put in special characters (i.e `{%`) that might create templating
.. seealso:: .. seealso::
:doc:`playbooks` :ref:`playbooks_intro`
An introduction to playbooks An introduction to playbooks
:doc:`playbooks_conditionals` :ref:`playbooks_conditionals`
Conditional statements in playbooks Conditional statements in playbooks
:doc:`playbooks_variables` :ref:`playbooks_variables`
All about variables All about variables
`User Mailing List <https://groups.google.com/group/ansible-devel>`_ `User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group! Have a question? Stop by the google group!

9
docs/docsite/rst/user_guide/playbooks_reuse_includes.rst
View file

@ -8,12 +8,12 @@ Including and Importing
Includes vs. Imports Includes vs. Imports
```````````````````` ````````````````````
As noted in :doc:`playbooks_reuse`, include and import statements are very similar, however the Ansible executor engine treats them very differently. As noted in :ref:`playbooks_reuse`, include and import statements are very similar, however the Ansible executor engine treats them very differently.
- All ``import*`` statements are pre-processed at the time playbooks are parsed. - All ``import*`` statements are pre-processed at the time playbooks are parsed.
- All ``include*`` statements are processed as they are encountered during the execution of the playbook. - All ``include*`` statements are processed as they are encountered during the execution of the playbook.
Please refer to :doc:`playbooks_reuse` for documentation concerning the trade-offs one may encounter when using each type. Please refer to :ref:`playbooks_reuse` for documentation concerning the trade-offs one may encounter when using each type.
Also be aware that this behaviour changed in 2.4. Prior to Ansible 2.4, only ``include`` was available and it behaved differently depending on context. Also be aware that this behaviour changed in 2.4. Prior to Ansible 2.4, only ``include`` was available and it behaved differently depending on context.
@ -89,14 +89,14 @@ And in your main playbook file::
- import_tasks: more_handlers.yml - import_tasks: more_handlers.yml
.. note:: .. note::
Be sure to refer to the limitations/trade-offs for handlers noted in :doc:`playbooks_reuse`. Be sure to refer to the limitations/trade-offs for handlers noted in :ref:`playbooks_reuse`.
You can mix in includes along with your regular non-included tasks and handlers. You can mix in includes along with your regular non-included tasks and handlers.
Including and Importing Roles Including and Importing Roles
````````````````````````````` `````````````````````````````
Please refer to :doc:`playbooks_reuse_roles` for details on including and importing roles. Please refer to :ref:`playbooks_reuse_roles` for details on including and importing roles.
.. seealso:: .. seealso::
@ -120,4 +120,3 @@ Please refer to :doc:`playbooks_reuse_roles` for details on including and import
Complete playbook files from the GitHub project source Complete playbook files from the GitHub project source
`Mailing List <https://groups.google.com/group/ansible-project>`_ `Mailing List <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups Questions? Help? Ideas? Stop by the list on Google Groups

6
docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
View file

@ -35,8 +35,8 @@ Roles expect files to be in certain directory names. Roles must include at least
- ``tasks`` - contains the main list of tasks to be executed by the role. - ``tasks`` - contains the main list of tasks to be executed by the role.
- ``handlers`` - contains handlers, which may be used by this role or even anywhere outside this role. - ``handlers`` - contains handlers, which may be used by this role or even anywhere outside this role.
- ``defaults`` - default variables for the role (see :doc:`playbooks_variables` for more information). - ``defaults`` - default variables for the role (see :ref:`playbooks_variables` for more information).
- ``vars`` - other variables for the role (see :doc:`playbooks_variables` for more information). - ``vars`` - other variables for the role (see :ref:`playbooks_variables` for more information).
- ``files`` - contains files which can be deployed via this role. - ``files`` - contains files which can be deployed via this role.
- ``templates`` - contains templates which can be deployed via this role. - ``templates`` - contains templates which can be deployed via this role.
- ``meta`` - defines some meta data for this role. See below for more details. - ``meta`` - defines some meta data for this role. See below for more details.
@ -334,7 +334,7 @@ The resulting order of execution would be as follows::
Note that we did not have to use ``allow_duplicates: true`` for ``wheel``, because each instance defined by ``car`` uses different parameter values. Note that we did not have to use ``allow_duplicates: true`` for ``wheel``, because each instance defined by ``car`` uses different parameter values.
.. note:: .. note::
Variable inheritance and scope are detailed in the :doc:`playbooks_variables`. Variable inheritance and scope are detailed in the :ref:`playbooks_variables`.
.. _embedding_modules_and_plugins_in_roles: .. _embedding_modules_and_plugins_in_roles:

2
docs/docsite/rst/user_guide/playbooks_roles.rst
View file

@ -6,7 +6,7 @@ Playbook Roles and Include Statements
.. contents:: Topics .. contents:: Topics
The documentation regarding roles and includes for playbooks have moved. Their new location is here: :doc:`playbooks_reuse`. Please update any links you may have made directly to this page. The documentation regarding roles and includes for playbooks have moved. Their new location is here: :ref:`playbooks_reuse`. Please update any links you may have made directly to this page.
.. seealso:: .. seealso::

4
docs/docsite/rst/user_guide/playbooks_tags.rst
View file

@ -211,9 +211,9 @@ By default, Ansible runs as if ``--tags all`` had been specified.
.. seealso:: .. seealso::
:doc:`playbooks` :ref:`playbooks_intro`
An introduction to playbooks An introduction to playbooks
:doc:`playbooks_reuse_roles` :ref:`playbooks_reuse_roles`
Playbook organization by roles Playbook organization by roles
`User Mailing List <https://groups.google.com/group/ansible-devel>`_ `User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group! Have a question? Stop by the google group!

10
docs/docsite/rst/user_guide/playbooks_templating.rst
View file

@ -39,15 +39,15 @@ fmt
.. seealso:: .. seealso::
:doc:`playbooks` :ref:`playbooks_intro`
An introduction to playbooks An introduction to playbooks
:doc:`playbooks_conditionals` :ref:`playbooks_conditionals`
Conditional statements in playbooks Conditional statements in playbooks
:doc:`playbooks_loops` :ref:`playbooks_loops`
Looping in playbooks Looping in playbooks
:doc:`playbooks_reuse_roles` :ref:`playbooks_reuse_roles`
Playbook organization by roles Playbook organization by roles
:doc:`playbooks_best_practices` :ref:`playbooks_best_practices`
Best practices in playbooks Best practices in playbooks
`User Mailing List <https://groups.google.com/group/ansible-devel>`_ `User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group! Have a question? Stop by the google group!

14
docs/docsite/rst/user_guide/playbooks_tests.rst
View file

@ -59,7 +59,7 @@ To match strings against a substring or a regular expression, use the "match", "
msg: "matched pattern 4" msg: "matched pattern 4"
when: url is regex("example.com/\w+/foo") when: url is regex("example.com/\w+/foo")
'match' requires zero or more characters at the beginning of the string, while 'search' only requires matching a subset of the string. By default, 'regex' works like `search`, but `regex` can be configured to perform other tests as well. 'match' requires zero or more characters at the beginning of the string, while 'search' only requires matching a subset of the string. By default, 'regex' works like `search`, but `regex` can be configured to perform other tests as well.
.. _testing_versions: .. _testing_versions:
@ -249,17 +249,17 @@ The following tasks are illustrative of the tests meant to check the status of t
.. seealso:: .. seealso::
:doc:`playbooks` :ref:`playbooks_intro`
An introduction to playbooks An introduction to playbooks
:doc:`playbooks_conditionals` :ref:`playbooks_conditionals`
Conditional statements in playbooks Conditional statements in playbooks
:doc:`playbooks_variables` :ref:`playbooks_variables`
All about variables All about variables
:doc:`playbooks_loops` :ref:`playbooks_loops`
Looping in playbooks Looping in playbooks
:doc:`playbooks_reuse_roles` :ref:`playbooks_reuse_roles`
Playbook organization by roles Playbook organization by roles
:doc:`playbooks_best_practices` :ref:`playbooks_best_practices`
Best practices in playbooks Best practices in playbooks
`User Mailing List <https://groups.google.com/group/ansible-devel>`_ `User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group! Have a question? Stop by the google group!

10
docs/docsite/rst/user_guide/windows_dsc.rst
View file

@ -28,7 +28,7 @@ Why Use DSC?
DSC and Ansible modules have a common goal which is to define and ensure the state of a DSC and Ansible modules have a common goal which is to define and ensure the state of a
resource. Because of resource. Because of
this, resources like the DSC `File resource <https://docs.microsoft.com/en-us/powershell/dsc/fileresource>`_ this, resources like the DSC `File resource <https://docs.microsoft.com/en-us/powershell/dsc/fileresource>`_
and Ansible ``win_file`` can be used to achieve the same result. Deciding which to use depends and Ansible ``win_file`` can be used to achieve the same result. Deciding which to use depends
on the scenario. on the scenario.
Reasons for using an Ansible module over a DSC resource: Reasons for using an Ansible module over a DSC resource:
@ -325,7 +325,7 @@ modules can be installed to manage other resources that are not usually availabl
Finding Custom DSC Resources Finding Custom DSC Resources
---------------------------- ----------------------------
You can use the You can use the
`PSGallery <https://www.powershellgallery.com/>`_ to find custom resources, along with documentation on how to install them on a Windows host. `PSGallery <https://www.powershellgallery.com/>`_ to find custom resources, along with documentation on how to install them on a Windows host.
The ``Find-DscResource`` cmdlet can also be used to find custom resources. For example: The ``Find-DscResource`` cmdlet can also be used to find custom resources. For example:
@ -496,11 +496,9 @@ Setup IIS Website
.. seealso:: .. seealso::
:doc:`index` :ref:`playbooks_intro`
The documentation index
:doc:`playbooks`
An introduction to playbooks An introduction to playbooks
:doc:`playbooks_best_practices` :ref:`playbooks_best_practices`
Best practices advice Best practices advice
:ref:`List of Windows Modules <windows_modules>` :ref:`List of Windows Modules <windows_modules>`
Windows specific module list, all implemented in PowerShell Windows specific module list, all implemented in PowerShell

6
docs/docsite/rst/user_guide/windows_usage.rst
View file

@ -501,11 +501,9 @@ guides for Windows modules differ substantially from those for standard standard
.. seealso:: .. seealso::
:doc:`index` :ref:`playbooks_intro`
The documentation index
:doc:`playbooks`
An introduction to playbooks An introduction to playbooks
:doc:`playbooks_best_practices` :ref:`playbooks_best_practices`
Best practices advice Best practices advice
:ref:`List of Windows Modules <windows_modules>` :ref:`List of Windows Modules <windows_modules>`
Windows specific module list, all implemented in PowerShell Windows specific module list, all implemented in PowerShell

6
docs/docsite/rst/user_guide/windows_winrm.rst
View file

@ -898,11 +898,9 @@ Some of these limitations can be mitigated by doing one of the following:
.. seealso:: .. seealso::
:doc:`index` :ref:`playbooks_intro`
The documentation index
:doc:`playbooks`
An introduction to playbooks An introduction to playbooks
:doc:`playbooks_best_practices` :ref:`playbooks_best_practices`
Best practices advice Best practices advice
:ref:`List of Windows Modules <windows_modules>` :ref:`List of Windows Modules <windows_modules>`
Windows specific module list, all implemented in PowerShell Windows specific module list, all implemented in PowerShell