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`.
@ -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.
@ -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:
@ -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>`.
@ -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:
@ -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!
@ -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
@ -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
@ -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
@ -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.
@ -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
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,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.