← Back to branch summary

~canonical-ci-engineering/ubuntu-ci-services-itself/ansible

« back to all changes in this revision

Viewing changes to docsite/latest/rst/modules.rst

  • Committer: Package Import Robot
  • Author(s): Michael Vogt
  • Date: 2013-11-24 10:41:27 UTC
  • mfrom: (1.1.3)
  • Revision ID: package-import@ubuntu.com-20131124104127-zppejr80jahk3av6
Tags: 1.4.0+dfsg-1
* new upstream version
* debian/rules:
  - remove sed manpage fixes, fixed upstream
* debian/patches/fix-html-makefile:
  - removed, fixed upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
docsite/latest/rst/modules.rst
1
 
Ansible Modules
2
 
===============
3
 
 
4
 
.. contents::
5
 
   :depth: 3
6
 
 
7
 
Introduction
8
 
````````````
9
 
 
10
 
 
11
 
Ansible ships with a number of modules (called the 'module library')
12
 
that can be executed directly on remote hosts or through :doc:`playbooks`.
13
 
Users can also write their own modules.   These modules can control system
14
 
resources, like services, packages, or files (anything really), or
15
 
handle executing system commands.
16
 
 
17
 
Let's review how we execute three different modules from the command line::
18
 
 
19
 
    ansible webservers -m service -a "name=httpd state=running"
20
 
    ansible webservers -m ping
21
 
    ansible webservers -m command -a "/sbin/reboot -t now"
22
 
 
23
 
Each module supports taking arguments.  Nearly all modules take ``key=value``
24
 
arguments, space delimited.  Some modules take no arguments, and the
25
 
command/shell modules simply take the string of the command you want to run.
26
 
 
27
 
From playbooks, Ansible modules are executed in a very similar way::
28
 
 
29
 
    - name: reboot the servers
30
 
      action: command /sbin/reboot -t now
31
 
 
32
 
Version 0.8 and higher support the following shorter syntax::
33
 
 
34
 
    - name: reboot the servers
35
 
      command: /sbin/reboot -t now
36
 
 
37
 
All modules technically return JSON format data, though if you are using the
38
 
command line or playbooks, you don't really need to know much about
39
 
that.  If you're writing your own module, you care, and this means you do
40
 
not have to write modules in any particular language -- you get to choose.
41
 
 
42
 
Modules are `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made.  When using Ansible
43
 
playbooks, these modules can trigger 'change events' in the form of notifying 'handlers'
44
 
to run additional tasks.
45
 
 
46
 
Documention for each module can be accessed from the command line with the
47
 
ansible-doc as well as the man command::
48
 
 
49
 
    ansible-doc command
50
 
 
51
 
    man ansible.template
52
 
 
53
 
Let's see what's available in the Ansible module library, out of the box:
54
 
 
55
 
 
56
 
.. include:: modules/_list.rst
57
 
 
58
 
 
59
 
Writing your own modules
60
 
````````````````````````
61
 
 
62
 
See :doc:`moduledev`.
63
 
 
64
 
.. seealso::
65
 
 
66
 
   :doc:`contrib`
67
 
       User contributed playbooks, modules, and articles
68
 
   :doc:`examples`
69
 
       Examples of using modules in /usr/bin/ansible
70
 
   :doc:`playbooks`
71
 
       Examples of using modules with /usr/bin/ansible-playbook
72
 
   :doc:`moduledev`
73
 
       How to write your own modules
74
 
   :doc:`api`
75
 
       Examples of using modules with the Python API
76
 
   `Mailing List <http://groups.google.com/group/ansible-project>`_
77
 
       Questions? Help? Ideas?  Stop by the list on Google Groups
78
 
   `irc.freenode.net <http://irc.freenode.net>`_
79
 
       #ansible IRC chat channel
80