mirror of https://github.com/ansible/ansible.git
moar docs
added docs for new v2 features restructures modules bar and core/extras info into their own pages changed templates to refer to the new pages added some missing ansible.cfg options more info on gathering settingpull/11637/head
Brian Coca
9 years ago
parent
e49d8b9582
commit
173f27531c
@ -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 this 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 by submitting a pull request to the module source code, just look for the "DOCUMENTATION" block in the source tree.
|
||||
@ -0,0 +1,23 @@
|
||||
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 of this module 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 this 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 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`.
|
||||
|
||||
@ -0,0 +1,64 @@
|
||||
Introduction
|
||||
============
|
||||
|
||||
Modules (also reffered 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
|
||||
|
||||
@ -0,0 +1,72 @@
|
||||
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.
|
||||
|
||||
|
||||
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.::
|
||||
|
||||
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 whatver 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
|
||||
|
||||
|
||||
|
||||
|
||||
@ -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 befor any host starts the next task, using the number of forks (default 5) to paralelize.
|
||||
|
||||
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:
|
||||
|
||||
Stratergy Plugins
|
||||
`````````````````
|
||||
|
||||
The strategies are implelented via a new type of plugin, this means that in the future new
|
||||
execution types can be added in the future, 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
|
||||
|
||||
Loading…
Reference in New Issue