ansible/docs/docsite/rst/dev_guide/developing_modules.rst

52 lines
3.4 KiB
ReStructuredText
Raw Normal View History

.. _developing_modules:
.. _module_dev_should_you:
2016-09-23 22:48:37 +02:00
****************************
Should you develop a module?
****************************
[docs][backport]Backportapalooza 10 (#71621) * Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commit c586d436fabc8033055d5195038ca3341d7f0192) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commit bc6461432ef4d0d9323d9b4355efd09e79c0a7b9) * 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 commit ec3920cef1692d54c08f1932cf0724239628aff1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit 215eb730e1e69f6f7e1566c610ac1b614c50854e) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commit f75223d2c6d38ae936a4b813190ff6324d361d7f) * User guide overhaul, Table of Contents (#71553) (cherry picked from commit b694dbadfe0774e1c0a0ad6c971ed8951c60326a) * 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 commit 7f9258b024cdd134d2a26a4879f24ac04dfbdb07) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit 96aee766f4c2ae2fe769d408a010834ef95dff71) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit 29b20bd1b135d18e9e7942555154ad24e2b1578b) 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>
2020-09-04 01:07:02 +02:00
Developing Ansible modules is easy, but often it is not necessary. Before you start writing a new module, ask:
2016-09-23 22:48:37 +02:00
1. Does a similar module already exist?
2016-09-23 22:48:37 +02:00
[docs][backport]Backportapalooza 10 (#71621) * Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commit c586d436fabc8033055d5195038ca3341d7f0192) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commit bc6461432ef4d0d9323d9b4355efd09e79c0a7b9) * 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 commit ec3920cef1692d54c08f1932cf0724239628aff1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit 215eb730e1e69f6f7e1566c610ac1b614c50854e) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commit f75223d2c6d38ae936a4b813190ff6324d361d7f) * User guide overhaul, Table of Contents (#71553) (cherry picked from commit b694dbadfe0774e1c0a0ad6c971ed8951c60326a) * 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 commit 7f9258b024cdd134d2a26a4879f24ac04dfbdb07) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit 96aee766f4c2ae2fe769d408a010834ef95dff71) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit 29b20bd1b135d18e9e7942555154ad24e2b1578b) 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>
2020-09-04 01:07:02 +02:00
An existing module may cover the functionality you want. Ansible collections include thousands of modules. Search our :ref:`list of included collections <list_of_collections>` or `Ansible Galaxy <https://galaxy.ansible.com>`_ to see if an existing module does what you need.
2016-09-23 22:48:37 +02:00
[docs][backport]Backportapalooza 10 (#71621) * Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commit c586d436fabc8033055d5195038ca3341d7f0192) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commit bc6461432ef4d0d9323d9b4355efd09e79c0a7b9) * 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 commit ec3920cef1692d54c08f1932cf0724239628aff1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit 215eb730e1e69f6f7e1566c610ac1b614c50854e) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commit f75223d2c6d38ae936a4b813190ff6324d361d7f) * User guide overhaul, Table of Contents (#71553) (cherry picked from commit b694dbadfe0774e1c0a0ad6c971ed8951c60326a) * 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 commit 7f9258b024cdd134d2a26a4879f24ac04dfbdb07) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit 96aee766f4c2ae2fe769d408a010834ef95dff71) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit 29b20bd1b135d18e9e7942555154ad24e2b1578b) 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>
2020-09-04 01:07:02 +02:00
2. Should you use or develop an action plugin instead of a module?
2016-09-23 22:48:37 +02:00
An action plugin may be the best way to get the functionality you want. Action plugins run on the control node instead of on the managed node, and their functionality is available to all modules. For more information about developing plugins, read the :ref:`developing plugins page <developing_plugins>`.
2016-09-23 22:48:37 +02:00
[docs][backport]Backportapalooza 10 (#71621) * Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commit c586d436fabc8033055d5195038ca3341d7f0192) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commit bc6461432ef4d0d9323d9b4355efd09e79c0a7b9) * 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 commit ec3920cef1692d54c08f1932cf0724239628aff1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit 215eb730e1e69f6f7e1566c610ac1b614c50854e) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commit f75223d2c6d38ae936a4b813190ff6324d361d7f) * User guide overhaul, Table of Contents (#71553) (cherry picked from commit b694dbadfe0774e1c0a0ad6c971ed8951c60326a) * 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 commit 7f9258b024cdd134d2a26a4879f24ac04dfbdb07) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit 96aee766f4c2ae2fe769d408a010834ef95dff71) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit 29b20bd1b135d18e9e7942555154ad24e2b1578b) 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>
2020-09-04 01:07:02 +02:00
3. Should you use a role instead of a module?
2016-09-23 22:48:37 +02:00
A combination of existing modules may cover the functionality you want. You can write a role for this type of use case. Check out the :ref:`roles documentation<playbooks_reuse_roles>`.
[docs][backport]Backportapalooza 10 (#71621) * Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commit c586d436fabc8033055d5195038ca3341d7f0192) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commit bc6461432ef4d0d9323d9b4355efd09e79c0a7b9) * 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 commit ec3920cef1692d54c08f1932cf0724239628aff1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit 215eb730e1e69f6f7e1566c610ac1b614c50854e) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commit f75223d2c6d38ae936a4b813190ff6324d361d7f) * User guide overhaul, Table of Contents (#71553) (cherry picked from commit b694dbadfe0774e1c0a0ad6c971ed8951c60326a) * 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 commit 7f9258b024cdd134d2a26a4879f24ac04dfbdb07) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit 96aee766f4c2ae2fe769d408a010834ef95dff71) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit 29b20bd1b135d18e9e7942555154ad24e2b1578b) 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>
2020-09-04 01:07:02 +02:00
4. Should you create a collection instead of a single module?
[docs][backport]Backportapalooza 10 (#71621) * Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commit c586d436fabc8033055d5195038ca3341d7f0192) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commit bc6461432ef4d0d9323d9b4355efd09e79c0a7b9) * 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 commit ec3920cef1692d54c08f1932cf0724239628aff1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit 215eb730e1e69f6f7e1566c610ac1b614c50854e) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commit f75223d2c6d38ae936a4b813190ff6324d361d7f) * User guide overhaul, Table of Contents (#71553) (cherry picked from commit b694dbadfe0774e1c0a0ad6c971ed8951c60326a) * 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 commit 7f9258b024cdd134d2a26a4879f24ac04dfbdb07) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit 96aee766f4c2ae2fe769d408a010834ef95dff71) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit 29b20bd1b135d18e9e7942555154ad24e2b1578b) 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>
2020-09-04 01:07:02 +02:00
The functionality you want may be too large for a single module. If you want to connect Ansible to a new cloud provider, database, or network platform, you may need to :ref:`develop a new collection<developing_modules_in_groups>`.
[docs][backport]Backportapalooza 10 (#71621) * Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commit c586d436fabc8033055d5195038ca3341d7f0192) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commit bc6461432ef4d0d9323d9b4355efd09e79c0a7b9) * 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 commit ec3920cef1692d54c08f1932cf0724239628aff1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit 215eb730e1e69f6f7e1566c610ac1b614c50854e) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commit f75223d2c6d38ae936a4b813190ff6324d361d7f) * User guide overhaul, Table of Contents (#71553) (cherry picked from commit b694dbadfe0774e1c0a0ad6c971ed8951c60326a) * 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 commit 7f9258b024cdd134d2a26a4879f24ac04dfbdb07) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit 96aee766f4c2ae2fe769d408a010834ef95dff71) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit 29b20bd1b135d18e9e7942555154ad24e2b1578b) 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>
2020-09-04 01:07:02 +02:00
* Each module should have a concise and well defined functionality. Basically, follow the UNIX philosophy of doing one thing well.
[docs][backport]Backportapalooza 10 (#71621) * Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commit c586d436fabc8033055d5195038ca3341d7f0192) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commit bc6461432ef4d0d9323d9b4355efd09e79c0a7b9) * 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 commit ec3920cef1692d54c08f1932cf0724239628aff1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit 215eb730e1e69f6f7e1566c610ac1b614c50854e) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commit f75223d2c6d38ae936a4b813190ff6324d361d7f) * User guide overhaul, Table of Contents (#71553) (cherry picked from commit b694dbadfe0774e1c0a0ad6c971ed8951c60326a) * 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 commit 7f9258b024cdd134d2a26a4879f24ac04dfbdb07) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit 96aee766f4c2ae2fe769d408a010834ef95dff71) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit 29b20bd1b135d18e9e7942555154ad24e2b1578b) 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>
2020-09-04 01:07:02 +02:00
* A module should not require that a user know all the underlying options of an API/tool to be used. For instance, if the legal values for a required module parameter cannot be documented, that's a sign that the module would be rejected.
* Modules should typically encompass much of the logic for interacting with a resource. A lightweight wrapper around an API that does not contain much logic would likely cause users to offload too much logic into a playbook, and for this reason the module would be rejected. Instead try creating multiple modules for interacting with smaller individual pieces of the API.
[docs][backport]Backportapalooza 10 (#71621) * Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commit c586d436fabc8033055d5195038ca3341d7f0192) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commit bc6461432ef4d0d9323d9b4355efd09e79c0a7b9) * 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 commit ec3920cef1692d54c08f1932cf0724239628aff1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit 215eb730e1e69f6f7e1566c610ac1b614c50854e) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commit f75223d2c6d38ae936a4b813190ff6324d361d7f) * User guide overhaul, Table of Contents (#71553) (cherry picked from commit b694dbadfe0774e1c0a0ad6c971ed8951c60326a) * 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 commit 7f9258b024cdd134d2a26a4879f24ac04dfbdb07) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit 96aee766f4c2ae2fe769d408a010834ef95dff71) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit 29b20bd1b135d18e9e7942555154ad24e2b1578b) 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>
2020-09-04 01:07:02 +02:00
If your use case isn't covered by an existing module, an action plugin, or a role, and you don't need to create multiple modules, then you're ready to start developing a new module. Choose from the topics below for next steps:
2016-09-23 22:48:37 +02:00
* I want to :ref:`get started on a new module <developing_modules_general>`.
* I want to review :ref:`tips and conventions for developing good modules <developing_modules_best_practices>`.
* I want to :ref:`write a Windows module <developing_modules_general_windows>`.
* I want :ref:`an overview of Ansible's architecture <developing_program_flow_modules>`.
* I want to :ref:`document my module <developing_modules_documenting>`.
* I want to :ref:`contribute my module back to Ansible Core <developing_modules_checklist>`.
* I want to :ref:`add unit and integration tests to my module <developing_testing>`.
* I want to :ref:`add Python 3 support to my module <developing_python_3>`.
* I want to :ref:`write multiple modules <developing_modules_in_groups>`.
2016-09-23 22:48:37 +02:00
.. seealso::
[docs][backport]Backportapalooza 10 (#71621) * Feature freeze date has been merged with Ansible-2.10.0beta1 (#71494) (cherry picked from commit c586d436fabc8033055d5195038ca3341d7f0192) * Add --allow-disabled to sanity docs (#71524) (cherry picked from commit bc6461432ef4d0d9323d9b4355efd09e79c0a7b9) * 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 commit ec3920cef1692d54c08f1932cf0724239628aff1) * ansible-vault: Fix typo in help message (#71485) (cherry picked from commit 215eb730e1e69f6f7e1566c610ac1b614c50854e) * update install for 2.10 (#71543) * update install for 2.10 (cherry picked from commit f75223d2c6d38ae936a4b813190ff6324d361d7f) * User guide overhaul, Table of Contents (#71553) (cherry picked from commit b694dbadfe0774e1c0a0ad6c971ed8951c60326a) * 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 commit 7f9258b024cdd134d2a26a4879f24ac04dfbdb07) * More docs updates to reflect collections ecosystem (#71597) (cherry picked from commit 96aee766f4c2ae2fe769d408a010834ef95dff71) * DOCS: Mentions ansible-base, adds collections pointers to Community and Dev Guides (#71480) (cherry picked from commit 29b20bd1b135d18e9e7942555154ad24e2b1578b) 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>
2020-09-04 01:07:02 +02:00
:ref:`list_of_collections`
Browse existing collections, modules, and plugins
`Mailing List <https://groups.google.com/group/ansible-devel>`_
2016-09-23 22:48:37 +02:00
Development mailing list
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel