ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-23 05:10:22 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge remote-tracking branch 'ansible/devel' into devel

Browse source
This commit is contained in:
Yannig Perré 2015-08-05 11:20:41 +02:00
commit 47db352725
763 changed files with 24732 additions and 13274 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docsite/rst/YAMLSyntax.rst
View file

@ -107,7 +107,7 @@ with a "{", YAML will think it is a dictionary, so you must quote it, like so::
Learn what playbooks can do and how to write/run them.
`YAMLLint <http://yamllint.com/>`_
YAML Lint (online) helps you debug YAML syntax if you are having problems
`Github examples directory <https://github.com/ansible/ansible/tree/devel/examples/playbooks>`_
`Github examples directory <https://github.com/ansible/ansible-examples>`_
Complete playbook files from the github project source
`Mailing List <http://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups

2
docsite/rst/become.rst
View file

@ -49,7 +49,7 @@ New command line options
--ask-become-pass
ask for privilege escalation password
-b, --become
--become,-b
run operations with become (no password implied)
--become-method=BECOME_METHOD

14
docsite/rst/community.rst
View file

@ -62,11 +62,11 @@ I'd Like To Report A Bug
Ansible practices responsible disclosure - if this is a security related bug, email `security@ansible.com <mailto:security@ansible.com>`_ instead of filing a ticket or posting to the Google Group and you will receive a prompt response.
Bugs related to the core language should be reported to `github.com/ansible/ansible <http://github.com/ansible/ansible>`_ after
signing up for a free github account. Before reporting a bug, please use the bug/issue search
to see if the issue has already been reported.
Bugs related to the core language should be reported to `github.com/ansible/ansible <https://github.com/ansible/ansible>`_ after
signing up for a free github account. Before reporting a bug, please use the bug/issue search
to see if the issue has already been reported.
MODULE related bugs however should go to `ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ or `ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ based on the classification of the module. This is listed on the bottom of the docs page for any module.
MODULE related bugs however should go to `ansible-modules-core <https://github.com/ansible/ansible-modules-core>`_ or `ansible-modules-extras <https://github.com/ansible/ansible-modules-extras>`_ based on the classification of the module. This is listed on the bottom of the docs page for any module.
When filing a bug, please use the `issue template <https://github.com/ansible/ansible/raw/devel/ISSUE_TEMPLATE.md>`_ to provide all relevant information, regardless of what repo you are filing a ticket against.
@ -132,9 +132,9 @@ Modules are some of the easiest places to get started.
Contributing Code (Features or Bugfixes)
----------------------------------------
The Ansible project keeps its source on github at `github.com/ansible/ansible <http://github.com/ansible/ansible>`_ for
the core application, and two sub repos `github.com/ansible/ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_
and `ansible/ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ for module related items.
The Ansible project keeps its source on github at `github.com/ansible/ansible <https://github.com/ansible/ansible>`_ for
the core application, and two sub repos `github.com/ansible/ansible-modules-core <https://github.com/ansible/ansible-modules-core>`_
and `ansible/ansible-modules-extras <https://github.com/ansible/ansible-modules-extras>`_ for module related items.
If you need to know if a module is in 'core' or 'extras', consult the web documentation page for that module.
The project takes contributions through `github pull requests <https://help.github.com/articles/using-pull-requests>`_.

76
docsite/rst/developing_modules.rst
View file

@ -18,7 +18,7 @@ The directory "./library", alongside your top level playbooks, is also automatic
added as a search directory.
Should you develop an interesting Ansible module, consider sending a pull request to the
`modules-extras project <http://github.com/ansible/ansible-modules-extras>`_. There's also a core
`modules-extras project <https://github.com/ansible/ansible-modules-extras>`_. There's also a core
repo for more established and widely used modules. "Extras" modules may be promoted to core periodically,
but there's no fundamental difference in the end - both ship with ansible, all in one package, regardless
of how you acquire ansible.
@ -238,7 +238,8 @@ The 'group' and 'user' modules are reasonably non-trivial and showcase what this
Key parts include always ending the module file with::
from ansible.module_utils.basic import *
main()
if __name__ == '__main__':
main()
And instantiating the module class like::
@ -291,7 +292,7 @@ will evaluate to True when check mode is enabled. For example::
)
if module.check_mode:
# Check if any changes would be made by don't actually make those changes
# Check if any changes would be made but don't actually make those changes
module.exit_json(changed=check_if_system_state_would_be_changed())
Remember that, as module developer, you are responsible for ensuring that no
@ -342,7 +343,7 @@ and guidelines:
* If packaging modules in an RPM, they only need to be installed on the control machine and should be dropped into /usr/share/ansible. This is entirely optional and up to you.
* Modules should output valid JSON only. All return types must be hashes (dictionaries) although they can be nested. Lists or simple scalar values are not supported, though they can be trivially contained inside a dictionary.
* Modules must output valid JSON only. The toplevel return type must be a hash (dictionary) although they can be nested. Lists or simple scalar values are not supported, though they can be trivially contained inside a dictionary.
* In the event of failure, a key of 'failed' should be included, along with a string explanation in 'msg'. Modules that raise tracebacks (stacktraces) are generally considered 'poor' modules, though Ansible can deal with these returns and will automatically convert anything unparseable into a failed result. If you are using the AnsibleModule common Python code, the 'failed' element will be included for you automatically when you call 'fail_json'.
@ -370,7 +371,7 @@ See an example documentation string in the checkout under `examples/DOCUMENTATIO
Include it in your module file like this::
#!/usr/bin/env python
#!/usr/bin/python
# Copyright header....
DOCUMENTATION = '''
@ -464,7 +465,7 @@ Module checklist
* Requirements should be documented, using the `requirements=[]` field
* Author should be set, name and github id at least
* Made use of U() for urls, C() for files and options, I() for params, M() for modules?
* GPL License header
* GPL 3 License header
* Does module use check_mode? Could it be modified to use it? Document it
* Examples: make sure they are reproducible
* Return: document the return structure of the module
@ -483,11 +484,72 @@ Module checklist
* The return structure should be consistent, even if NA/None are used for keys normally returned under other options.
* Are module actions idempotent? If not document in the descriptions or the notes
* Import module snippets `from ansible.module_utils.basic import *` at the bottom, conserves line numbers for debugging.
* Call your :func:`main` from a conditional so that it would be possible to
test them in the future example::
if __name__ == '__main__':
main()
* Try to normalize parameters with other modules, you can have aliases for when user is more familiar with underlying API name for the option
* Being pep8 compliant is nice, but not a requirement. Specifically, the 80 column limit now hinders readability more that it improves it
* Avoid '`action`/`command`', they are imperative and not declarative, there are other ways to express the same thing
* Sometimes you want to split the module, specially if you are adding a list/info state, you want a _facts version
* If you are asking 'how can i have a module execute other modules' ... you want to write a role
* If you are asking 'how can I have a module execute other modules' ... you want to write a role
* Return values must be able to be serialized as json via the python stdlib
json library. basic python types (strings, int, dicts, lists, etc) are
serializable. A common pitfall is to try returning an object via
exit_json(). Instead, convert the fields you need from the object into the
fields of a dictionary and return the dictionary.
* Do not use urllib2 to handle urls. urllib2 does not natively verify TLS
certificates and so is insecure for https. Instead, use either fetch_url or
open_url from ansible.module_utils.urls.
Windows modules checklist
`````````````````````````
* Favour native powershell and .net ways of doing things over calls to COM libraries or calls to native executables which may or may not be present in all versions of windows
* modules are in powershell (.ps1 files) but the docs reside in same name python file (.py)
* look at ansible/lib/ansible/module_utils/powershell.ps1 for commmon code, avoid duplication
* start with::
#!powershell
then::
<GPL header>
then::
# WANT_JSON
# POWERSHELL_COMMON
* Arguments:
* Try and use state present and state absent like other modules
* You need to check that all your mandatory args are present::
If ($params.state) {
$state = $params.state.ToString().ToLower()
If (($state -ne 'started') -and ($state -ne 'stopped') -and ($state -ne 'restarted')) {
Fail-Json $result "state is '$state'; must be 'started', 'stopped', or 'restarted'"
}
}
* Look at existing modules for more examples of argument checking.
* Results
* The result object should allways contain an attribute called changed set to either $true or $false
* Create your result object like this::
$result = New-Object psobject @{
changed = $false
other_result_attribute = $some_value
};
If all is well, exit with a
Exit-Json $result
* Ensure anything you return, including errors can be converted to json.
* Be aware that because exception messages could contain almost anything.
* ConvertTo-Json will fail if it encounters a trailing \ in a string.
* If all is not well use Fail-Json to exit.
* Have you tested for powershell 3.0 and 4.0 compliance?
Deprecating and making module aliases

14
docsite/rst/developing_plugins.rst
View file

@ -21,7 +21,7 @@ Carrier Pigeon?) it's as simple as copying the format of one of the existing mod
directory. The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses
'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 an later. Previous versions did not support 'smart'.
More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/runner/connection_plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/runner/connection_plugins>`_ and figure things out pretty easily.
More documentation on writing connection plugins is pending, though you can jump into `lib/ansible/plugins/connections <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/connections>`_ and figure things out pretty easily.
.. _developing_lookup_plugins:
@ -30,7 +30,7 @@ Lookup Plugins
Language constructs like "with_fileglob" and "with_items" are implemented via lookup plugins. Just like other plugin types, you can write your own.
More documentation on writing lookup plugins is pending, though you can jump into `lib/ansible/runner/lookup_plugins <https://github.com/ansible/ansible/tree/devel/lib/ansible/runner/lookup_plugins>`_ and figure
More documentation on writing lookup plugins is pending, though you can jump into `lib/ansible/plugins/lookup <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/lookup>`_ and figure
things out pretty easily.
.. _developing_vars_plugins:
@ -54,7 +54,7 @@ Filter Plugins
If you want more Jinja2 filters available in a Jinja2 template (filters like to_yaml and to_json are provided by default), they can be extended by writing a filter plugin. Most of the time, when someone comes up with an idea for a new filter they would like to make available in a playbook, we'll just include them in 'core.py' instead.
Jump into `lib/ansible/runner/filter_plugins/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/runner/filter_plugins>`_ for details.
Jump into `lib/ansible/plugins/filter <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/filter>`_ for details.
.. _developing_callbacks:
@ -68,17 +68,17 @@ Callbacks are one of the more interesting plugin types. Adding additional callb
Examples
++++++++
Example callbacks are shown in `plugins/callbacks <https://github.com/ansible/ansible/tree/devel/plugins/callbacks>`_.
Example callbacks are shown in `lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_.
The `log_plays
<https://github.com/ansible/ansible/blob/devel/plugins/callbacks/log_plays.py>`_
<https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/callback/log_plays.py>`_
callback is an example of how to intercept playbook events to a log
file, and the `mail
<https://github.com/ansible/ansible/blob/devel/plugins/callbacks/mail.py>`_
<https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/callback/mail.py>`_
callback sends email when playbooks complete.
The `osx_say
<https://github.com/ansible/ansible/blob/devel/plugins/callbacks/osx_say.py>`_
<https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/callback/osx_say.py>`_
callback provided is particularly entertaining -- it will respond with
computer synthesized speech on OS X in relation to playbook events,
and is guaranteed to entertain and/or annoy coworkers.

2
docsite/rst/faq.rst
View file

@ -11,7 +11,7 @@ How can I set the PATH or any other environment variable for a task or entire pl
Setting environment variables can be done with the `environment` keyword. It can be used at task or playbook level::
environment:
PATH: {{ ansible_env.PATH }}:/thingy/bin
PATH: "{{ ansible_env.PATH }}:/thingy/bin"
SOME: value

2
docsite/rst/galaxy.rst
View file

@ -8,7 +8,7 @@ Ansible Galaxy
The Website
```````````
The website `Ansible Galaxy <http://galaxy.ansible.com>`_, is a free site for finding, downloading, rating, and reviewing all kinds of community developed Ansible roles and can be a great way to get a jumpstart on your automation projects.
The website `Ansible Galaxy <https://galaxy.ansible.com>`_, is a free site for finding, downloading, rating, and reviewing all kinds of community developed Ansible roles and can be a great way to get a jumpstart on your automation projects.
You can sign up with social auth and use the download client 'ansible-galaxy' which is included in Ansible 1.4.2 and later.

4
docsite/rst/guide_aws.rst
View file

@ -13,7 +13,7 @@ Requirements for the AWS modules are minimal.
All of the modules require and are tested against recent versions of boto. You'll need this Python module installed on your control machine. Boto can be installed from your OS distribution or python's "pip install boto".
Whereas classically ansible will execute tasks in it's host loop against multiple remote machines, most cloud-control steps occur on your local machine with reference to the regions to control.
Whereas classically ansible will execute tasks in its host loop against multiple remote machines, most cloud-control steps occur on your local machine with reference to the regions to control.
In your playbook steps we'll typically be using the following pattern for provisioning steps::
@ -214,7 +214,7 @@ AWS Image Building With Ansible
```````````````````````````````
Many users may want to have images boot to a more complete configuration rather than configuring them entirely after instantiation. To do this,
one of many programs can be used with Ansible playbooks to define and upload a base image, which will then get it's own AMI ID for usage with
one of many programs can be used with Ansible playbooks to define and upload a base image, which will then get its own AMI ID for usage with
the ec2 module or other Ansible AWS modules such as ec2_asg or the cloudformation module. Possible tools include Packer, aminator, and Ansible's
ec2_ami module.

10
docsite/rst/guide_gce.rst
View file

@ -22,7 +22,7 @@ The GCE modules all require the apache-libcloud module, which you can install fr
Credentials
-----------
To work with the GCE modules, you'll first need to get some credentials. You can create new one from the `console <https://console.developers.google.com/>`_ by going to the "APIs and Auth" section and choosing to create a new client ID for a service account. Once you've created a new client ID and downloaded the generated private key (in the `pkcs12 format <http://en.wikipedia.org/wiki/PKCS_12>`_), you'll need to convert the key by running the following command:
To work with the GCE modules, you'll first need to get some credentials. You can create new one from the `console <https://console.developers.google.com/>`_ by going to the "APIs and Auth" section and choosing to create a new client ID for a service account. Once you've created a new client ID and downloaded (you must click **Generate new P12 Key**) the generated private key (in the `pkcs12 format <http://en.wikipedia.org/wiki/PKCS_12>`_), you'll need to convert the key by running the following command:
.. code-block:: bash
@ -79,6 +79,8 @@ Create a file ``secrets.py`` looking like following, and put it in some folder w
GCE_PARAMS = ('i...@project.googleusercontent.com', '/path/to/project.pem')
GCE_KEYWORD_PARAMS = {'project': 'project_id'}
Ensure to enter the email address from the created services account and not the one from your main account.
Now the modules can be used as above, but the account information can be omitted.
GCE Dynamic Inventory
@ -86,9 +88,9 @@ GCE Dynamic Inventory
The best way to interact with your hosts is to use the gce inventory plugin, which dynamically queries GCE and tells Ansible what nodes can be managed.
Note that when using the inventory script ``gce.py``, you also need to populate the ``gce.ini`` file that you can find in the plugins/inventory directory of the ansible checkout.
Note that when using the inventory script ``gce.py``, you also need to populate the ``gce.ini`` file that you can find in the contrib/inventory directory of the ansible checkout.
To use the GCE dynamic inventory script, copy ``gce.py`` from ``plugins/inventory`` into your inventory directory and make it executable. You can specify credentials for ``gce.py`` using the ``GCE_INI_PATH`` environment variable -- the default is to look for gce.ini in the same directory as the inventory script.
To use the GCE dynamic inventory script, copy ``gce.py`` from ``contrib/inventory`` into your inventory directory and make it executable. You can specify credentials for ``gce.py`` using the ``GCE_INI_PATH`` environment variable -- the default is to look for gce.ini in the same directory as the inventory script.
Let's see if inventory is working:
@ -109,7 +111,7 @@ Now let's see if we can use the inventory script to talk to Google.
"x.x.x.x"
],
As with all dynamic inventory plugins in Ansible, you can configure the inventory path in ansible.cfg. The recommended way to use the inventory is to create an ``inventory`` directory, and place both the ``gce.py`` script and a file containing ``localhost`` in it. This can allow for cloud inventory to be used alongside local inventory (such as a physical datacenter) or machines running in different providers.
As with all dynamic inventory scripts in Ansible, you can configure the inventory path in ansible.cfg. The recommended way to use the inventory is to create an ``inventory`` directory, and place both the ``gce.py`` script and a file containing ``localhost`` in it. This can allow for cloud inventory to be used alongside local inventory (such as a physical datacenter) or machines running in different providers.
Executing ``ansible`` or ``ansible-playbook`` and specifying the ``inventory`` directory instead of an individual file will cause ansible to evaluate each file in that directory for inventory.

6
docsite/rst/guide_rax.rst
View file

@ -6,7 +6,7 @@ Rackspace Cloud Guide
Introduction
````````````
.. note:: This section of the documentation is under construction. We are in the process of adding more examples about the Rackspace modules and how they work together. Once complete, there will also be examples for Rackspace Cloud in `ansible-examples <http://github.com/ansible/ansible-examples/>`_.
.. note:: This section of the documentation is under construction. We are in the process of adding more examples about the Rackspace modules and how they work together. Once complete, there will also be examples for Rackspace Cloud in `ansible-examples <https://github.com/ansible/ansible-examples/>`_.
Ansible contains a number of core modules for interacting with Rackspace Cloud.
@ -131,7 +131,7 @@ The rax module returns data about the nodes it creates, like IP addresses, hostn
hostname: "{{ item.name }}"
ansible_ssh_host: "{{ item.rax_accessipv4 }}"
ansible_ssh_pass: "{{ item.rax_adminpass }}"
groupname: raxhosts
groups: raxhosts
with_items: rax.success
when: rax.action == 'create'
@ -519,7 +519,7 @@ Build a complete webserver environment with servers, custom networks and load ba
ansible_ssh_host: "{{ item.rax_accessipv4 }}"
ansible_ssh_pass: "{{ item.rax_adminpass }}"
ansible_ssh_user: root
groupname: web
groups: web
with_items: rax.success
when: rax.action == 'create'

1
docsite/rst/guides.rst
View file

@ -11,7 +11,6 @@ This section is new and evolving. The idea here is explore particular use cases
guide_gce
guide_vagrant
guide_rolling_upgrade
test_strategies
Pending topics may include: Docker, Jenkins, Google Compute Engine, Linode/DigitalOcean, Continuous Deployment, and more.

12
docsite/rst/index.rst
View file

@ -9,14 +9,16 @@ Welcome to the Ansible documentation!
Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks
such as continuous deployments or zero downtime rolling updates.
Ansible's goals are foremost those of simplicity and maximum ease of use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with an accelerated socket mode and pull modes as alternatives), and a language that is designed around auditability by humans -- even those not familiar with the program.
Ansible's main goals are simplicity and ease-of-use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with an accelerated socket mode and pull modes as alternatives), and a language that is designed around auditability by humans--even those not familiar with the program.
We believe simplicity is relevant to all sizes of environments and design for busy users of all types -- whether this means developers, sysadmins, release engineers, IT managers, and everywhere in between. Ansible is appropriate for managing small setups with a handful of instances as well as enterprise environments with many thousands.
We believe simplicity is relevant to all sizes of environments, so we design for busy users of all types: developers, sysadmins, release engineers, IT managers, and everyone in between. Ansible is appropriate for managing all environments, from small setups with a handful of instances to enterprise environments with many thousands of instances.
Ansible manages machines in an agentless manner. There is never a question of how to
upgrade remote daemons or the problem of not being able to manage systems because daemons are uninstalled. As OpenSSH is one of the most peer reviewed open source components, the security exposure of using the tool is greatly reduced. Ansible is decentralized -- it relies on your existing OS credentials to control access to remote machines; if needed it can easily connect with Kerberos, LDAP, and other centralized authentication management systems.
Ansible manages machines in an agent-less manner. There is never a question of how to
upgrade remote daemons or the problem of not being able to manage systems because daemons are uninstalled. Because OpenSSH is one of the most peer-reviewed open source components, security exposure is greatly reduced. Ansible is decentralized--it relies on your existing OS credentials to control access to remote machines. If needed, Ansible can easily connect with Kerberos, LDAP, and other centralized authentication management systems.
This documentation covers the current released version of Ansible (1.8.4) and also some development version features (1.9). For recent features, in each section, the version of Ansible where the feature is added is indicated. Ansible, Inc releases a new major release of Ansible approximately every 2 months. The core application evolves somewhat conservatively, valuing simplicity in language design and setup, while the community around new modules and plugins being developed and contributed moves very very quickly, typically adding 20 or so new modules in each release.
This documentation covers the current released version of Ansible (1.9.1) and also some development version features (2.0). For recent features, we note in each section the version of Ansible where the feature was added.
Ansible, Inc. releases a new major release of Ansible approximately every two months. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. However, the community around new modules and plugins being developed and contributed moves very quickly, typically adding 20 or so new modules in each release.
.. _an_introduction:

59
docsite/rst/intro_configuration.rst
View file

@ -1,5 +1,5 @@
The Ansible Configuration File
++++++++++++++++++++++++++++++
Configuration file
++++++++++++++++++
.. contents:: Topics
@ -144,6 +144,27 @@ different locations::
Most users will not need to use this feature. See :doc:`developing_plugins` for more details
.. _stdout_callback:
stdout_callback
===============
.. versionadded:: 2.0
This setting allows you to override the default stdout callback for ansible-playbook.
.. _callback_whitelist:
callback_whitelist
==================
.. versionadded:: 2.0
Now ansible ships with all included callback plugins ready to use but they are disabled by default,
this setting lets you enable a list of additional callbacks, this cannot change or override the
default stdout callback, use :ref:`stdout_callback` for that.
.. _command_warnings:
command_warnings
@ -224,8 +245,7 @@ or ansible action line exactly as written.
executable
==========
This indicates the command to use to spawn a shell under a sudo environment. Users may need to change this in
rare instances to /bin/bash in rare instances when sudo is constrained, but in most cases it may be left as is::
This indicates the command to use to spawn a shell under a sudo environment. Users may need to change this to /bin/bash in rare instances when sudo is constrained, but in most cases it may be left as is::
executable = /bin/bash
@ -286,9 +306,10 @@ gathering
New in 1.6, the 'gathering' setting controls the default policy of facts gathering (variables discovered about remote systems).
The value 'implicit' is the default, meaning facts will be gathered per play unless 'gather_facts: False' is set in the play. The value 'explicit' is the inverse, facts will not be gathered unless directly requested in the play.
The value 'smart' means each new host that has no facts discovered will be scanned, but if the same host is addressed in multiple plays it will not be contacted again in the playbook run. This option can be useful for those wishing to save fact gathering time.
The value 'implicit' is the default, which means that the fact cache will be ignored and facts will be gathered per play unless 'gather_facts: False' is set.
The value 'explicit' is the inverse, facts will not be gathered unless directly requested in the play.
The value 'smart' means each new host that has no facts discovered will be scanned, but if the same host is addressed in multiple plays it will not be contacted again in the playbook run.
This option can be useful for those wishing to save fact gathering time. Both 'smart' and 'explicit' will use the fact cache.
hash_behaviour
==============
@ -309,7 +330,7 @@ The valid values are either 'replace' (the default) or 'merge'.
hostfile
========
This is a deprecated setting since 1.9, please look at :ref:`inventory` for the new setting.
This is a deprecated setting since 1.9, please look at :ref:`inventory_file` for the new setting.
.. _host_key_checking:
@ -321,7 +342,7 @@ implications and wish to disable it, you may do so here by setting the value to
host_key_checking=True
.. _inventory:
.. _inventory_file:
inventory
=========
@ -680,7 +701,7 @@ If set, this will pass a specific set of options to Ansible rather than Ansible'
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
In particular, users may wish to raise the ControlPersist time to encourage performance. A value of 30 minutes may
be appropriate.
be appropriate. If `ssh_args` is set, the default ``control_path`` setting is not used.
.. _control_path:
@ -700,7 +721,7 @@ may wish to shorten the string to something like the below::
Ansible 1.4 and later will instruct users to run with "-vvvv" in situations where it hits this problem
and if so it is easy to tell there is too long of a Control Path filename. This may be frequently
encountered on EC2.
encountered on EC2. This setting is ignored if ``ssh_args`` is set.
.. _scp_if_ssh:
@ -802,3 +823,19 @@ If enabled, this setting allows multiple private keys to be uploaded to the daem
New clients first connect to the target node over SSH to upload the key, which is done via a local socket file, so they must have the same access as the user that launched the daemon originally.
.. _selinux_settings:
Selinux Specific Settings
-------------------------
These are settings that control SELinux interactions.
special_context_filesystems
===========================
.. versionadded:: 1.9
This is a list of file systems that require special treatment when dealing with security context.
The normal behaviour is for operations to copy the existing context or use the user default, this changes it to use a file system dependent context.
The default list is: nfs,vboxsf,fuse,ramfs

14
docsite/rst/intro_dynamic_inventory.rst
View file

@ -12,7 +12,7 @@ in a different software system. Ansible provides a basic text-based system as d
Frequent examples include pulling inventory from a cloud provider, LDAP, `Cobbler <http://cobbler.github.com>`_,
or a piece of expensive enterprisey CMDB software.
Ansible easily supports all of these options via an external inventory system. The plugins directory contains some of these already -- including options for EC2/Eucalyptus, Rackspace Cloud, and OpenStack, examples of some of which will be detailed below.
Ansible easily supports all of these options via an external inventory system. The contrib/inventory directory contains some of these already -- including options for EC2/Eucalyptus, Rackspace Cloud, and OpenStack, examples of some of which will be detailed below.
:doc:`tower` also provides a database to store inventory results that is both web and REST Accessible. Tower syncs with all Ansible dynamic inventory sources you might be using, and also includes a graphical inventory editor. By having a database record of all of your hosts, it's easy to correlate past event history and see which ones have had failures on their last playbook runs.
@ -30,7 +30,7 @@ While primarily used to kickoff OS installations and manage DHCP and DNS, Cobble
layer that allows it to represent data for multiple configuration management systems (even at the same time), and has
been referred to as a 'lightweight CMDB' by some admins.
To tie Ansible's inventory to Cobbler (optional), copy `this script <https://raw.github.com/ansible/ansible/devel/plugins/inventory/cobbler.py>`_ to /etc/ansible and `chmod +x` the file. cobblerd will now need
To tie Ansible's inventory to Cobbler (optional), copy `this script <https://raw.github.com/ansible/ansible/devel/contrib/inventory/cobbler.py>`_ to /etc/ansible and `chmod +x` the file. cobblerd will now need
to be running when you are using Ansible and you'll need to use Ansible's ``-i`` command line option (e.g. ``-i /etc/ansible/cobbler.py``).
This particular script will communicate with Cobbler using Cobbler's XMLRPC API.
@ -80,14 +80,14 @@ So in other words, you can use those variables in arguments/actions as well.
Example: AWS EC2 External Inventory Script
``````````````````````````````````````````
If you use Amazon Web Services EC2, maintaining an inventory file might not be the best approach, because hosts may come and go over time, be managed by external applications, or you might even be using AWS autoscaling. For this reason, you can use the `EC2 external inventory <https://raw.github.com/ansible/ansible/devel/plugins/inventory/ec2.py>`_ script.
If you use Amazon Web Services EC2, maintaining an inventory file might not be the best approach, because hosts may come and go over time, be managed by external applications, or you might even be using AWS autoscaling. For this reason, you can use the `EC2 external inventory <https://raw.github.com/ansible/ansible/devel/contrib/inventory/ec2.py>`_ script.
You can use this script in one of two ways. The easiest is to use Ansible's ``-i`` command line option and specify the path to the script after
marking it executable::
ansible -i ec2.py -u ubuntu us-east-1d -m ping
The second option is to copy the script to `/etc/ansible/hosts` and `chmod +x` it. You will also need to copy the `ec2.ini <https://raw.githubusercontent.com/ansible/ansible/devel/plugins/inventory/ec2.ini>`_ file to `/etc/ansible/ec2.ini`. Then you can run ansible as you would normally.
The second option is to copy the script to `/etc/ansible/hosts` and `chmod +x` it. You will also need to copy the `ec2.ini <https://raw.githubusercontent.com/ansible/ansible/devel/contrib/inventory/ec2.ini>`_ file to `/etc/ansible/ec2.ini`. Then you can run ansible as you would normally.
To successfully make an API call to AWS, you will need to configure Boto (the Python interface to AWS). There are a `variety of methods <http://docs.pythonboto.org/en/latest/boto_config_tut.html>`_ available, but the simplest is just to export two environment variables::
@ -96,7 +96,7 @@ To successfully make an API call to AWS, you will need to configure Boto (the Py
You can test the script by itself to make sure your config is correct::
cd plugins/inventory
cd contrib/inventory
./ec2.py --list
After a few moments, you should see your entire EC2 inventory across all regions in JSON.
@ -185,7 +185,7 @@ Both ``ec2_security_group_ids`` and ``ec2_security_group_names`` are comma-separ
To see the complete list of variables available for an instance, run the script by itself::
cd plugins/inventory
cd contrib/inventory
./ec2.py --host ec2-12-12-12-12.compute-1.amazonaws.com
Note that the AWS inventory script will cache results to avoid repeated API calls, and this cache setting is configurable in ec2.ini. To
@ -210,7 +210,7 @@ In addition to Cobbler and EC2, inventory scripts are also available for::
Vagrant (not to be confused with the provisioner in vagrant, which is preferred)
Zabbix
Sections on how to use these in more detail will be added over time, but by looking at the "plugins/" directory of the Ansible checkout
Sections on how to use these in more detail will be added over time, but by looking at the "contrib/inventory" directory of the Ansible checkout
it should be very obvious how to use them. The process for the AWS inventory script is the same.
If you develop an interesting inventory script that might be general purpose, please submit a pull request -- we'd likely be glad

26
docsite/rst/intro_installation.rst
View file

@ -8,8 +8,8 @@ Installation
Getting Ansible
```````````````
You may also wish to follow the `Github project <https://github.com/ansible/ansible>`_ if
you have a github account. This is also where we keep the issue tracker for sharing
You may also wish to follow the `GitHub project <https://github.com/ansible/ansible>`_ if
you have a GitHub account. This is also where we keep the issue tracker for sharing
bugs and feature ideas.
.. _what_will_be_installed:
@ -126,7 +126,7 @@ If you don't have pip installed in your version of Python, install pip::
Ansible also uses the following Python modules that need to be installed::
$ sudo pip install paramiko PyYAML Jinja2 httplib2
$ sudo pip install paramiko PyYAML Jinja2 httplib2 six
Note when updating ansible, be sure to not only update the source tree, but also the "submodules" in git
which point at Ansible's own modules (not the same kind of modules, alas).
@ -147,7 +147,7 @@ other than /etc/ansible/hosts:
.. note::
ANSIBLE_INVENTORY is available starting at 1.9 and subtitutes the deprecated ANSIBLE_HOSTS
ANSIBLE_INVENTORY is available starting at 1.9 and substitutes the deprecated ANSIBLE_HOSTS
You can read more about the inventory file in later parts of the manual.
@ -267,6 +267,24 @@ Ansible is available for Solaris as `SysV package from OpenCSW <https://www.open
# pkgadd -d http://get.opencsw.org/now
# /opt/csw/bin/pkgutil -i ansible
.. _from_pacman:
Latest Releases Via Pacman (Arch Linux)
+++++++++++++++++++++++++++++++++++++++
Ansible is available in the Community repository::
$ pacman -S ansible
The AUR has a PKGBUILD for pulling directly from Github called `ansible-git <https://aur.archlinux.org/packages/ansible-git>`_.
Also see the `Ansible <https://wiki.archlinux.org/index.php/Ansible>`_ page on the ArchWiki.
.. note::
If you have Python 3 as a default Python slot on your Arch nodes (default setting), then you
must set ``ansible_python_interpreter = /usr/bin/python2`` in your group or inventory variables.
.. _from_pip:
Latest Releases Via Pip

42
docsite/rst/intro_inventory.rst
View file

@ -46,7 +46,7 @@ To make things explicit, it is suggested that you set them if things are not run
badwolf.example.com:5309
Suppose you have just static IPs and want to set up some aliases that don't live in your host file, or you are connecting through tunnels. You can do things like this::
Suppose you have just static IPs and want to set up some aliases that live in your host file, or you are connecting through tunnels. You can also describe hosts like this::
jumper ansible_ssh_port=5555 ansible_ssh_host=192.168.1.50
@ -106,9 +106,7 @@ Variables can also be applied to an entire group at once::
Groups of Groups, and Group Variables
+++++++++++++++++++++++++++++++++++++
It is also possible to make groups of groups and assign
variables to groups. These variables can be used by /usr/bin/ansible-playbook, but not
/usr/bin/ansible::
It is also possible to make groups of groups using the ``:children`` suffix. Just like above, you can apply variables using ``:vars``::
[atlanta]
host1
@ -194,8 +192,14 @@ is an excellent way to track changes to your inventory and host variables.
List of Behavioral Inventory Parameters
+++++++++++++++++++++++++++++++++++++++
As alluded to above, setting the following variables controls how ansible interacts with remote hosts. Some we have already
mentioned::
As alluded to above, setting the following variables controls how ansible interacts with remote hosts.
Host connection::
ansible_connection
Connection type to the host. Candidates are local, smart, ssh or paramiko. The default is smart.
Ssh connection::
ansible_ssh_host
The name of the host to connect to, if different from the alias you wish to give to it.
@ -205,18 +209,24 @@ mentioned::
The default ssh user name to use.
ansible_ssh_pass
The ssh password to use (this is insecure, we strongly recommend using --ask-pass or SSH keys)
ansible_sudo
The boolean to decide if sudo should be used for this host. Defaults to false.
ansible_sudo_pass
The sudo password to use (this is insecure, we strongly recommend using --ask-sudo-pass)
ansible_sudo_exe (new in version 1.8)
The sudo command path.
ansible_connection
Connection type of the host. Candidates are local, ssh or paramiko. The default is paramiko before Ansible 1.2, and 'smart' afterwards which detects whether usage of 'ssh' would be feasible based on whether ControlPersist is supported.
ansible_ssh_private_key_file
Private key file used by ssh. Useful if using multiple keys and you don't want to use SSH agent.
Privilege escalation (see :doc:`Ansible Privilege Escalation<become>` for further details)::
ansible_become
Equivalent to ansible_sudo or ansible_su, allows to force privilege escalation
ansible_become_method
Allows to set privilege escalation method
ansible_become_user
Equivalent to ansible_sudo_user or ansible_su_user, allows to set the user you become through privilege escalation
ansible_become_pass
Equivalent to ansible_sudo_pass or ansible_su_pass, allows you to set the privilege escalation password
Remote host environnement parameters::
ansible_shell_type
The shell type of the target system. By default commands are formatted using 'sh'-style syntax by default. Setting this to 'csh' or 'fish' will cause commands executed on target systems to follow those shell's syntax instead.
The shell type of the target system. Commands are formatted using 'sh'-style syntax by default. Setting this to 'csh' or 'fish' will cause commands executed on target systems to follow those shell's syntax instead.
ansible_python_interpreter
The target host python path. This is useful for systems with more
than one Python or not located at "/usr/bin/python" such as \*BSD, or where /usr/bin/python
@ -242,7 +252,7 @@ Examples from a host file::
:doc:`intro_adhoc`
Examples of basic commands
:doc:`playbooks`
Learning ansible's configuration management language
Learning Ansible’s configuration, deployment, and orchestration language.
`Mailing List <http://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_

2
docsite/rst/intro_windows.rst
View file

@ -26,7 +26,7 @@ Installing on the Control Machine
On a Linux control machine::
pip install http://github.com/diyan/pywinrm/archive/master.zip#egg=pywinrm
pip install https://github.com/diyan/pywinrm/archive/master.zip#egg=pywinrm
If you wish to connect to domain accounts published through Active Directory (as opposed to local accounts created on the remote host)::

43
docsite/rst/modules.rst
View file

@ -2,48 +2,20 @@ About Modules
=============
.. toctree::
:maxdepth: 4
:maxdepth: 1
.. _modules_intro:
modules_intro
modules_core
modules_extra
common_return_values
Introduction
````````````
Ansible ships with a number of modules (called the 'module library')
that can be executed directly on remote hosts or through :doc:`Playbooks <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.
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.
Let's review how we execute three different modules from the command line::
ansible webservers -m service -a "name=httpd state=started"
ansible webservers -m ping
ansible webservers -m command -a "/sbin/reboot -t now"
Each module supports taking arguments. Nearly all modules take ``key=value``
arguments, space delimited. Some modules take no arguments, and the command/shell modules simply
take the string of the command you want to run.
From playbooks, Ansible modules are executed in a very similar way::
- name: reboot the servers
action: command /sbin/reboot -t now
Which can be abbreviated to::
- name: reboot the servers
command: /sbin/reboot -t now
All modules technically return JSON format data, though if you are using the command line or playbooks, you don't really need to know much about
that. If you're writing your own module, you care, and this means you do not have to write modules in any particular language -- you get to choose.
Modules are `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made. When using Ansible
playbooks, these modules can trigger 'change events' in the form of notifying 'handlers' to run additional tasks.
Documentation for each module can be accessed from the command line with the ansible-doc tool::
ansible-doc yum
.. seealso::
@ -59,4 +31,3 @@ Documentation for each module can be accessed from the command line with the ans
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

13
docsite/rst/modules_core.rst Normal file
View file

@ -0,0 +1,13 @@
Core Modules
------------
These are modules that the core ansible team maintains and will always ship with ansible itself.
They will also receive slightly higher priority for all requests than those in the "extras" repos.
The source of these modules is hosted on GitHub in the `ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ repo.
If you believe you have found a bug in a core module and are already running the latest stable or development version of Ansible, first look in the `issue tracker at github.com/ansible/ansible-modules-core <http://github.com/ansible/ansible-modules-core>`_ to see if a bug has already been filed. If not, we would be grateful if you would file one.
Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_ or on Ansible's "#ansible" channel, located on irc.freenode.net. Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
Documentation updates for these modules can also be edited directly in the module itself and by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.

22
docsite/rst/modules_extra.rst Normal file
View file

@ -0,0 +1,22 @@
Extras Modules
--------------
These modules are currently shipped with Ansible, but might be shipped separately in the future. They are also mostly maintained by the community.
Non-core modules are still fully usable, but may receive slightly lower response rates for issues and pull requests.
Popular "extras" modules may be promoted to core modules over time.
This source for these modules is hosted on GitHub in the `ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_ repo.
If you believe you have found a bug in an extras module and are already running the latest stable or development version of Ansible,
first look in the `issue tracker at github.com/ansible/ansible-modules-extras <http://github.com/ansible/ansible-modules-extras>`_
o see if a bug has already been filed. If not, we would be grateful if you would file one.
Should you have a question rather than a bug report, inquries are welcome on the `ansible-project google group <https://groups.google.com/forum/#!forum/ansible-project>`_
or on Ansible's "#ansible" channel, located on irc.freenode.net.
Development oriented topics should instead use the similar `ansible-devel google group <https://groups.google.com/forum/#!forum/ansible-devel>`_.
Documentation updates for this module can also be edited directly in the module and by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.
For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`developing_test_pr` and :doc:`developing_modules`.

64
docsite/rst/modules_intro.rst Normal file
View file

@ -0,0 +1,64 @@
Introduction
============
Modules (also referred to as "task plugins" or "library plugins") are the ones that do
the actual work in ansible, they are what gets executed in each playbook task.
But you can also run a single one using the 'ansible' command.
Let's review how we execute three different modules from the command line::
ansible webservers -m service -a "name=httpd state=started"
ansible webservers -m ping
ansible webservers -m command -a "/sbin/reboot -t now"
Each module supports taking arguments. Nearly all modules take ``key=value``
arguments, space delimited. Some modules take no arguments, and the command/shell modules simply
take the string of the command you want to run.
From playbooks, Ansible modules are executed in a very similar way::
- name: reboot the servers
action: command /sbin/reboot -t now
Which can be abbreviated to::
- name: reboot the servers
command: /sbin/reboot -t now
Another way to pass arguments to a module is using yaml syntax also called 'complex args' ::
- name: restart webserver
service:
name: httpd
state: restarted
All modules technically return JSON format data, though if you are using the command line or playbooks, you don't really need to know much about
that. If you're writing your own module, you care, and this means you do not have to write modules in any particular language -- you get to choose.
Modules strive to be `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made. When using Ansible
playbooks, these modules can trigger 'change events' in the form of notifying 'handlers' to run additional tasks.
Documentation for each module can be accessed from the command line with the ansible-doc tool::
ansible-doc yum
A list of all installed modules is also available::
ansible-doc -l
.. seealso::
:doc:`intro_adhoc`
Examples of using modules in /usr/bin/ansible
:doc:`playbooks`
Examples of using modules with /usr/bin/ansible-playbook
:doc:`developing_modules`
How to write your own modules
:doc:`developing_api`
Examples of using modules with the Python API
`Mailing List <http://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

2
docsite/rst/playbooks.rst
View file

@ -24,6 +24,8 @@ It is recommended to look at `Example Playbooks <https://github.com/ansible/ansi
playbooks_filters
playbooks_conditionals
playbooks_loops
playbooks_blocks
playbooks_strategies
playbooks_best_practices

2
docsite/rst/playbooks_async.rst
View file

@ -77,7 +77,7 @@ following::
.. note::
If the value of ``async:`` is not high enough, this will cause the
"check on it later" task to fail because the temporary status file that
the ``async_status:`` is looking for will not have been written
the ``async_status:`` is looking for will not have been written or no longer exist
.. seealso::

18
docsite/rst/playbooks_best_practices.rst
View file

@ -28,7 +28,7 @@ Directory Layout
The top level of the directory would contain files and directories like so::
production # inventory file for production servers
stage # inventory file for stage environment
staging # inventory file for staging environment
group_vars/
group1 # here we assign variables to particular groups
@ -78,10 +78,10 @@ If you are using a cloud provider, you should not be managing your inventory in
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.
.. _stage_vs_prod:
.. _staging_vs_prod:
How to Differentiate Stage vs Production
`````````````````````````````````````````
How to Differentiate Staging vs Production
``````````````````````````````````````````
If managing static inventory, it is frequently asked how to differentiate different types of environments. The following example
shows a good way to do this. Similar methods of grouping could be adapted to dynamic inventory (for instance, consider applying the AWS
@ -285,14 +285,14 @@ all the time -- you can have situational plays that you use at different times a
Ansible allows you to deploy and configure using the same tool, so you would likely reuse groups and just
keep the OS configuration in separate playbooks from the app deployment.
.. _stage_vs_production:
.. _staging_vs_production:
Stage vs Production
+++++++++++++++++++
Staging vs Production
+++++++++++++++++++++
As also mentioned above, a good way to keep your stage (or testing) and production environments separate is to use a separate inventory file for stage and production. This way you pick with -i what you are targeting. Keeping them all in one file can lead to surprises!
As also mentioned above, a good way to keep your staging (or testing) and production environments separate is to use a separate inventory file for staging and production. This way you pick with -i what you are targeting. Keeping them all in one file can lead to surprises!
Testing things in a stage environment before trying in production is always a great idea. Your environments need not be the same
Testing things in a staging environment before trying in production is always a great idea. Your environments need not be the same
size and you can use group variables to control the differences between those environments.
.. _rolling_update:

78
docsite/rst/playbooks_blocks.rst Normal file
View file

@ -0,0 +1,78 @@
Blocks
======
In 2.0 we added a block feature to allow for logical grouping of tasks and even
in play error handling. Most of what you can apply to a single task can be applied
at the block level, which also makes it much easier to set data or directives common
to the tasks.
.. code-block:: YAML
:emphasize-lines: 2
:caption: Block example
tasks:
- block:
- yum: name={{ item }} state=installed
with_items:
- httpd
- memcached
- template: src=templates/src.j2 dest=/etc/foo.conf
- service: name=bar state=started enabled=True
when: ansible_distribution == 'CentOS'
become: true
become_user: root
In the example above the 3 tasks will be executed only when the block's when condition is met and enables
privilege escalation for all the enclosed tasks.
.. _block_error_handling:
Error Handling
``````````````
About Blocks
Blocks also introduce the ability to handle errors in a way similar to exceptions in most programming languages.
.. code-block:: YAML
:emphasize-lines: 2,6,10
:caption: Block error handling example
tasks:
- block:
- debug: msg='i execute normally'
- command: /bin/false
- debug: msg='i never execute, cause ERROR!'
rescue:
- debug: msg='I caught an error'
- command: /bin/false
- debug: msg='I also never execute :-('
always:
- debug: msg="this always executes"
The tasks in the ``block`` would execute normally, if there is any error the ``rescue`` section would get executed
with whatever you need to do to recover from the previous error. The ``always`` section runs no matter what previous
error did or did not occur in the ``block`` and ``rescue`` sections.
.. seealso::
:doc:`playbooks`
An introduction to playbooks
:doc:`playbooks_roles`
Playbook organization by roles
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

7
docsite/rst/playbooks_conditionals.rst
View file

@ -90,7 +90,7 @@ If a required variable has not been set, you can skip or fail using Jinja2's
when: foo is defined
- fail: msg="Bailing out. this play requires 'bar'"
when: bar is not defined
when: bar is undefined
This is especially useful in combination with the conditional import of vars
files (see below).
@ -119,12 +119,13 @@ Applying 'when' to roles and includes
`````````````````````````````````````
Note that if you have several tasks that all share the same conditional statement, you can affix the conditional
to a task include statement as below. Note this does not work with playbook includes, just task includes. All the tasks
get evaluated, but the conditional is applied to each and every task::
to a task include statement as below. All the tasks get evaluated, but the conditional is applied to each and every task::
- include: tasks/sometasks.yml
when: "'reticulating splines' in output"
.. note:: In versions prior to 2.0 this worked with task includes but not playbook includes. 2.0 allows it to work with both.
Or with a role::
- hosts: webservers

4
docsite/rst/playbooks_delegation.rst
View file

@ -9,7 +9,7 @@ This in particular is very applicable when setting up continuous deployment infr
Additional features allow for tuning the orders in which things complete, and assigning a batch window size for how many machines to process at once during a rolling update.
This section covers all of these features. For examples of these items in use, `please see the ansible-examples repository <http://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.
@ -189,7 +189,7 @@ use the default remote connection type::
:doc:`playbooks`
An introduction to playbooks
`Ansible Examples on GitHub <http://github.com/ansible/ansible-examples>`_
`Ansible Examples on GitHub <https://github.com/ansible/ansible-examples>`_
Many examples of full-stack deployments
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!

45
docsite/rst/playbooks_filters.rst
View file

@ -3,6 +3,7 @@ Jinja2 filters
.. contents:: Topics
Filters in Jinja2 are a way of transforming template expressions from one kind of data into another. Jinja2
ships with many of these. See `builtin filters`_ in the official Jinja2 template documentation.
@ -16,9 +17,27 @@ Filters For Formatting Data
The following filters will take a data structure in a template and render it in a slightly different format. These
are occasionally useful for debugging::
{{ some_variable | to_json }}
{{ some_variable | to_yaml }}
For human readable output, you can use::
{{ some_variable | to_nice_json }}
{{ some_variable | to_nice_yaml }}
Alternatively, you may be reading in some already formatted data::
{{ some_variable | from_json }}
{{ some_variable | from_yaml }}
for example::
tasks:
- shell: cat /some/path/to/file.json
register: result
- set_fact: myvar="{{ result.stdout | from_json }}"
.. _filters_used_with_conditionals:
Filters Often Used With Conditionals
@ -91,6 +110,10 @@ As of Ansible 1.8, it is possible to use the default filter to omit variables an
For the first two files in the list, the default mode will be determined by the umask of the system as the `mode=`
parameter will not be sent to the file module while the final file will receive the `mode=0444` option.
.. note:: If you are "chaining" additional filters after the `default(omit)` filter, you should instead do something like this:
`"{{ foo | default(None) | some_filter or omit }}"`. In this example, the default `None` (python null) value will cause the
later filters to fail, which will trigger the `or omit` portion of the logic. Using omit in this manner is very specific to
the later filters you're chaining though, so be prepared for some trial and error if you do this.
.. _list_filters:
@ -299,7 +322,11 @@ Hash types available depend on the master system running ansible,
Other Useful Filters
--------------------
To use one value on true and another on false (since 1.9)::
To add quotes for shell usage::
- shell: echo={{ string_value | quote }}
To use one value on true and another on false (new in version 1.9)::
{{ (name == "John") | ternary('Mr','Ms') }}
@ -323,6 +350,15 @@ To get the real path of a link (new in version 1.8)::
{{ path | realpath }}
To get the relative path of a link, from a start point (new in version 1.7)::
{{ path | relpath('/etc') }}
To get the root and extension of a path or filename (new in version 2.0)::
# with path == 'nginx.conf' the return would be ('nginx', '.conf')
{{ path | splitext }}
To work with Base64 encoded strings::
{{ encoded | b64decode }}
@ -352,6 +388,8 @@ To match strings against a regex, use the "match" or "search" filter::
'match' will require a complete match in the string, while 'search' will require a match inside of the string.
.. versionadded:: 1.6
To replace text in a string with regex, use the "regex_replace" filter::
# convert "ansible" to "able"
@ -363,6 +401,11 @@ To replace text in a string with regex, use the "regex_replace" filter::
.. note:: If "regex_replace" filter is used with variables inside YAML arguments (as opposed to simpler 'key=value' arguments),
then you need to escape backreferences (e.g. ``\\1``) with 4 backslashes (``\\\\``) instead of 2 (``\\``).
To escape special characters within a regex, use the "regex_escape" filter::
# convert '^f.*o(.*)$' to '\^f\.\*o\(\.\*\)\$'
{{ '^f.*o(.*)$' | regex_escape() }}
A few useful filters are typically added with each new Ansible release. The development documentation shows
how to extend Ansible filters by writing your own as plugins, though in general, we encourage new ones
to be added to core so everyone can make use of them.

40
docsite/rst/playbooks_intro.rst
View file

@ -106,6 +106,33 @@ YAML dictionaries to supply the modules with their key=value arguments.::
name: httpd
state: restarted
Playbooks can contain multiple plays. You may have a playbook that targets first
the web servers, and then the database servers. For example::
---
- hosts: webservers
remote_user: root
tasks:
- name: ensure apache is at the latest version
yum: pkg=httpd state=latest
- name: write the apache config file
template: src=/srv/httpd.j2 dest=/etc/httpd.conf
- hosts: databases
remote_user: root
tasks:
- name: ensure postgresql is at the latest version
yum: name=postgresql state=latest
- name: ensure that postgresql is started
service: name=postgresql state=running
You can use this method to switch between the host group you're targeting,
the username logging into the remote servers, whether to sudo or not, and so
forth. Plays, like tasks, run in the order specified in the playbook: top to
bottom.
Below, we'll break down what the various features of the playbook language are.
.. _playbook_basics:
@ -338,10 +365,10 @@ The things listed in the 'notify' section of a task are called
handlers.
Handlers are lists of tasks, not really any different from regular
tasks, that are referenced by name. Handlers are what notifiers
notify. If nothing notifies a handler, it will not run. Regardless
of how many things notify a handler, it will run only once, after all
of the tasks complete in a particular play.
tasks, that are referenced by a globally unique name. Handlers are
what notifiers notify. If nothing notifies a handler, it will not
run. Regardless of how many things notify a handler, it will run only
once, after all of the tasks complete in a particular play.
Here's an example handlers section::
@ -355,7 +382,10 @@ Handlers are best used to restart services and trigger reboots. You probably
won't need them for much else.
.. note::
Notify handlers are always run in the order written.
* Notify handlers are always run in the order written.
* Handler names live in a global namespace.
* If two handler tasks have the same name, only one will run.
`* <https://github.com/ansible/ansible/issues/4943>`_
Roles are described later on. It's worthwhile to point out that handlers are
automatically processed between 'pre_tasks', 'roles', 'tasks', and 'post_tasks'

2
docsite/rst/playbooks_lookups.rst
View file

@ -237,7 +237,7 @@ Here are some examples::
# The following lookups were added in 1.9
- debug: msg="{{item}}"
with_url:
- 'http://github.com/gremlin.keys'
- 'https://github.com/gremlin.keys'
# outputs the cartesian product of the supplied lists
- debug: msg="{{item}}"

63
docsite/rst/playbooks_loops.rst
View file

@ -23,7 +23,7 @@ To save some typing, repeated tasks can be written in short-hand like so::
If you have defined a YAML list in a variables file, or the 'vars' section, you can also do::
with_items: somelist
with_items: "{{somelist}}"
The above would be the equivalent of::
@ -58,12 +58,12 @@ Loops can be nested as well::
- [ 'alice', 'bob' ]
- [ 'clientdb', 'employeedb', 'providerdb' ]
As with the case of 'with_items' above, you can use previously defined variables. Just specify the variable's name without templating it with '{{ }}'::
As with the case of 'with_items' above, you can use previously defined variables.::
- name: here, 'users' contains the above list of employees
mysql_user: name={{ item[0] }} priv={{ item[1] }}.*:ALL append_privs=yes password=foo
with_nested:
- users
- "{{users}}"
- [ 'clientdb', 'employeedb', 'providerdb' ]
.. _looping_over_hashes:
@ -89,7 +89,7 @@ And you want to print every user's name and phone number. You can loop through
tasks:
- name: Print phone records
debug: msg="User {{ item.key }} is {{ item.value.name }} ({{ item.value.telephone }})"
with_dict: users
with_dict: "{{users}}"
.. _looping_over_fileglobs:
@ -111,7 +111,7 @@ be used like this::
- copy: src={{ item }} dest=/etc/fooapp/ owner=root mode=600
with_fileglob:
- /playbooks/files/fooapp/*
.. note:: When using a relative path with ``with_fileglob`` in a role, Ansible resolves the path relative to the `roles/<rolename>/files` directory.
Looping over Parallel Sets of Data
@ -130,40 +130,71 @@ And you want the set of '(a, 1)' and '(b, 2)' and so on. Use 'with_together' t
tasks:
- debug: msg="{{ item.0 }} and {{ item.1 }}"
with_together:
- alpha
- numbers
- "{{alpha}}"
- "{{numbers}}"
Looping over Subelements
````````````````````````
Suppose you want to do something like loop over a list of users, creating them, and allowing them to login by a certain set of
SSH keys.
SSH keys.
How might that be accomplished? Let's assume you had the following defined and loaded in via "vars_files" or maybe a "group_vars/all" file::
---
users:
- name: alice
authorized:
authorized:
- /tmp/alice/onekey.pub
- /tmp/alice/twokey.pub
mysql:
password: mysql-password
hosts:
- "%"
- "127.0.0.1"
- "::1"
- "localhost"
privs:
- "*.*:SELECT"
- "DB1.*:ALL"
- name: bob
authorized:
- /tmp/bob/id_rsa.pub
mysql:
password: other-mysql-password
hosts:
- "db1"
privs:
- "*.*:SELECT"
- "DB2.*:ALL"
It might happen like so::
- user: name={{ item.name }} state=present generate_ssh_key=yes
with_items: users
with_items: "{{users}}"
- authorized_key: "user={{ item.0.name }} key='{{ lookup('file', item.1) }}'"
with_subelements:
- users
- authorized
Subelements walks a list of hashes (aka dictionaries) and then traverses a list with a given key inside of those
Given the mysql hosts and privs subkey lists, you can also iterate over a list in a nested subkey::
- name: Setup MySQL users
mysql_user: name={{ item.0.user }} password={{ item.0.mysql.password }} host={{ item.1 }} priv={{ item.0.mysql.privs | join('/') }}
with_subelements:
- users
- mysql.hosts
Subelements walks a list of hashes (aka dictionaries) and then traverses a list with a given (nested sub-)key inside of those
records.
Optionally, you can add a third element to the subelements list, that holds a
dictionary of flags. Currently you can add the 'skip_missing' flag. If set to
True, the lookup plugin will skip the lists items that do not contain the given
subkey. Without this flag, or if that flag is set to False, the plugin will
yield an error and complain about the missing subkey.
The authorized_key pattern is exactly where it comes up most.
.. _looping_over_integer_sequences:
@ -298,7 +329,7 @@ Should you ever need to execute a command remotely, you would not use the above
- name: Do something with each result
shell: /usr/bin/something_else --param {{ item }}
with_items: command_result.stdout_lines
with_items: "{{command_result.stdout_lines}}"
.. _indexed_lists:
@ -314,7 +345,7 @@ It's uncommonly used::
- name: indexed loop demo
debug: msg="at array position {{ item.0 }} there is a value {{ item.1 }}"
with_indexed_items: some_list
with_indexed_items: "{{some_list}}"
.. _using_ini_with_a_loop:
@ -387,8 +418,8 @@ As you can see the formatting of packages in these lists is all over the place.
- name: flattened loop demo
yum: name={{ item }} state=installed
with_flattened:
- packages_base
- packages_apps
- "{{packages_base}}"
- "{{packages_apps}}"
That's how!
@ -452,7 +483,7 @@ Subsequent loops over the registered variable to inspect the results may look li
fail:
msg: "The command ({{ item.cmd }}) did not have a 0 return code"
when: item.rc != 0
with_items: echo.results
with_items: "{{echo.results}}"
.. _writing_your_own_iterators:

9
docsite/rst/playbooks_prompts.rst
View file

@ -20,9 +20,12 @@ Here is a most basic example::
from: "camelot"
vars_prompt:
name: "what is your name?"
quest: "what is your quest?"
favcolor: "what is your favorite color?"
- name: "name"
prompt: "what is your name?"
- name: "quest"
prompt: "what is your quest?"
- name: "favcolor"
prompt: "what is your favorite color?"
If you have a variable that changes infrequently, it might make sense to
provide a default value that can be overridden. This can be accomplished using

1
docsite/rst/playbooks_special_topics.rst
View file

@ -7,6 +7,7 @@ and adopt these only if they seem relevant or useful to your environment.
.. toctree::
:maxdepth: 1
become
playbooks_acceleration
playbooks_async
playbooks_checkmode

39
docsite/rst/playbooks_strategies.rst Normal file
View file

@ -0,0 +1,39 @@
Strategies
===========
In 2.0 we added a new way to control play execution, ``strategy``, by default plays will
still run as they used to, with what we call the ``linear`` strategy. All hosts will run each
task before any host starts the next task, using the number of forks (default 5) to parallelize.
The ``serial`` directive can 'batch' this behaviour to a subset of the hosts, which then run to
completion of the play before the next 'batch' starts.
A second ``strategy`` ships with ansible ``free``, which allows each host to run until the end of
the play as fast as it can.::
- hosts: all
strategy: free
tasks:
...
.. _strategy_plugins:
Strategy Plugins
`````````````````
The strategies are implelented via a new type of plugin, this means that in the future new
execution types can be added, either locally by users or to Ansible itself by
a code contribution.
.. seealso::
:doc:`playbooks`
An introduction to playbooks
:doc:`playbooks_roles`
Playbook organization by roles
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

5
docsite/rst/playbooks_tags.rst
View file

@ -38,8 +38,9 @@ And you may also tag basic include statements::
- include: foo.yml tags=web,foo
Both of these have the function of tagging every single task inside the include statement.
Both of these apply the specified tags to every task inside the included
file or role, so that these tasks can be selectively run when the playbook
is invoked with the corresponding tags.
Special Tags
````````````

33
docsite/rst/playbooks_variables.rst
View file

@ -308,7 +308,7 @@ This will return a ginormous amount of variable data, which may look like this,
"type": "ether"
},
"ansible_form_factor": "Other",
"ansible_fqdn": "ubuntu2",
"ansible_fqdn": "ubuntu2.example.com",
"ansible_hostname": "ubuntu2",
"ansible_interfaces": [
"lo",
@ -353,6 +353,7 @@ This will return a ginormous amount of variable data, which may look like this,
"size_total": 20079898624
}
],
"ansible_nodename": "ubuntu2.example.com",
"ansible_os_family": "Debian",
"ansible_pkg_mgr": "apt",
"ansible_processor": [
@ -387,8 +388,11 @@ In the above the model of the first harddrive may be referenced in a template or
Similarly, the hostname as the system reports it is::
{{ ansible_hostname }}
{{ ansible_nodename }}
and the unqualified hostname shows the string before the first period(.)::
{{ ansible_hostname }}
Facts are frequently used in conditionals (see :doc:`playbooks_conditionals`) and also in templates.
@ -494,7 +498,11 @@ not be necessary to "hit" all servers to reference variables and information abo
With fact caching enabled, it is possible for machine in one group to reference variables about machines in the other group, despite
the fact that they have not been communicated with in the current execution of /usr/bin/ansible-playbook.
To configure fact caching, enable it in ansible.cfg as follows::
To benefit from cached facts, you will want to change the 'gathering' setting to 'smart' or 'explicit' or set 'gather_facts' to False in most plays.
Currently, Ansible ships with two persistent cache plugins: redis and jsonfile.
To configure fact caching using redis, enable it in ansible.cfg as follows::
[defaults]
gathering = smart
@ -502,9 +510,6 @@ To configure fact caching, enable it in ansible.cfg as follows::
fact_caching_timeout = 86400
# seconds
You might also want to change the 'gathering' setting to 'smart' or 'explicit' or set gather_facts to False in most plays.
At the time of writing, Redis is the only supported fact caching engine.
To get redis up and running, perform the equivalent OS commands::
yum install redis
@ -515,6 +520,18 @@ Note that the Python redis library should be installed from pip, the version pac
In current embodiments, this feature is in beta-level state and the Redis plugin does not support port or password configuration, this is expected to change in the near future.
To configure fact caching using jsonfile, enable it in ansible.cfg as follows::
[defaults]
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /path/to/cachedir
fact_caching_timeout = 86400
# seconds
`fact_caching_connection` is a local filesystem path to a writeable
directory (ansible will attempt to create the directory if one does not exist).
.. _registered_variables:
Registered Variables
@ -614,6 +631,8 @@ Don't worry about any of this unless you think you need it. You'll know when yo
Also available, *inventory_dir* is the pathname of the directory holding Ansible's inventory host file, *inventory_file* is the pathname and the filename pointing to the Ansible's inventory host file.
And finally, *role_path* will return the current role's pathname (since 1.8). This will only work inside a role.
.. _variable_file_separation_details:
Variable File Separation
@ -782,7 +801,7 @@ Parameterized roles are useful.
If you are using a role and want to override a default, pass it as a parameter to the role like so::
roles:
- { name: apache, http_port: 8080 }
- { role: apache, http_port: 8080 }
This makes it clear to the playbook reader that you've made a conscious choice to override some default in the role, or pass in some
configuration that the role can't assume by itself. It also allows you to pass something site-specific that isn't really part of the

4
docsite/rst/playbooks_vault.rst
View file

@ -5,7 +5,7 @@ Vault
New in Ansible 1.5, "Vault" is a feature of ansible that allows keeping sensitive data such as passwords or keys in encrypted files, rather than as plaintext in your playbooks or roles. These vault files can then be distributed or placed in source control.
To enable this feature, a command line tool, `ansible-vault` is used to edit files, and a command line flag `--ask-vault-pass` or `--vault-password-file` is used.
To enable this feature, a command line tool, `ansible-vault` is used to edit files, and a command line flag `--ask-vault-pass` or `--vault-password-file` is used. Alternately, you may specify the location of a password file in your ansible.cfg file. This option requires no command line flag usage.
.. _what_can_be_encrypted_with_vault:
@ -14,7 +14,7 @@ What Can Be Encrypted With Vault
The vault feature can encrypt any structured data file used by Ansible. This can include "group_vars/" or "host_vars/" inventory variables, variables loaded by "include_vars" or "vars_files", or variable files passed on the ansible-playbook command line with "-e @file.yml" or "-e @file.json". Role variables and defaults are also included!
Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with vault. If you'd like to not betray what variables you are even using, you can go as far to keep an individual task file entirely encrypted. However, that might be a little much and could annoy your coworkers :)
Ansible tasks, handlers, and so on are also data so these can be encrypted with vault as well. To hide the names of variables that you're using, you can encrypt the task files in their entirety. However, that might be a little too much and could annoy your coworkers :)
.. _creating_files:

2
docsite/rst/quickstart.rst
View file

@ -3,7 +3,7 @@ Quickstart Video
We've recorded a short video that shows how to get started with Ansible that you may like to use alongside the documentation.
The `quickstart video <http://ansible.com/ansible-resources>`_ is about 30 minutes long and will show you some of the basics about your
The `quickstart video <http://ansible.com/resources>`_ is about 30 minutes long and will show you some of the basics about your
first steps with Ansible.
Enjoy, and be sure to visit the rest of the documentation to learn more.

16
docsite/rst/test_strategies.rst
View file

@ -19,16 +19,16 @@ also very easy to run the steps on the localhost or testing servers. Ansible let
The Right Level of Testing
``````````````````````````
Ansible resources are models of desired-state. As such, it should not be necessary to test that services are running, packages are
Ansible resources are models of desired-state. As such, it should not be necessary to test that services are started, packages are
installed, or other such things. Ansible is the system that will ensure these things are declaratively true. Instead, assert these
things in your playbooks.
.. code-block:: yaml
tasks:
- service: name=foo state=running enabled=yes
- service: name=foo state=started enabled=yes
If you think the service may not be running, the best thing to do is request it to be running. If the service fails to start, Ansible
If you think the service may not be started, the best thing to do is request it to be started. If the service fails to start, Ansible
will yell appropriately. (This should not be confused with whether the service is doing something functional, which we'll show more about how to
do later).
@ -114,14 +114,14 @@ Testing Lifecycle
If writing some degree of basic validation of your application into your playbooks, they will run every time you deploy.
As such, deploying into a local development VM and a stage environment will both validate that things are according to plan
As such, deploying into a local development VM and a staging environment will both validate that things are according to plan
ahead of your production deploy.
Your workflow may be something like this::
- Use the same playbook all the time with embedded tests in development
- Use the playbook to deploy to a stage environment (with the same playbooks) that simulates production
- Run an integration test battery written by your QA team against stage
- Use the playbook to deploy to a staging environment (with the same playbooks) that simulates production
- Run an integration test battery written by your QA team against staging
- Deploy to production, with the same integrated tests.
Something like an integration test battery should be written by your QA team if you are a production webservice. This would include
@ -213,7 +213,7 @@ If desired, the above techniques may be extended to enable continuous deployment
The workflow may look like this::
- Write and use automation to deploy local development VMs
- Have a CI system like Jenkins deploy to a stage environment on every code change
- Have a CI system like Jenkins deploy to a staging environment on every code change
- The deploy job calls testing scripts to pass/fail a build on every deploy
- If the deploy job succeeds, it runs the same deploy playbook against production inventory
@ -241,7 +241,7 @@ as part of a Continuous Integration/Continuous Delivery pipeline, as is covered
The focus should not be on infrastructure testing, but on application testing, so we strongly encourage getting together with your
QA team and ask what sort of tests would make sense to run every time you deploy development VMs, and which sort of tests they would like
to run against the stage environment on every deploy. Obviously at the development stage, unit tests are great too. But don't unit
to run against the staging environment on every deploy. Obviously at the development stage, unit tests are great too. But don't unit
test your playbook. Ansible describes states of resources declaratively, so you don't have to. If there are cases where you want
to be sure of something though, that's great, and things like stat/assert are great go-to modules for that purpose.