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`.
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 <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'
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.
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 <modules_by_category>` 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 <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:
@ -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 <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.
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!
@ -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.
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.
@ -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.
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 <https://groups.google.com/group/ansible-project>`_
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
``````````````````````
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 <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::
@ -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.
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.
@ -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 <https://github.com/ansible/ansible-examples>`_
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 ``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 <https://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
@ -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.
@ -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 <https://groups.google.com/group/ansible-devel>`_
Alicia Cozine
5 years ago
committed by