1af7c6c003
* Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commitc586d436fa) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commitbc6461432e) * Update intro_patterns.rst (#71542) Call out the trailing comma when specifying a single host. Small snag that took me a while to notice. (cherry picked from commitec3920cef1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit215eb730e1) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commitf75223d2c6) * User guide overhaul, Table of Contents (#71553) (cherry picked from commitb694dbadfe) * update backport instructions for 2.11 (#71567) * update backport instructions in docs/docsite/rst/community/development_process.rst Co-authored-by: Matt Martz <matt@sivel.net> (cherry picked from commit7f9258b024) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit96aee766f4) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit29b20bd1b1) Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Amin Vakil <info@aminvakil.com> Co-authored-by: Matt Deacalion <matt@dirtymonkey.co.uk> Co-authored-by: Fabien Malfoy <fabien.malfoy@laposte.net> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
52 lines
2.3 KiB
ReStructuredText
52 lines
2.3 KiB
ReStructuredText
.. _intro_modules:
|
|
|
|
Introduction to modules
|
|
=======================
|
|
|
|
Modules (also referred to as "task plugins" or "library plugins") are discrete units of code that can be used from the command line or in a playbook task. Ansible executes each module, usually on the remote managed node, and collects return values. In Ansible 2.10 and later, most modules are hosted in collections.
|
|
|
|
You can execute 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
|
|
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 return JSON format data. This means modules can be written in any programming language. Modules should be idempotent, and should avoid making any changes if they detect that the current state matches the desired final state. When used in an Ansible playbook, modules can trigger 'change events' in the form of notifying :ref:`handlers <handlers>` to run additional tasks.
|
|
|
|
You can access the documentation for each module from the command line with the ansible-doc tool::
|
|
|
|
ansible-doc yum
|
|
|
|
For a list of all available modules, see the :ref:`Collection docs <list_of_collections>`, or run the following at a command prompt::
|
|
|
|
ansible-doc -l
|
|
|
|
|
|
.. seealso::
|
|
|
|
:ref:`intro_adhoc`
|
|
Examples of using modules in /usr/bin/ansible
|
|
:ref:`working_with_playbooks`
|
|
Examples of using modules with /usr/bin/ansible-playbook
|
|
:ref:`developing_modules`
|
|
How to write your own modules
|
|
:ref:`developing_api`
|
|
Examples of using modules with the Python API
|
|
`Mailing List <https://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
|