CINXE.COM

<!DOCTYPE html> <html class="writer-html5" lang="en" data-content_root="../"> <head> <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Developing modules — Ansible Community Documentation</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=5707b69d" /> <link rel="stylesheet" type="text/css" href="../_static/css/ansible.css?v=c5b67dd2" /> <link rel="stylesheet" type="text/css" href="../_static/antsibull-minimal.css" /> <link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="../_static/css/rtd-ethical-ads.css?v=289b023e" /> <link rel="shortcut icon" href="../_static/images/Ansible-Mark-RGB_Black.png"/> <link rel="canonical" href="https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html"/> <script src="../_static/jquery.js?v=5d32c60e"></script> <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="../_static/documentation_options.js?v=8ff10258"></script> <script src="../_static/doctools.js?v=888ff710"></script> <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../_static/copybutton.js?v=f281be69"></script> <script src="../_static/js/theme.js"></script> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="next" title="Contributing your module to an existing Ansible collection" href="developing_modules_checklist.html" /> <link rel="prev" title="Should you develop a module?" href="developing_modules.html" /> <script src="https://www.redhat.com/dtm.js"></script>  <script> dataLayer = []; </script>  </head> <body class="wy-body-for-nav">  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-PSB293" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript> <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-PSB293');</script>  <div class="DocSite-globalNav ansibleNav"> <ul> <li><a href="https://www.ansible.com/blog" target="_blank">Blog</a></li> <li><a href="https://forum.ansible.com/" target="_blank">Ansible community forum</a></li> <li><a href="https://docs.ansible.com/" target="_blank">Documentation</a></li> </ul> </div> <a class="DocSite-nav" href="/" style="padding-bottom: 30px;"> <img class="DocSiteNav-logo" src="../_static/images/Ansible-Mark-RGB_White.png" alt="Ansible Logo"> <div class="DocSiteNav-title">Ansible Community Documentation</div> </a> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="../index.html" class="icon icon-home"> Ansible </a> <div class="version"> <form class="version-dropdown" method="get"> <script> function switchVersionTo(slug) { var current_url_path = window.location.pathname; var url_version = current_url_path.search("/11/") > -1 ? "/11/" : "/latest/"; var new_version_url = current_url_path.replace(url_version, "/" + slug + "/"); window.location.replace(new_version_url); } </script> <label class="sr-only" for="version-list">Select version:</label> <select class="version-list" id="version-list" onchange="switchVersionTo(this.value);" > <option value="latest" > latest </option> <option value="2.9" > 2.9 </option> <option value="devel" > devel </option> </select> </form> </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> <label class="sr-only" for="q">Search docs:</label> <input type="text" class="st-default-search-input" id="q" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> Ansible getting started <ul> <li class="toctree-l1"><a class="reference internal" href="../getting_started/index.html">Getting started with Ansible</a></li> <li class="toctree-l1"><a class="reference internal" href="../getting_started_ee/index.html">Getting started with Execution Environments</a></li> </ul> Installation, Upgrade & Configuration <ul> <li class="toctree-l1"><a class="reference internal" href="../installation_guide/index.html">Installation Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="../porting_guides/porting_guides.html">Ansible Porting Guides</a></li> </ul> Using Ansible <ul> <li class="toctree-l1"><a class="reference internal" href="../inventory_guide/index.html">Building Ansible inventories</a></li> <li class="toctree-l1"><a class="reference internal" href="../command_guide/index.html">Using Ansible command line tools</a></li> <li class="toctree-l1"><a class="reference internal" href="../playbook_guide/index.html">Using Ansible playbooks</a></li> <li class="toctree-l1"><a class="reference internal" href="../vault_guide/index.html">Protecting sensitive data with Ansible vault</a></li> <li class="toctree-l1"><a class="reference internal" href="../module_plugin_guide/index.html">Using Ansible modules and plugins</a></li> <li class="toctree-l1"><a class="reference internal" href="../collections_guide/index.html">Using Ansible collections</a></li> <li class="toctree-l1"><a class="reference internal" href="../os_guide/index.html">Using Ansible on Windows and BSD</a></li> <li class="toctree-l1"><a class="reference internal" href="../tips_tricks/index.html">Ansible tips and tricks</a></li> </ul> Contributing to Ansible <ul> <li class="toctree-l1"><a class="reference internal" href="../community/index.html">Ansible Community Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="../community/contributions_collections.html">Ansible Collections Contributor Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="../community/contributions.html">ansible-core Contributors Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="../community/advanced_index.html">Advanced Contributor Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="style_guide/index.html">Ansible documentation style guide</a></li> </ul> Extending Ansible <ul> <li class="toctree-l1"><a class="reference internal" href="index.html">Developer Guide</a></li> </ul> Common Ansible Scenarios <ul> <li class="toctree-l1"><a class="reference internal" href="../scenario_guides/cloud_guides.html">Legacy Public Cloud Guides</a></li> </ul> Network Automation <ul> <li class="toctree-l1"><a class="reference internal" href="../network/getting_started/index.html">Network Getting Started</a></li> <li class="toctree-l1"><a class="reference internal" href="../network/user_guide/index.html">Network Advanced Topics</a></li> <li class="toctree-l1"><a class="reference internal" href="../network/dev_guide/index.html">Network Developer Guide</a></li> </ul> Ansible Galaxy <ul> <li class="toctree-l1"><a class="reference internal" href="../galaxy/user_guide.html">Galaxy User Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="../galaxy/dev_guide.html">Galaxy Developer Guide</a></li> </ul> Reference & Appendices <ul> <li class="toctree-l1"><a class="reference internal" href="../collections/index.html">Collection Index</a></li> <li class="toctree-l1"><a class="reference internal" href="../collections/all_plugins.html">Indexes of all modules and plugins</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/playbooks_keywords.html">Playbook Keywords</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/common_return_values.html">Return Values</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/config.html">Ansible Configuration Settings</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/general_precedence.html">Controlling how Ansible behaves: precedence rules</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/YAMLSyntax.html">YAML Syntax</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/python_3_support.html">Python 3 Support</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/interpreter_discovery.html">Interpreter Discovery</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/release_and_maintenance.html">Releases and maintenance</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/test_strategies.html">Testing Strategies</a></li> <li class="toctree-l1"><a class="reference internal" href="testing/sanity/index.html">Sanity Tests</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/faq.html">Frequently Asked Questions</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/glossary.html">Glossary</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/module_utils.html">Ansible Reference: Module Utilities</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/special_variables.html">Special Variables</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/tower.html">Red Hat Ansible Automation Platform</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/automationhub.html">Ansible Automation Hub</a></li> <li class="toctree-l1"><a class="reference internal" href="../reference_appendices/logging.html">Logging Ansible output</a></li> </ul> Roadmaps <ul> <li class="toctree-l1"><a class="reference internal" href="../roadmap/ansible_roadmap_index.html">Ansible Roadmap</a></li> <li class="toctree-l1"><a class="reference internal" href="../roadmap/ansible_core_roadmap_index.html">ansible-core Roadmaps</a></li> </ul>   <div id="sideBanner"> <a href="https://www.ansible.com/docs-left?utm_source=docs"> <img style="border-width:0px;" src="https://cdn2.hubspot.net/hubfs/330046/docs-graphics/ASB-docs-left-rail.png" /> </a> </div> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <a href="../index.html">Ansible</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item"><a href="index.html">Developer Guide</a></li> <li class="breadcrumb-item active">Developing modules</li> <li class="wy-breadcrumbs-aside">  <a href="https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/dev_guide/developing_modules_general.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr" class="fa fa-github"> Edit on GitHub</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <script> function startsWith(str, needle) { return str.slice(0, needle.length) == needle } function startsWithOneOf(str, needles) { return needles.some(function (needle) { return startsWith(str, needle); }); } var banner = ''; /*use extra_banner for when we want something extra, like a survey or Community Day notice */ var extra_banner = ''; /* var extra_banner = '<div id="latest_extra_banner_id" class="admonition important">' + '' + 'Take the <a href="https://www.surveymonkey.com/r/P9Q2SNG">Ansible Project Survey 2024</a>!' + '' + '' + 'We want to hear from you! Help us gain insights into the state of the Ansible ecosystem.' + '' + '</div>'; */ // Create a banner if we're not on the official docs site if (location.host == "docs.testing.ansible.com") { document.write('<div id="testing_banner_id" class="admonition important">' + 'This is the testing site for Ansible Documentation. Unless you are reviewing pre-production changes, please visit the <a href="https://docs.ansible.com/ansible/latest/">official documentation website</a>. ' + '</div>'); } // Create a banner current_url_path = window.location.pathname; var important = false; var msg = ''; if (startsWith(current_url_path, "/ansible-core/")) { msg += 'You are reading documentation for Ansible Core, which contains no plugins except for those in ansible.builtin. For documentation of the Ansible package, go to <a href="/ansible/latest">the latest documentation</a>.'; } else if (startsWithOneOf(current_url_path, ["/ansible/latest/", "/ansible/11/"])) { /* temp extra banner to advertise something */ banner += extra_banner; msg += 'This is the latest (stable) Ansible community documentation. For Red Hat Ansible Automation Platform subscriptions, see <a href="https://access.redhat.com/support/policy/updates/ansible-automation-platform">Life Cycle</a> for version details.'; } else if (startsWith(current_url_path, "/ansible/2.9/")) { msg += 'You are reading the latest Red Hat released version of the Ansible documentation. Community users can use this version, or select latest from the version selector to the left for the most recent community version.'; } else if (startsWith(current_url_path, "/ansible/devel/")) { /* temp extra banner to advertise something */ banner += extra_banner; msg += 'You are reading the devel version of the Ansible documentation - this version is not guaranteed stable. Use the version selection to the left if you want the latest (stable) released version.'; } else { msg += 'You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the latest (stable) released version.'; /* temp extra banner to advertise something - this is for testing*/ banner += extra_banner; } msg += ''; banner += '<div id="banner_id" class="admonition '; banner += important ? 'important' : 'caution'; banner += '">'; banner += important ? ' ' : ''; banner += msg; banner += important ? ' ' : ''; banner += '</div>'; document.write(banner); </script> <div itemprop="articleBody"> <section id="developing-modules"> <h1>Developing modules<a class="headerlink" href="#developing-modules" title="Link to this heading"></a></h1> A module is a reusable, standalone script that Ansible runs on your behalf, either locally or remotely. Modules interact with your local machine, an API, or a remote system to perform specific tasks like changing a database password or spinning up a cloud instance. Each module can be used by the Ansible API, or by the ansible or ansible-playbook programs. A module provides a defined interface, accepts arguments, and returns information to Ansible by printing a JSON string to stdout before exiting. If you need functionality that is not available in any of the thousands of Ansible modules found in collections, you can easily write your own custom module. When you write a module for local use, you can choose any programming language and follow your own rules. Use this topic to learn how to create an Ansible module in Python. After you create a module, you must add it locally to the appropriate directory so that Ansible can find and execute it. For details about adding a module locally, see <a class="reference internal" href="developing_locally.html#developing-locally">Adding modules and plugins locally</a>. If you are developing a module in a <a class="reference internal" href="developing_collections.html#developing-collections">collection</a>, see those documents instead. <nav class="contents local" id="contents"> <ul class="simple"> <li><a class="reference internal" href="#preparing-an-environment-for-developing-ansible-modules" id="id1">Preparing an environment for developing Ansible modules</a></li> <li><a class="reference internal" href="#creating-a-module" id="id2">Creating a module</a></li> <li><a class="reference internal" href="#creating-an-info-or-a-facts-module" id="id3">Creating an info or a facts module</a></li> <li><a class="reference internal" href="#verifying-your-module-code" id="id4">Verifying your module code</a> <ul> <li><a class="reference internal" href="#verifying-your-module-code-locally" id="id5">Verifying your module code locally</a></li> <li><a class="reference internal" href="#verifying-your-module-code-in-a-playbook" id="id6">Verifying your module code in a playbook</a></li> </ul> </li> <li><a class="reference internal" href="#testing-your-newly-created-module" id="id7">Testing your newly-created module</a></li> <li><a class="reference internal" href="#contributing-back-to-ansible" id="id8">Contributing back to Ansible</a></li> <li><a class="reference internal" href="#communication-and-development-support" id="id9">Communication and development support</a></li> <li><a class="reference internal" href="#credit" id="id10">Credit</a></li> </ul> </nav> <section id="preparing-an-environment-for-developing-ansible-modules"> <h2><a class="toc-backref" href="#id1" role="doc-backlink">Preparing an environment for developing Ansible modules</a><a class="headerlink" href="#preparing-an-environment-for-developing-ansible-modules" title="Link to this heading"></a></h2> You just need <code class="docutils literal notranslate">ansible-core</code> installed to test the module. Modules can be written in any language, but most of the following guide is assuming you are using Python. Modules for inclusion in Ansible itself must be Python or Powershell. One advantage of using Python or Powershell for your custom modules is being able to use the <code class="docutils literal notranslate">module_utils</code> common code that does a lot of the heavy lifting for argument processing, logging and response writing, among other things. </section> <section id="creating-a-module"> <h2><a class="toc-backref" href="#id2" role="doc-backlink">Creating a module</a><a class="headerlink" href="#creating-a-module" title="Link to this heading"></a></h2> It is highly recommended that you use a <code class="docutils literal notranslate">venv</code> or <code class="docutils literal notranslate">virtualenv</code> for Python development. To create a module: <ol class="arabic simple"> <li>Create a <code class="docutils literal notranslate">library</code> directory in your workspace. Your test play should live in the same directory.</li> <li>Create your new module file: <code class="docutils literal notranslate">$ touch library/my_test.py</code>. Or just open/create it with your editor of choice.</li> <li>Paste the content below into your new module file. It includes the <a class="reference internal" href="developing_modules_documenting.html#developing-modules-documenting">required Ansible format and documentation</a>, a simple <a class="reference internal" href="developing_program_flow_modules.html#argument-spec">argument spec for declaring the module options</a>, and some example code.</li> <li>Modify and extend the code to do what you want your new module to do. See the <a class="reference internal" href="developing_modules_best_practices.html#developing-modules-best-practices">programming tips</a> and <a class="reference internal" href="developing_python_3.html#developing-python-3">Python 3 compatibility</a> pages for pointers on writing clean and concise module code.</li> </ol> <div class="highlight-python notranslate"><div class="highlight"><pre>#!/usr/bin/python # Copyright: (c) 2018, Terry Jones <<a href="/cdn-cgi/l/email-protection" class="__cf_email__" data-cfemail="dda9b8afafa4f3b7b2b3b8ae9db8a5bcb0adb1b8f3b2afba">[email protected]</a>> # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import (absolute_import, division, print_function) __metaclass__ = type DOCUMENTATION = r''' --- module: my_test short_description: This is my test module # If this is part of a collection, you need to use semantic versioning, # i.e. the version is of the form "2.5.0" and not "2.4". version_added: "1.0.0" description: This is my longer description explaining my test module. options: name: description: This is the message to send to the test module. required: true type: str new: description: - Control to demo if the result of this module is changed or not. - Parameter description can be a list as well. required: false type: bool # Specify this value according to your collection # in format of namespace.collection.doc_fragment_name # extends_documentation_fragment: # - my_namespace.my_collection.my_doc_fragment_name author: - Your Name (@yourGitHubHandle) ''' EXAMPLES = r''' # Pass in a message - name: Test with a message my_namespace.my_collection.my_test: name: hello world # pass in a message and have changed true - name: Test with a message and changed output my_namespace.my_collection.my_test: name: hello world new: true # fail the module - name: Test failure of the module my_namespace.my_collection.my_test: name: fail me ''' RETURN = r''' # These are examples of possible return values, and in general should use other names for return values. original_message: description: The original name param that was passed in. type: str returned: always sample: 'hello world' message: description: The output message that the test module generates. type: str returned: always sample: 'goodbye' ''' from ansible.module_utils.basic import AnsibleModule def run_module(): # define available arguments/parameters a user can pass to the module module_args = dict( name=dict(type='str', required=True), new=dict(type='bool', required=False, default=False) ) # seed the result dict in the object # we primarily care about changed and state # changed is if this module effectively modified the target # state will include any data that you want your module to pass back # for consumption, for example, in a subsequent task result = dict( changed=False, original_message='', message='' ) # the AnsibleModule object will be our abstraction working with Ansible # this includes instantiation, a couple of common attr would be the # args/params passed to the execution, as well as if the module # supports check mode module = AnsibleModule( argument_spec=module_args, supports_check_mode=True ) # if the user is working with this module in only check mode we do not # want to make any changes to the environment, just return the current # state with no modifications if module.check_mode: module.exit_json(**result) # manipulate or modify the state as needed (this is going to be the # part where your module will do what it needs to do) result['original_message'] = module.params['name'] result['message'] = 'goodbye' # use whatever logic you need to determine whether or not this module # made any modifications to your target if module.params['new']: result['changed'] = True # during the execution of the module, if there is an exception or a # conditional state that effectively causes a failure, run # AnsibleModule.fail_json() to pass in the message and the result if module.params['name'] == 'fail me': module.fail_json(msg='You requested this to fail', **result) # in the event of a successful module execution, you will want to # simple AnsibleModule.exit_json(), passing the key/value results module.exit_json(**result) def main(): run_module() if __name__ == '__main__': main() </pre></div> </div> </section> <section id="creating-an-info-or-a-facts-module"> <h2><a class="toc-backref" href="#id3" role="doc-backlink">Creating an info or a facts module</a><a class="headerlink" href="#creating-an-info-or-a-facts-module" title="Link to this heading"></a></h2> Ansible gathers information about the target machines using facts modules, and gathers information on other objects or files using info modules. If you find yourself trying to add <code class="docutils literal notranslate">state: info</code> or <code class="docutils literal notranslate">state: list</code> to an existing module, that is often a sign that a new dedicated <code class="docutils literal notranslate">_facts</code> or <code class="docutils literal notranslate">_info</code> module is needed. In Ansible 2.8 and onwards, we have two type of information modules, they are <code class="docutils literal notranslate">*_info</code> and <code class="docutils literal notranslate">*_facts</code>. If a module is named <code class="docutils literal notranslate"><something>_facts</code>, it should be because its main purpose is returning <code class="docutils literal notranslate">ansible_facts</code>. Do not name modules that do not do this with <code class="docutils literal notranslate">_facts</code>. Only use <code class="docutils literal notranslate">ansible_facts</code> for information that is specific to the host machine, for example network interfaces and their configuration, which operating system and which programs are installed. Modules that query/return general information (and not <code class="docutils literal notranslate">ansible_facts</code>) should be named <code class="docutils literal notranslate">_info</code>. General information is non-host specific information, for example information on online/cloud services (you can access different accounts for the same online service from the same host), or information on VMs and containers accessible from the machine, or information on individual files or programs. Info and facts modules, are just like any other Ansible Module, with a few minor requirements: <ol class="arabic simple"> <li>They MUST be named <code class="docutils literal notranslate"><something>_info</code> or <code class="docutils literal notranslate"><something>_facts</code>, where <something> is singular.</li> <li>Info <code class="docutils literal notranslate">*_info</code> modules MUST return in the form of the <a class="reference internal" href="../reference_appendices/common_return_values.html#common-return-values">result dictionary</a> so other modules can access them.</li> <li>Fact <code class="docutils literal notranslate">*_facts</code> modules MUST return in the <code class="docutils literal notranslate">ansible_facts</code> field of the <a class="reference internal" href="../reference_appendices/common_return_values.html#common-return-values">result dictionary</a> so other modules can access them.</li> <li>They MUST support <a class="reference internal" href="../playbook_guide/playbooks_checkmode.html#check-mode-dry">check_mode</a>.</li> <li>They MUST NOT make any changes to the system.</li> <li>They MUST document the <a class="reference internal" href="developing_modules_documenting.html#return-block">return fields</a> and <a class="reference internal" href="developing_modules_documenting.html#examples-block">examples</a>.</li> </ol> You can add your facts into <code class="docutils literal notranslate">ansible_facts</code> field of the result as follows: <div class="highlight-python notranslate"><div class="highlight"><pre>module.exit_json(changed=False, ansible_facts=dict(my_new_fact=value_of_fact)) </pre></div> </div> The rest is just like creating a normal module. </section> <section id="verifying-your-module-code"> <h2><a class="toc-backref" href="#id4" role="doc-backlink">Verifying your module code</a><a class="headerlink" href="#verifying-your-module-code" title="Link to this heading"></a></h2> After you modify the sample code above to do what you want, you can try out your module. Our <a class="reference internal" href="debugging.html#debugging-modules">debugging tips</a> will help if you run into bugs as you verify your module code. <section id="verifying-your-module-code-locally"> <h3><a class="toc-backref" href="#id5" role="doc-backlink">Verifying your module code locally</a><a class="headerlink" href="#verifying-your-module-code-locally" title="Link to this heading"></a></h3> The simplest way is to use <code class="docutils literal notranslate">ansible</code> adhoc command: <div class="highlight-shell notranslate"><div class="highlight"><pre>ANSIBLE_LIBRARY=./library ansible -m my_test -a 'name=hello new=true' remotehost </pre></div> </div> If your module does not need to target a remote host, you can quickly and easily exercise your code locally like this: <div class="highlight-shell notranslate"><div class="highlight"><pre>ANSIBLE_LIBRARY=./library ansible -m my_test -a 'name=hello new=true' localhost </pre></div> </div> <ul class="simple"> <li>If for any reason (pdb, using print(), faster iteration, etc) you want to avoid going through Ansible, another way is to create an arguments file, a basic JSON config file that passes parameters to your module so that you can run it. Name the arguments file <code class="docutils literal notranslate">/tmp/args.json</code> and add the following content:</li> </ul> <div class="highlight-json notranslate"><div class="highlight"><pre>{ "ANSIBLE_MODULE_ARGS": { "name": "hello", "new": true } } </pre></div> </div> <ul class="simple"> <li>Then the module can be tested locally and directly. This skips the packing steps and uses module_utils files directly:</li> </ul> <div class="highlight-console notranslate"><div class="highlight"><pre>$ python library/my_test.py /tmp/args.json </pre></div> </div> It should return output like this: <div class="highlight-json notranslate"><div class="highlight"><pre>{"changed": true, "state": {"original_message": "hello", "new_message": "goodbye"}, "invocation": {"module_args": {"name": "hello", "new": true}}} </pre></div> </div> </section> <section id="verifying-your-module-code-in-a-playbook"> <h3><a class="toc-backref" href="#id6" role="doc-backlink">Verifying your module code in a playbook</a><a class="headerlink" href="#verifying-your-module-code-in-a-playbook" title="Link to this heading"></a></h3> You can easily run a full test by including it in a playbook, as long as the <code class="docutils literal notranslate">library</code> directory is in the same directory as the play: <ul class="simple"> <li>Create a playbook in any directory: <code class="docutils literal notranslate">$ touch testmod.yml</code></li> <li>Add the following to the new playbook file:</li> </ul> <div class="highlight-yaml notranslate"><div class="highlight"><pre>- name: test my new module hosts: localhost tasks: - name: run the new module my_test: name: 'hello' new: true register: testout - name: dump test output debug: msg: '{{ testout }}' </pre></div> </div> <ul class="simple"> <li>Run the playbook and analyze the output: <code class="docutils literal notranslate">$ ansible-playbook ./testmod.yml</code></li> </ul> </section> </section> <section id="testing-your-newly-created-module"> <h2><a class="toc-backref" href="#id7" role="doc-backlink">Testing your newly-created module</a><a class="headerlink" href="#testing-your-newly-created-module" title="Link to this heading"></a></h2> Review our <a class="reference internal" href="testing.html#developing-testing">testing</a> section for more detailed information, including instructions for <a class="reference internal" href="testing_documentation.html#testing-module-documentation">testing module documentation</a>, adding <a class="reference internal" href="testing_integration.html#testing-integration">integration tests</a>, and more. <div class="admonition note"> Note If contributing to Ansible, every new module and plugin should have integration tests, even if the tests cannot be run on Ansible CI infrastructure. In this case, the tests should be marked with the <code class="docutils literal notranslate">unsupported</code> alias in <a class="reference external" href="https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/integration-aliases.html">aliases file</a>. </div> </section> <section id="contributing-back-to-ansible"> <h2><a class="toc-backref" href="#id8" role="doc-backlink">Contributing back to Ansible</a><a class="headerlink" href="#contributing-back-to-ansible" title="Link to this heading"></a></h2> If you would like to contribute to <code class="docutils literal notranslate">ansible-core</code> by adding a new feature or fixing a bug, <a class="reference external" href="https://help.github.com/articles/fork-a-repo/">create a fork</a> of the ansible/ansible repository and develop against a new feature branch using the <code class="docutils literal notranslate">devel</code> branch as a starting point. When you have a good working code change, you can submit a pull request to the Ansible repository by selecting your feature branch as a source and the Ansible devel branch as a target. If you want to contribute a module to an <a class="reference internal" href="../community/contributing_maintained_collections.html#contributing-maintained-collections">Ansible collection</a>, review our <a class="reference internal" href="developing_modules_checklist.html#developing-modules-checklist">submission checklist</a>, <a class="reference internal" href="developing_modules_best_practices.html#developing-modules-best-practices">programming tips</a>, and <a class="reference internal" href="developing_python_3.html#developing-python-3">strategy for maintaining Python 2 and Python 3 compatibility</a>, as well as information about <a class="reference internal" href="testing.html#developing-testing">testing</a> before you open a pull request. The <a class="reference internal" href="../community/index.html#ansible-community-guide">Community Guide</a> covers how to open a pull request and what happens next. </section> <section id="communication-and-development-support"> <h2><a class="toc-backref" href="#id9" role="doc-backlink">Communication and development support</a><a class="headerlink" href="#communication-and-development-support" title="Link to this heading"></a></h2> Visit the <a class="reference internal" href="../community/communication.html#communication">Ansible communication guide</a> for information on how to join the conversation. </section> <section id="credit"> <h2><a class="toc-backref" href="#id10" role="doc-backlink">Credit</a><a class="headerlink" href="#credit" title="Link to this heading"></a></h2> Thank you to Thomas Stringer (<a class="reference external" href="https://github.com/trstringer">@trstringer</a>) for contributing source material for this topic. </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="developing_modules.html" class="btn btn-neutral float-left" title="Should you develop a module?" accesskey="p" rel="prev"> Previous</a> <a href="developing_modules_checklist.html" class="btn btn-neutral float-right" title="Contributing your module to an existing Ansible collection" accesskey="n" rel="next">Next </a> </div> <hr/> <div role="contentinfo"> © Copyright Ansible project contributors. Last updated on Nov 20, 2024. </div> </footer> </div> </div> </section> </div> <script data-cfasync="false" src="/cdn-cgi/scripts/5c5dd728/cloudflare-static/email-decode.min.js"></script><script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script>  <script> var _hsq = _hsq || []; _hsq.push(["setContentType", "standard-page"]); (function(d,s,i,r) { if (d.getElementById(i)){return;} var n = d.createElement(s),e = document.getElementsByTagName(s)[0]; n.id=i;n.src = 'https://js.hs-analytics.net/analytics/'+(Math.ceil(new Date()/r)*r)+'/330046.js'; e.parentNode.insertBefore(n, e); })(document, "script", "hs-analytics",300000); </script>  <script> if (("undefined" !== typeof _satellite) && ("function" === typeof _satellite.pageBottom)) { _satellite.pageBottom(); } </script> </body> </html>