@@ -199,6 +208,8 @@ These 'facts' will be available to all statements called after that module (but
...
@@ -199,6 +208,8 @@ These 'facts' will be available to all statements called after that module (but
A good idea might be make a module called 'site_facts' and always call it at the top of each playbook, though
A good idea might be make a module called 'site_facts' and always call it at the top of each playbook, though
we're always open to improving the selection of core facts in Ansible as well.
we're always open to improving the selection of core facts in Ansible as well.
.. _common_module_boilerplate:
Common Module Boilerplate
Common Module Boilerplate
`````````````````````````
`````````````````````````
...
@@ -248,6 +259,8 @@ can function outside of Ansible.
...
@@ -248,6 +259,8 @@ can function outside of Ansible.
If submitting a module to ansible's core code, which we encourage, use of the AnsibleModule
If submitting a module to ansible's core code, which we encourage, use of the AnsibleModule
class is required.
class is required.
.. _developing_for_check_mode:
Check Mode
Check Mode
``````````
``````````
.. versionadded:: 1.1
.. versionadded:: 1.1
...
@@ -274,6 +287,8 @@ system state is altered when the user enables check mode.
...
@@ -274,6 +287,8 @@ system state is altered when the user enables check mode.
If your module does not support check mode, when the user runs Ansible in check
If your module does not support check mode, when the user runs Ansible in check
mode, your module will simply be skipped.
mode, your module will simply be skipped.
.. _module_dev_pitfalls:
Common Pitfalls
Common Pitfalls
```````````````
```````````````
...
@@ -295,6 +310,8 @@ will still be shown in Ansible, but the command will not succeed.
...
@@ -295,6 +310,8 @@ will still be shown in Ansible, but the command will not succeed.
Always use the hacking/test-module script when developing modules and it will warn
Always use the hacking/test-module script when developing modules and it will warn
you about these kind of things.
you about these kind of things.
.. _module_dev_conventions:
Conventions/Recommendations
Conventions/Recommendations
```````````````````````````
```````````````````````````
...
@@ -321,6 +338,8 @@ and guidelines:
...
@@ -321,6 +338,8 @@ and guidelines:
* As results from many hosts will be aggregrated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form.
* As results from many hosts will be aggregrated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form.
.. _module_dev_shorthand:
Shorthand Vs JSON
Shorthand Vs JSON
`````````````````
`````````````````
...
@@ -334,6 +353,7 @@ will know what to do::
...
@@ -334,6 +353,7 @@ will know what to do::
If you're writing a module in Python or Ruby or whatever, though, returning
If you're writing a module in Python or Ruby or whatever, though, returning
JSON is probably the simplest way to go.
JSON is probably the simplest way to go.
.. _module_documenting:
Documenting Your Module
Documenting Your Module
```````````````````````
```````````````````````
...
@@ -344,6 +364,8 @@ which conforms to the schema defined below. You may find it easier to
...
@@ -344,6 +364,8 @@ which conforms to the schema defined below. You may find it easier to
start writing your ``DOCUMENTATION`` string in an editor with YAML
start writing your ``DOCUMENTATION`` string in an editor with YAML
syntax highlighting before you include it in your Python file.
syntax highlighting before you include it in your Python file.
.. _module_doc_example:
Example
Example
+++++++
+++++++
...
@@ -384,6 +406,8 @@ The ``module_formatter.py`` script and ``ansible-doc(1)`` append the
...
@@ -384,6 +406,8 @@ The ``module_formatter.py`` script and ``ansible-doc(1)`` append the
``EXAMPLES`` blob after any existing (deprecated) ``examples`` you may have in the
``EXAMPLES`` blob after any existing (deprecated) ``examples`` you may have in the
YAML ``DOCUMENTATION`` string.
YAML ``DOCUMENTATION`` string.
.. _module_dev_testing:
Building & Testing
Building & Testing
++++++++++++++++++
++++++++++++++++++
...
@@ -418,6 +442,8 @@ output formats available:
...
@@ -418,6 +442,8 @@ output formats available:
You can use ANSIBLE_KEEP_REMOTE_FILES=1 to prevent ansible from
You can use ANSIBLE_KEEP_REMOTE_FILES=1 to prevent ansible from
deleting the remote files so you can debug your module.
deleting the remote files so you can debug your module.
.. _module_contribution:
Getting Your Module Into Core
Getting Your Module Into Core
`````````````````````````````
`````````````````````````````
...
@@ -425,7 +451,8 @@ High-quality modules with minimal dependencies
...
@@ -425,7 +451,8 @@ High-quality modules with minimal dependencies
can be included in the core, but core modules (just due to the programming
can be included in the core, but core modules (just due to the programming
preferences of the developers) will need to be implemented in Python and use
preferences of the developers) will need to be implemented in Python and use
the AnsibleModule common code, and should generally use consistent arguments with the rest of
the AnsibleModule common code, and should generally use consistent arguments with the rest of
the program. Stop by the mailing list to inquire about requirements.
the program. Stop by the mailing list to inquire about requirements if you like, and submit