diff --git a/docs/docsite/rst/user_guide/become.rst b/docs/docsite/rst/user_guide/become.rst index 2d57f57cdf4..02556550c5b 100644 --- a/docs/docsite/rst/user_guide/become.rst +++ b/docs/docsite/rst/user_guide/become.rst @@ -74,7 +74,7 @@ ansible_become_user set the user you become through privilege escalation; does not imply ``ansible_become: yes`` 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:: @@ -302,7 +302,7 @@ If you need a password to enter ``enable`` mode, you can specify it in one of tw .. 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 ----------------------- diff --git a/docs/docsite/rst/user_guide/intro_adhoc.rst b/docs/docsite/rst/user_guide/intro_adhoc.rst index 62ce7a52bfe..05ffb17c5eb 100644 --- a/docs/docsite/rst/user_guide/intro_adhoc.rst +++ b/docs/docsite/rst/user_guide/intro_adhoc.rst @@ -6,7 +6,7 @@ Introduction To Ad-Hoc Commands .. contents:: Topics The following examples show how to use `/usr/bin/ansible` for running -ad hoc tasks. +ad hoc tasks. 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 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. .. _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 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 -run some other :doc:`modules`. +run some other modules. .. note:: The :ref:`command module ` does not support extended shell syntax like piping and @@ -104,7 +104,7 @@ Using the :ref:`shell module ` looks like this:: $ ansible raleigh -m shell -a 'echo $TERM' When running any command with the Ansible *ad hoc* CLI (as opposed to -:doc:`Playbooks `), pay particular attention to shell quoting rules, so +:ref:`Playbooks `), pay particular attention to shell quoting rules, so 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 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 has modules for managing packages under many platforms. If there isn't -a module for your package manager, you can install packages using the -command module or (better!) contribute a module for your package manager. +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 +command module or (better!) contribute a module for your package manager. Stop by the mailing list for info/details. .. _users_and_groups: @@ -186,7 +186,7 @@ exist:: $ 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 ` section for details on all of the available options, including how to manipulate groups and group membership. .. _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 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``):: $ 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. 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 ` 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 ` also support polling, and have a simplified syntax for this. .. _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. -Read more about facts at :doc:`playbooks_variables` once you're ready to read up on :doc:`Playbooks `. +Read more about facts at :ref:`playbooks_variables` once you're ready to read up on :ref:`Playbooks `. .. seealso:: diff --git a/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst b/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst index a1452ff9e6b..9004079dd45 100644 --- a/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst +++ b/docs/docsite/rst/user_guide/intro_dynamic_inventory.rst @@ -356,7 +356,7 @@ the dynamic groups as empty in the static inventory file. For example:: .. seealso:: - :doc:`intro_inventory` + :ref:`intro_inventory` All about static inventory files `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/user_guide/intro_getting_started.rst b/docs/docsite/rst/user_guide/intro_getting_started.rst index 3ff73634352..7c06b6c9578 100644 --- a/docs/docsite/rst/user_guide/intro_getting_started.rst +++ b/docs/docsite/rst/user_guide/intro_getting_started.rst @@ -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. 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: @@ -55,7 +55,7 @@ public SSH key should be located in ``authorized_keys`` on those systems:: 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 do: @@ -64,7 +64,7 @@ do: $ ssh-agent bash $ 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: $ ssh-agent bash @@ -102,9 +102,9 @@ Now run a live command on all of your nodes: $ ansible all -a "/bin/echo hello" 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 -: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 explore, but you already have a fully working infrastructure! diff --git a/docs/docsite/rst/user_guide/intro_patterns.rst b/docs/docsite/rst/user_guide/intro_patterns.rst index a7f6a956ff6..dc83584bf6d 100644 --- a/docs/docsite/rst/user_guide/intro_patterns.rst +++ b/docs/docsite/rst/user_guide/intro_patterns.rst @@ -6,9 +6,9 @@ Working with Patterns .. contents:: Topics 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` 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 -m -a @@ -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 -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. .. seealso:: - :doc:`intro_adhoc` + :ref:`intro_adhoc` Examples of basic commands - :doc:`playbooks` + :ref:`working_with_playbooks` Learning ansible's configuration management language `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/user_guide/intro_windows.rst b/docs/docsite/rst/user_guide/intro_windows.rst index 5f00ca3d0d7..ba81f6d6a7c 100644 --- a/docs/docsite/rst/user_guide/intro_windows.rst +++ b/docs/docsite/rst/user_guide/intro_windows.rst @@ -1,4 +1,4 @@ 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`. diff --git a/docs/docsite/rst/user_guide/modules.rst b/docs/docsite/rst/user_guide/modules.rst index 917180888d6..36bdc323032 100644 --- a/docs/docsite/rst/user_guide/modules.rst +++ b/docs/docsite/rst/user_guide/modules.rst @@ -13,7 +13,7 @@ Working With Modules Ansible ships with a number of modules (called the 'module library') -that can be executed directly on remote hosts or through :doc:`Playbooks `. +that can be executed directly on remote hosts or through :ref:`Playbooks `. 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. @@ -21,15 +21,15 @@ like services, packages, or files (anything really), or handle executing system .. seealso:: - :doc:`intro_adhoc` + :ref:`intro_adhoc` Examples of using modules in /usr/bin/ansible - :doc:`playbooks` - Examples of using modules with /usr/bin/ansible-playbook - :doc:`../dev_guide/developing_modules` + :ref:`playbooks_intro` + Introduction to using modules with /usr/bin/ansible-playbook + :ref:`developing_modules_general` How to write your own modules - :doc:`../dev_guide/developing_api` + :ref:`developing_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 `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups diff --git a/docs/docsite/rst/user_guide/modules_intro.rst b/docs/docsite/rst/user_guide/modules_intro.rst index 1d36b7bfdfa..7f4237d67f3 100644 --- a/docs/docsite/rst/user_guide/modules_intro.rst +++ b/docs/docsite/rst/user_guide/modules_intro.rst @@ -44,7 +44,7 @@ Documentation for each module can be accessed from the command line with the ans 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 `, or run the following at a command prompt:: 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 `irc.freenode.net `_ #ansible IRC chat channel - diff --git a/docs/docsite/rst/user_guide/modules_support.rst b/docs/docsite/rst/user_guide/modules_support.rst index f5b711f1e08..b3922df781e 100644 --- a/docs/docsite/rst/user_guide/modules_support.rst +++ b/docs/docsite/rst/user_guide/modules_support.rst @@ -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 `_ or on Ansible's "#ansible" channel, located on irc.freenode.net. -For development-oriented topics, use the `ansible-devel Google group `_ 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 `_ or Ansible's #ansible and #ansible-devel channels, located on irc.freenode.net. You should also read the :ref:`Community Guide `, :ref:`Testing Ansible `, and the :ref:`Developer Guide `. The modules are hosted on GitHub in a subdirectory of the `Ansible `_ repo. @@ -56,7 +56,7 @@ please refer to the following `knowledge base article ` + :ref:`Module index` A complete list of all available modules. :ref:`intro_adhoc` Examples of using modules in /usr/bin/ansible diff --git a/docs/docsite/rst/user_guide/playbooks_advanced_syntax.rst b/docs/docsite/rst/user_guide/playbooks_advanced_syntax.rst index 9086d4a72f8..712f08e39a1 100644 --- a/docs/docsite/rst/user_guide/playbooks_advanced_syntax.rst +++ b/docs/docsite/rst/user_guide/playbooks_advanced_syntax.rst @@ -104,7 +104,7 @@ You've anchored the value of ``version`` with the ``&my_version`` anchor, and re .. seealso:: - :doc:`playbooks_variables` + :ref:`playbooks_variables` All about variables `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/playbooks_async.rst b/docs/docsite/rst/user_guide/playbooks_async.rst index 99b4d1e670b..0ad66c7b7cd 100644 --- a/docs/docsite/rst/user_guide/playbooks_async.rst +++ b/docs/docsite/rst/user_guide/playbooks_async.rst @@ -42,7 +42,7 @@ poll value is set by the ``DEFAULT_POLL_INTERVAL`` setting if you do not specify .. note:: 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. @@ -149,7 +149,7 @@ of tasks running concurrently, you can do it this way:: .. seealso:: - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/playbooks_best_practices.rst b/docs/docsite/rst/user_guide/playbooks_best_practices.rst index 1d595b3d3bd..3ce8dfd700c 100644 --- a/docs/docsite/rst/user_guide/playbooks_best_practices.rst +++ b/docs/docsite/rst/user_guide/playbooks_best_practices.rst @@ -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. 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: @@ -120,7 +120,7 @@ This layout gives you more flexibility for larger environments, as well as a tot 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 in your infrastructure, usage of dynamic inventory is a great idea in general. @@ -282,7 +282,7 @@ of each play:: name: ntpd state: restarted -See :doc:`playbooks_reuse_roles` for more information. +See :ref:`playbooks_reuse_roles` for more information. .. _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 updating at once in the batch. -See :doc:`playbooks_delegation`. +See :ref:`playbooks_delegation`. .. _mention_the_state: @@ -374,13 +374,13 @@ parameter in your playbooks to make it clear, especially as some modules support 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. This allows playbooks to target machines based on role, as well as to assign role specific variables using the group variable system. -See :doc:`playbooks_reuse_roles`. +See :ref:`playbooks_reuse_roles`. .. _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 `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups - diff --git a/docs/docsite/rst/user_guide/playbooks_blocks.rst b/docs/docsite/rst/user_guide/playbooks_blocks.rst index 8c1e7ed9fe6..6d41a366aa2 100644 --- a/docs/docsite/rst/user_guide/playbooks_blocks.rst +++ b/docs/docsite/rst/user_guide/playbooks_blocks.rst @@ -155,9 +155,9 @@ ansible_failed_result .. seealso:: - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks - :doc:`playbooks_reuse_roles` + :ref:`playbooks_reuse_roles` Playbook organization by roles `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/playbooks_checkmode.rst b/docs/docsite/rst/user_guide/playbooks_checkmode.rst index 9eee4e44250..e121041daf2 100644 --- a/docs/docsite/rst/user_guide/playbooks_checkmode.rst +++ b/docs/docsite/rst/user_guide/playbooks_checkmode.rst @@ -26,7 +26,7 @@ Enabling or disabling check mode for tasks .. 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 -be added to tasks. +be added to tasks. There are two options: @@ -54,8 +54,8 @@ Example:: 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 -which a module would make changes. -With ``register`` (see :doc:`playbooks_conditionals`) you can check the +which a module would make changes. +With ``register`` (see :ref:`playbooks_conditionals`) you can check the potential changes. 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 -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:: diff --git a/docs/docsite/rst/user_guide/playbooks_conditionals.rst b/docs/docsite/rst/user_guide/playbooks_conditionals.rst index 344bb22744e..fad0834ffe2 100644 --- a/docs/docsite/rst/user_guide/playbooks_conditionals.rst +++ b/docs/docsite/rst/user_guide/playbooks_conditionals.rst @@ -118,7 +118,7 @@ As the examples show, you don't need to use `{{ }}` to use variables inside cond 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: - command: echo {{ item }} @@ -174,7 +174,7 @@ Or with a role:: 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. -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 ` can be a more streamlined way to accomplish the same thing; see :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 @@ -242,7 +242,7 @@ As a reminder, the various YAML files contain just keys and values:: somethingelse: 42 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. 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 - name: check contents for emptiness - debug: + debug: msg: "Directory is empty" when: contents.stdout == "" diff --git a/docs/docsite/rst/user_guide/playbooks_debugger.rst b/docs/docsite/rst/user_guide/playbooks_debugger.rst index 393a78151c6..599bf9b7629 100644 --- a/docs/docsite/rst/user_guide/playbooks_debugger.rst +++ b/docs/docsite/rst/user_guide/playbooks_debugger.rst @@ -285,7 +285,7 @@ may cause the rescheduled task to execute after subsequent tasks listed in your .. seealso:: - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/playbooks_delegation.rst b/docs/docsite/rst/user_guide/playbooks_delegation.rst index ff877dffcbb..439ddf10672 100644 --- a/docs/docsite/rst/user_guide/playbooks_delegation.rst +++ b/docs/docsite/rst/user_guide/playbooks_delegation.rst @@ -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 `_. 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` section. Modules like :ref:`ec2_elb`, :ref:`nagios`, :ref:`bigip_pool`, 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. @@ -130,7 +130,7 @@ In the above example, if more than 3 of the 10 servers in the group were to fail .. 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. .. _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 - name: actual steps would go here - yum: + yum: name: acme-web-stack state: latest @@ -298,8 +298,8 @@ use the default remote connection type:: connection: local .. 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 - under {{ ansible_playbook_python }}. Be sure to set ansible_python_interpreter: "{{ ansible_playbook_python }}" in + 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 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: - name: 'shutting down datacenter [ A ]' command: /usr/bin/disable-dc - + - hosts: frontends_dc_a tasks: - name: 'stopping service' command: /usr/bin/stop-software - name: 'updating software' command: /usr/bin/upgrade-software - + - hosts: load_balancers_dc_a tasks: - name: 'Starting datacenter [ A ]' @@ -348,7 +348,7 @@ In this example Ansible will start the software upgrade on the front ends only i .. seealso:: - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks `Ansible Examples on GitHub `_ 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! `irc.freenode.net `_ #ansible IRC chat channel - - diff --git a/docs/docsite/rst/user_guide/playbooks_environment.rst b/docs/docsite/rst/user_guide/playbooks_environment.rst index b07b087a24d..e617708a2d3 100644 --- a/docs/docsite/rst/user_guide/playbooks_environment.rst +++ b/docs/docsite/rst/user_guide/playbooks_environment.rst @@ -6,7 +6,7 @@ Setting the Environment (and Working With Proxies) .. versionadded:: 1.1 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. 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:: - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks `User Mailing List `_ Have a question? Stop by the google group! `irc.freenode.net `_ #ansible IRC chat channel - - diff --git a/docs/docsite/rst/user_guide/playbooks_error_handling.rst b/docs/docsite/rst/user_guide/playbooks_error_handling.rst index 5871b0f3609..38acea16214 100644 --- a/docs/docsite/rst/user_guide/playbooks_error_handling.rst +++ b/docs/docsite/rst/user_guide/playbooks_error_handling.rst @@ -186,13 +186,13 @@ See :ref:`block_error_handling` for more examples. .. seealso:: - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Best practices in playbooks - :doc:`playbooks_conditionals` + :ref:`playbooks_conditionals` Conditional statements in playbooks - :doc:`playbooks_variables` + :ref:`playbooks_variables` All about variables `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/playbooks_intro.rst b/docs/docsite/rst/user_guide/playbooks_intro.rst index 348c357d1d7..d5d33918dbc 100644 --- a/docs/docsite/rst/user_guide/playbooks_intro.rst +++ b/docs/docsite/rst/user_guide/playbooks_intro.rst @@ -5,6 +5,7 @@ Intro to Playbooks :local: .. _about_playbooks: +.. _playbooks_intro: 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 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 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. 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:: --- @@ -162,7 +163,7 @@ Remote users can also be defined per task:: ping: 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 @@ -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. 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: diff --git a/docs/docsite/rst/user_guide/playbooks_prompts.rst b/docs/docsite/rst/user_guide/playbooks_prompts.rst index b057f3be6ff..f54ebe23d16 100644 --- a/docs/docsite/rst/user_guide/playbooks_prompts.rst +++ b/docs/docsite/rst/user_guide/playbooks_prompts.rst @@ -2,7 +2,7 @@ Prompts ======= 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. @@ -23,9 +23,9 @@ Here is a most basic example:: - name: password prompt: "What is your password?" - tasks: + tasks: - - debug: + - debug: msg: 'Logging in as {{ username }}' 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:: - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks - :doc:`playbooks_conditionals` + :ref:`playbooks_conditionals` Conditional statements in playbooks - :doc:`playbooks_variables` + :ref:`playbooks_variables` All about variables `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_includes.rst b/docs/docsite/rst/user_guide/playbooks_reuse_includes.rst index 8b57e251146..0e394bc0fec 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse_includes.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse_includes.rst @@ -8,12 +8,12 @@ Including and Importing 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 ``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. @@ -89,14 +89,14 @@ And in your main playbook file:: - import_tasks: more_handlers.yml .. 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. 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:: @@ -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 `Mailing List `_ Questions? Help? Ideas? Stop by the list on Google Groups - diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst index 798ca77309d..461c30b431e 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst @@ -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. - ``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). -- ``vars`` - other 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 :ref:`playbooks_variables` for more information). - ``files`` - contains files 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. @@ -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:: - 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: diff --git a/docs/docsite/rst/user_guide/playbooks_roles.rst b/docs/docsite/rst/user_guide/playbooks_roles.rst index 6a84763a0a1..f79e23087d5 100644 --- a/docs/docsite/rst/user_guide/playbooks_roles.rst +++ b/docs/docsite/rst/user_guide/playbooks_roles.rst @@ -6,7 +6,7 @@ Playbook Roles and Include Statements .. 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:: diff --git a/docs/docsite/rst/user_guide/playbooks_tags.rst b/docs/docsite/rst/user_guide/playbooks_tags.rst index 0f05843cbd0..bc08b0ef205 100644 --- a/docs/docsite/rst/user_guide/playbooks_tags.rst +++ b/docs/docsite/rst/user_guide/playbooks_tags.rst @@ -211,9 +211,9 @@ By default, Ansible runs as if ``--tags all`` had been specified. .. seealso:: - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks - :doc:`playbooks_reuse_roles` + :ref:`playbooks_reuse_roles` Playbook organization by roles `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/playbooks_templating.rst b/docs/docsite/rst/user_guide/playbooks_templating.rst index 766aefec707..e6af5fe2d8b 100644 --- a/docs/docsite/rst/user_guide/playbooks_templating.rst +++ b/docs/docsite/rst/user_guide/playbooks_templating.rst @@ -39,15 +39,15 @@ fmt .. seealso:: - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks - :doc:`playbooks_conditionals` + :ref:`playbooks_conditionals` Conditional statements in playbooks - :doc:`playbooks_loops` + :ref:`playbooks_loops` Looping in playbooks - :doc:`playbooks_reuse_roles` + :ref:`playbooks_reuse_roles` Playbook organization by roles - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Best practices in playbooks `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/playbooks_tests.rst b/docs/docsite/rst/user_guide/playbooks_tests.rst index 2acb186c247..1dd8bdd6cf1 100644 --- a/docs/docsite/rst/user_guide/playbooks_tests.rst +++ b/docs/docsite/rst/user_guide/playbooks_tests.rst @@ -59,7 +59,7 @@ To match strings against a substring or a regular expression, use the "match", " msg: "matched pattern 4" 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: @@ -249,17 +249,17 @@ The following tasks are illustrative of the tests meant to check the status of t .. seealso:: - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks - :doc:`playbooks_conditionals` + :ref:`playbooks_conditionals` Conditional statements in playbooks - :doc:`playbooks_variables` + :ref:`playbooks_variables` All about variables - :doc:`playbooks_loops` + :ref:`playbooks_loops` Looping in playbooks - :doc:`playbooks_reuse_roles` + :ref:`playbooks_reuse_roles` Playbook organization by roles - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Best practices in playbooks `User Mailing List `_ Have a question? Stop by the google group! diff --git a/docs/docsite/rst/user_guide/windows_dsc.rst b/docs/docsite/rst/user_guide/windows_dsc.rst index af4a02de768..60c5dafecd1 100644 --- a/docs/docsite/rst/user_guide/windows_dsc.rst +++ b/docs/docsite/rst/user_guide/windows_dsc.rst @@ -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 resource. Because of this, resources like the DSC `File resource `_ -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. 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 ---------------------------- -You can use the +You can use the `PSGallery `_ 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: @@ -496,11 +496,9 @@ Setup IIS Website .. seealso:: - :doc:`index` - The documentation index - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Best practices advice :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell diff --git a/docs/docsite/rst/user_guide/windows_usage.rst b/docs/docsite/rst/user_guide/windows_usage.rst index d49d67e6096..6ce5dea2d35 100644 --- a/docs/docsite/rst/user_guide/windows_usage.rst +++ b/docs/docsite/rst/user_guide/windows_usage.rst @@ -501,11 +501,9 @@ guides for Windows modules differ substantially from those for standard standard .. seealso:: - :doc:`index` - The documentation index - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Best practices advice :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell diff --git a/docs/docsite/rst/user_guide/windows_winrm.rst b/docs/docsite/rst/user_guide/windows_winrm.rst index ea4bac52c6e..32c0a14c0fe 100644 --- a/docs/docsite/rst/user_guide/windows_winrm.rst +++ b/docs/docsite/rst/user_guide/windows_winrm.rst @@ -898,11 +898,9 @@ Some of these limitations can be mitigated by doing one of the following: .. seealso:: - :doc:`index` - The documentation index - :doc:`playbooks` + :ref:`playbooks_intro` An introduction to playbooks - :doc:`playbooks_best_practices` + :ref:`playbooks_best_practices` Best practices advice :ref:`List of Windows Modules ` Windows specific module list, all implemented in PowerShell