Adding some labels so we don't get "#id22" for the links in the docs.
parent
a74c0091b2
commit
198c9a5903
|
@ -9,6 +9,8 @@ API so you have a considerable amount of power across the board. This chapter d
|
||||||
.. contents:: `Table of contents`
|
.. contents:: `Table of contents`
|
||||||
:depth: 2
|
:depth: 2
|
||||||
|
|
||||||
|
.. _python_api:
|
||||||
|
|
||||||
Python API
|
Python API
|
||||||
----------
|
----------
|
||||||
|
|
||||||
|
@ -43,6 +45,8 @@ expressed in the 'ansible-modules' documentation.::
|
||||||
A module can return any type of JSON data it wants, so Ansible can
|
A module can return any type of JSON data it wants, so Ansible can
|
||||||
be used as a framework to rapidly build powerful applications and scripts.
|
be used as a framework to rapidly build powerful applications and scripts.
|
||||||
|
|
||||||
|
.. _detailed_api_example:
|
||||||
|
|
||||||
Detailed API Example
|
Detailed API Example
|
||||||
````````````````````
|
````````````````````
|
||||||
|
|
||||||
|
|
|
@ -8,6 +8,8 @@ How do we write a new one?
|
||||||
Simple! We just create a script or program that can return JSON in the right format when fed the proper arguments.
|
Simple! We just create a script or program that can return JSON in the right format when fed the proper arguments.
|
||||||
You can do this in any language.
|
You can do this in any language.
|
||||||
|
|
||||||
|
.. _inventory_script_conventions:
|
||||||
|
|
||||||
Script Conventions
|
Script Conventions
|
||||||
``````````````````
|
``````````````````
|
||||||
|
|
||||||
|
@ -46,6 +48,8 @@ if the script does not wish to do this, returning an empty hash/dictionary is th
|
||||||
"monitoring" : "pack.example.com"
|
"monitoring" : "pack.example.com"
|
||||||
}
|
}
|
||||||
|
|
||||||
|
.. _inventory_script_tuning:
|
||||||
|
|
||||||
Tuning the External Inventory Script
|
Tuning the External Inventory Script
|
||||||
````````````````````````````````````
|
````````````````````````````````````
|
||||||
|
|
||||||
|
|
|
@ -11,8 +11,11 @@ by `ANSIBLE_LIBRARY` or the ``--module-path`` command line option.
|
||||||
:depth: 2
|
:depth: 2
|
||||||
|
|
||||||
|
|
||||||
|
.. _module_dev_tutorial:
|
||||||
|
|
||||||
Tutorial
|
Tutorial
|
||||||
````````
|
````````
|
||||||
|
|
||||||
Let's build a module to get and set the system time. For starters, let's build
|
Let's build a module to get and set the system time. For starters, let's build
|
||||||
a module that just outputs the current time.
|
a module that just outputs the current time.
|
||||||
|
|
||||||
|
@ -45,6 +48,8 @@ Ok, let's get going with an example. We'll use Python. For starters, save this
|
||||||
"time" : date
|
"time" : date
|
||||||
})
|
})
|
||||||
|
|
||||||
|
.. _module_testing:
|
||||||
|
|
||||||
Testing Modules
|
Testing Modules
|
||||||
```````````````
|
```````````````
|
||||||
|
|
||||||
|
@ -63,6 +68,8 @@ You should see output that looks something like this::
|
||||||
|
|
||||||
If you did not, you might have a typo in your module, so recheck it and try again.
|
If you did not, you might have a typo in your module, so recheck it and try again.
|
||||||
|
|
||||||
|
.. _reading_input:
|
||||||
|
|
||||||
Reading Input
|
Reading Input
|
||||||
`````````````
|
`````````````
|
||||||
|
|
||||||
|
@ -176,6 +183,8 @@ This should return something like::
|
||||||
|
|
||||||
{"changed": true, "time": "2012-03-14 12:23:00.000307"}
|
{"changed": true, "time": "2012-03-14 12:23:00.000307"}
|
||||||
|
|
||||||
|
.. _module_provided_facts:
|
||||||
|
|
||||||
Module Provided 'Facts'
|
Module Provided 'Facts'
|
||||||
```````````````````````
|
```````````````````````
|
||||||
|
|
||||||
|
@ -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.
|
||||||
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.
|
||||||
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.
|
||||||
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:
|
||||||
|
|
||||||
* 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::
|
||||||
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
|
||||||
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
|
||||||
``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:
|
||||||
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
|
||||||
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
|
||||||
|
a github pull request to the main project.
|
||||||
|
|
||||||
.. seealso::
|
.. seealso::
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue