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 dynamic inventory — Ansible Community Documentation</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=41de9001" /> <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_inventory.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="Developing ansible-core" href="developing_core.html" /> <link rel="prev" title="Developing plugins" href="developing_plugins.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="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 dynamic inventory</li> <li class="wy-breadcrumbs-aside">  <a href="https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/dev_guide/developing_inventory.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-dynamic-inventory"> <h1>Developing dynamic inventory<a class="headerlink" href="#developing-dynamic-inventory" title="Link to this heading"></a></h1> Ansible can pull inventory information from dynamic sources, including cloud sources, by using the supplied <a class="reference internal" href="../plugins/inventory.html#inventory-plugins">inventory plugins</a>. For details about how to pull inventory information, see <a class="reference internal" href="../inventory_guide/intro_dynamic_inventory.html#dynamic-inventory">Working with dynamic inventory</a>. If the source you want is not currently covered by existing plugins, you can create your own inventory plugin as with any other plugin type. In previous versions, you had to create a script or program that could output JSON in the correct format when invoked with the proper arguments. You can still use and write inventory scripts, as we ensured backwards compatibility through the <a class="reference internal" href="../collections/ansible/builtin/script_inventory.html#script-inventory">script inventory plugin</a> and there is no restriction on the programming language used. If you choose to write a script, however, you will need to implement some features yourself such as caching, configuration management, dynamic variable and group composition, and so on. If you use <a class="reference internal" href="../plugins/inventory.html#inventory-plugins">inventory plugins</a> instead, you can use the Ansible codebase and add these common features automatically. <nav class="contents local" id="topics"> Topics <ul class="simple"> <li><a class="reference internal" href="#inventory-sources" id="id6">Inventory sources</a></li> <li><a class="reference internal" href="#inventory-plugins" id="id7">Inventory plugins</a> <ul> <li><a class="reference internal" href="#developing-an-inventory-plugin" id="id8">Developing an inventory plugin</a> <ul> <li><a class="reference internal" href="#verify-file-method" id="id9">verify_file method</a></li> <li><a class="reference internal" href="#parse-method" id="id10">parse method</a></li> <li><a class="reference internal" href="#inventory-object" id="id11">inventory object</a></li> <li><a class="reference internal" href="#inventory-cache" id="id12">inventory cache</a></li> <li><a class="reference internal" href="#constructed-features" id="id13">constructed features</a></li> </ul> </li> <li><a class="reference internal" href="#common-format-for-inventory-sources" id="id14">Common format for inventory sources</a></li> <li><a class="reference internal" href="#the-auto-plugin" id="id15">The ‘auto’ plugin</a></li> </ul> </li> <li><a class="reference internal" href="#developing-inventory-scripts" id="id16">Inventory scripts</a> <ul> <li><a class="reference internal" href="#inventory-script-conventions" id="id17">Inventory script conventions</a></li> <li><a class="reference internal" href="#tuning-the-external-inventory-script" id="id18">Tuning the external inventory script</a></li> </ul> </li> </ul> </nav> <section id="inventory-sources"> <h2><a class="toc-backref" href="#id6" role="doc-backlink">Inventory sources</a><a class="headerlink" href="#inventory-sources" title="Link to this heading"></a></h2> Inventory sources are the input strings that inventory plugins work with. An inventory source can be a path to a file or to a script, or it can be raw data that the plugin can interpret. The table below shows some examples of inventory plugins and the source types that you can pass to them with <code class="docutils literal notranslate">-i</code> on the command line. <table class="docutils align-default"> <tbody> <tr class="row-odd"><td>Plugin</td> <td>Source</td> </tr> <tr class="row-even"><td><a class="reference internal" href="../collections/ansible/builtin/host_list_inventory.html#host-list-inventory">host list</a></td> <td>A comma-separated list of hosts</td> </tr> <tr class="row-odd"><td><a class="reference internal" href="../collections/ansible/builtin/yaml_inventory.html#yaml-inventory">yaml</a></td> <td>Path to a YAML format data file</td> </tr> <tr class="row-even"><td><a class="reference internal" href="../collections/ansible/builtin/constructed_inventory.html#constructed-inventory">constructed</a></td> <td>Path to a YAML configuration file</td> </tr> <tr class="row-odd"><td><a class="reference internal" href="../collections/ansible/builtin/ini_inventory.html#ini-inventory">ini</a></td> <td>Path to an INI formatted data file</td> </tr> <tr class="row-even"><td><a class="reference external" href="https://docs.ansible.com/ansible/2.9/plugins/inventory/virtualbox.html#virtualbox-inventory" title="(in Ansible v2.9)">virtualbox</a></td> <td>Path to a YAML configuration file</td> </tr> <tr class="row-odd"><td><a class="reference internal" href="../collections/ansible/builtin/script_inventory.html#script-inventory">script plugin</a></td> <td>Path to an executable that outputs JSON</td> </tr> </tbody> </table> </section> <section id="inventory-plugins"> <h2><a class="toc-backref" href="#id7" role="doc-backlink">Inventory plugins</a><a class="headerlink" href="#inventory-plugins" title="Link to this heading"></a></h2> Like most plugin types (except modules), inventory plugins must be developed in Python. They execute on the control node and should therefore adhere to the <a class="reference internal" href="../installation_guide/intro_installation.html#control-node-requirements">Control node requirements</a>. Most of the documentation in <a class="reference internal" href="developing_plugins.html#developing-plugins">Developing plugins</a> also applies here. You should read that document first for a general understanding and then come back to this document for specifics on inventory plugins. Normally, inventory plugins are executed at the start of a run, and before the playbooks, plays, or roles are loaded. However, you can use the <code class="docutils literal notranslate">meta: refresh_inventory</code> task to clear the current inventory and execute the inventory plugins again, and this task will generate a new inventory. If you use the persistent cache, inventory plugins can also use the configured cache plugin to store and retrieve data. Caching inventory avoids making repeated and costly external calls. <section id="developing-an-inventory-plugin"> <h3><a class="toc-backref" href="#id8" role="doc-backlink">Developing an inventory plugin</a><a class="headerlink" href="#developing-an-inventory-plugin" title="Link to this heading"></a></h3> The first thing you want to do is use the base class: <div class="highlight-python notranslate"><div class="highlight"><pre>from ansible.plugins.inventory import BaseInventoryPlugin class InventoryModule(BaseInventoryPlugin): NAME = 'myplugin' # used internally by Ansible, it should match the file name but not required </pre></div> </div> If the inventory plugin is in a collection, the NAME should be in the ‘namespace.collection_name.myplugin’ format. The base class has a couple of methods that each plugin should implement and a few helpers for parsing the inventory source and updating the inventory. After you have the basic plugin working, you can incorporate other features by adding more base classes: <div class="highlight-python notranslate"><div class="highlight"><pre>from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable): NAME = 'myplugin' </pre></div> </div> For the bulk of the work in a plugin, we mostly want to deal with 2 methods <code class="docutils literal notranslate">verify_file</code> and <code class="docutils literal notranslate">parse</code>. <section id="verify-file-method"> <h4><a class="toc-backref" href="#id9" role="doc-backlink">verify_file method</a><a class="headerlink" href="#verify-file-method" title="Link to this heading"></a></h4> Ansible uses this method to quickly determine if the inventory source is usable by the plugin. The determination does not need to be 100% accurate, as there might be an overlap in what plugins can handle and by default Ansible will try the enabled plugins as per their sequence. <div class="highlight-python notranslate"><div class="highlight"><pre>def verify_file(self, path): ''' return true/false if this is possibly a valid file for this plugin to consume ''' valid = False if super(InventoryModule, self).verify_file(path): # base class verifies that file exists and is readable by current user if path.endswith(('virtualbox.yaml', 'virtualbox.yml', 'vbox.yaml', 'vbox.yml')): valid = True return valid </pre></div> </div> In the above example, from the <a class="reference external" href="https://docs.ansible.com/ansible/2.9/plugins/inventory/virtualbox.html#virtualbox-inventory" title="(in Ansible v2.9)">virtualbox inventory plugin</a>, we screen for specific file name patterns to avoid attempting to consume any valid YAML file. You can add any type of condition here, but the most common one is ‘extension matching’. If you implement extension matching for YAML configuration files, the path suffix <plugin_name>.<yml|yaml> should be accepted. All valid extensions should be documented in the plugin description. The following is another example that does not use a ‘file’ but the inventory source string itself, from the <a class="reference internal" href="../collections/ansible/builtin/host_list_inventory.html#host-list-inventory">host list</a> plugin: <div class="highlight-python notranslate"><div class="highlight"><pre>def verify_file(self, path): ''' don't call base class as we don't expect a path, but a host list ''' host_list = path valid = False b_path = to_bytes(host_list, errors='surrogate_or_strict') if not os.path.exists(b_path) and ',' in host_list: # the path does NOT exist and there is a comma to indicate this is a 'host list' valid = True return valid </pre></div> </div> This method is just to expedite the inventory process and avoid unnecessary parsing of sources that are easy to filter out before causing a parse error. </section> <section id="parse-method"> <h4><a class="toc-backref" href="#id10" role="doc-backlink">parse method</a><a class="headerlink" href="#parse-method" title="Link to this heading"></a></h4> This method does the bulk of the work in the plugin. It takes the following parameters: <blockquote> <div><ul class="simple"> <li>inventory: inventory object with existing data and the methods to add hosts/groups/variables to inventory</li> <li>loader: Ansible’s DataLoader. The DataLoader can read files, auto load JSON/YAML and decrypt vaulted data, and cache read files.</li> <li>path: string with inventory source (this is usually a path, but is not required)</li> <li>cache: indicates whether the plugin should use or avoid caches (cache plugin and/or loader)</li> </ul> </div></blockquote> The base class does some minimal assignment for reuse in other methods. <div class="highlight-python notranslate"><div class="highlight"><pre>def parse(self, inventory, loader, path, cache=True): self.loader = loader self.inventory = inventory self.templar = Templar(loader=loader) </pre></div> </div> It is up to the plugin now to parse the provided inventory source and translate it into Ansible inventory. To facilitate this, the example below uses a few helper functions: <div class="highlight-python notranslate"><div class="highlight"><pre>NAME = 'myplugin' def parse(self, inventory, loader, path, cache=True): # call base method to ensure properties are available for use with other helper methods super(InventoryModule, self).parse(inventory, loader, path, cache) # this method will parse 'common format' inventory sources and # update any options declared in DOCUMENTATION as needed config = self._read_config_data(path) # if NOT using _read_config_data you should call set_options directly, # to process any defined configuration for this plugin, # if you don't define any options you can skip #self.set_options() # example consuming options from inventory source mysession = apilib.session(user=self.get_option('api_user'), password=self.get_option('api_pass'), server=self.get_option('api_server') ) # make requests to get data to feed into inventory mydata = mysession.getitall() #parse data and create inventory objects: for colo in mydata: for server in mydata[colo]['servers']: self.inventory.add_host(server['name']) self.inventory.set_variable(server['name'], 'ansible_host', server['external_ip']) </pre></div> </div> The specifics will vary depending on API and structure returned. Remember that if you get an inventory source error or any other issue, you should <code class="docutils literal notranslate">raise AnsibleParserError</code> to let Ansible know that the source was invalid or the process failed. For examples on how to implement an inventory plugin, see the source code here: <a class="reference external" href="https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/inventory">lib/ansible/plugins/inventory</a>. </section> <section id="inventory-object"> <h4><a class="toc-backref" href="#id11" role="doc-backlink">inventory object</a><a class="headerlink" href="#inventory-object" title="Link to this heading"></a></h4> The <code class="docutils literal notranslate">inventory</code> object passed to <code class="docutils literal notranslate">parse</code> has helpful methods for populating inventory. <code class="docutils literal notranslate">add_group</code> adds a group to inventory if it doesn’t already exist. It takes the group name as the only positional argument. <code class="docutils literal notranslate">add_child</code> adds a group or host that exists in inventory to a parent group in inventory. It takes two positional arguments, the name of the parent group and the name of the child group or host. <code class="docutils literal notranslate">add_host</code> adds a host to inventory if it doesn’t already exist, optionally to a specific group. It takes the host name as the first argument and accepts two optional keyword arguments, <code class="docutils literal notranslate">group</code> and <code class="docutils literal notranslate">port</code>. <code class="docutils literal notranslate">group</code> is the name of a group in inventory, and <code class="docutils literal notranslate">port</code> is an integer. <code class="docutils literal notranslate">set_variable</code> adds a variable to a group or host in inventory. It takes three positional arguments: the name of the group or host, the name of the variable, and the value of the variable. To create groups and variables using Jinja2 expressions, see the section on implementing <code class="docutils literal notranslate">constructed</code> features below. To see other inventory object methods, see the source code here: <a class="reference external" href="https://github.com/ansible/ansible/tree/devel/lib/ansible/inventory/data.py">lib/ansible/inventory/data.py</a>. </section> <section id="inventory-cache"> <h4><a class="toc-backref" href="#id12" role="doc-backlink">inventory cache</a><a class="headerlink" href="#inventory-cache" title="Link to this heading"></a></h4> To cache the inventory, extend the inventory plugin documentation with the inventory_cache documentation fragment and use the Cacheable base class. <div class="highlight-yaml notranslate"><div class="highlight"><pre>extends_documentation_fragment: - inventory_cache </pre></div> </div> <div class="highlight-python notranslate"><div class="highlight"><pre>class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable): NAME = 'myplugin' </pre></div> </div> Next, load the cache plugin specified by the user to read from and update the cache. If your inventory plugin uses YAML-based configuration files and the <code class="docutils literal notranslate">_read_config_data</code> method, the cache plugin is loaded within that method. If your inventory plugin does not use <code class="docutils literal notranslate">_read_config_data</code>, you must load the cache explicitly with <code class="docutils literal notranslate">load_cache_plugin</code>. <div class="highlight-python notranslate"><div class="highlight"><pre>NAME = 'myplugin' def parse(self, inventory, loader, path, cache=True): super(InventoryModule, self).parse(inventory, loader, path) self.load_cache_plugin() </pre></div> </div> Before using the cache plugin, you must retrieve a unique cache key by using the <code class="docutils literal notranslate">get_cache_key</code> method. This task needs to be done by all inventory modules using the cache, so that you don’t use/overwrite other parts of the cache. <div class="highlight-python notranslate"><div class="highlight"><pre>def parse(self, inventory, loader, path, cache=True): super(InventoryModule, self).parse(inventory, loader, path) self.load_cache_plugin() cache_key = self.get_cache_key(path) </pre></div> </div> Now that you’ve enabled caching, loaded the correct plugin, and retrieved a unique cache key, you can set up the flow of data between the cache and your inventory using the <code class="docutils literal notranslate">cache</code> parameter of the <code class="docutils literal notranslate">parse</code> method. This value comes from the inventory manager and indicates whether the inventory is being refreshed (such as by the <code class="docutils literal notranslate">--flush-cache</code> or the meta task <code class="docutils literal notranslate">refresh_inventory</code>). Although the cache shouldn’t be used to populate the inventory when being refreshed, the cache should be updated with the new inventory if the user has enabled caching. You can use <code class="docutils literal notranslate">self._cache</code> like a dictionary. The following pattern allows refreshing the inventory to work in conjunction with caching. <div class="highlight-python notranslate"><div class="highlight"><pre>def parse(self, inventory, loader, path, cache=True): super(InventoryModule, self).parse(inventory, loader, path) self.load_cache_plugin() cache_key = self.get_cache_key(path) # cache may be True or False at this point to indicate if the inventory is being refreshed # get the user's cache option too to see if we should save the cache if it is changing user_cache_setting = self.get_option('cache') # read if the user has caching enabled and the cache isn't being refreshed attempt_to_read_cache = user_cache_setting and cache # update if the user has caching enabled and the cache is being refreshed; update this value to True if the cache has expired below cache_needs_update = user_cache_setting and not cache # attempt to read the cache if inventory isn't being refreshed and the user has caching enabled if attempt_to_read_cache: try: results = self._cache[cache_key] except KeyError: # This occurs if the cache_key is not in the cache or if the cache_key expired, so the cache needs to be updated cache_needs_update = True if not attempt_to_read_cache or cache_needs_update: # parse the provided inventory source results = self.get_inventory() if cache_needs_update: self._cache[cache_key] = results # submit the parsed data to the inventory object (add_host, set_variable, etc) self.populate(results) </pre></div> </div> After the <code class="docutils literal notranslate">parse</code> method is complete, the contents of <code class="docutils literal notranslate">self._cache</code> is used to set the cache plugin if the contents of the cache have changed. <dl class="simple"> <dt>You have three other cache methods available:</dt><dd><ul class="simple"> <li><code class="docutils literal notranslate">set_cache_plugin</code> forces the cache plugin to be set with the contents of <code class="docutils literal notranslate">self._cache</code>, before the <code class="docutils literal notranslate">parse</code> method completes</li> <li><code class="docutils literal notranslate">update_cache_if_changed</code> sets the cache plugin only if <code class="docutils literal notranslate">self._cache</code> has been modified, before the <code class="docutils literal notranslate">parse</code> method completes</li> <li><code class="docutils literal notranslate">clear_cache</code> flushes the cache, ultimately by calling the cache plugin’s <code class="docutils literal notranslate">flush()</code> method, whose implementation is dependent upon the particular cache plugin in use. Note that if the user is using the same cache backend for facts and inventory, both will get flushed. To avoid this, the user can specify a distinct cache backend in their inventory plugin configuration.</li> </ul> </dd> </dl> </section> <section id="constructed-features"> <h4><a class="toc-backref" href="#id13" role="doc-backlink">constructed features</a><a class="headerlink" href="#constructed-features" title="Link to this heading"></a></h4> Inventory plugins can create host variables and groups from Jinja2 expressions and variables by using features from the <code class="docutils literal notranslate">constructed</code> inventory plugin. To do this, use the <code class="docutils literal notranslate">Constructable</code> base class and extend the inventory plugin’s documentation with the <code class="docutils literal notranslate">constructed</code> documentation fragment. <div class="highlight-yaml notranslate"><div class="highlight"><pre>extends_documentation_fragment: - constructed </pre></div> </div> <div class="highlight-python notranslate"><div class="highlight"><pre>class InventoryModule(BaseInventoryPlugin, Constructable): NAME = 'ns.coll.myplugin' </pre></div> </div> There are three main options in the <code class="docutils literal notranslate">constructed</code> documentation fragment: <code class="docutils literal notranslate">compose</code> creates variables using Jinja2 expressions. This is implemented by calling the <code class="docutils literal notranslate">_set_composite_vars</code> method. <code class="docutils literal notranslate">keyed_groups</code> creates groups of hosts based on variable values. This is implemented by calling the <code class="docutils literal notranslate">_add_host_to_keyed_groups</code> method. <code class="docutils literal notranslate">groups</code> creates groups based on Jinja2 conditionals. This is implemented by calling the <code class="docutils literal notranslate">_add_host_to_composed_groups</code> method. Each method should be called for every host added to inventory. Three positional arguments are required: the constructed option, a dictionary of variables, and a host name. Calling the method <code class="docutils literal notranslate">_set_composite_vars</code> first will allow <code class="docutils literal notranslate">keyed_groups</code> and <code class="docutils literal notranslate">groups</code> to use the composed variables. By default, undefined variables are ignored. This is permitted by default for <code class="docutils literal notranslate">compose</code> so you can make the variable definitions depend on variables that will be populated later in a play from other sources. For groups, it allows using variables that are not always present without having to use the <code class="docutils literal notranslate">default</code> filter. To support configuring undefined variables to be an error, pass the constructed option <code class="docutils literal notranslate">strict</code> to each of the methods as a keyword argument. <code class="docutils literal notranslate">keyed_groups</code> and <code class="docutils literal notranslate">groups</code> use any variables already associated with the host (for example, from an earlier inventory source). <code class="docutils literal notranslate">_add_host_to_keyed_groups</code> and <code class="docutils literal notranslate">add_host_to_composed_groups</code> can turn this off by passing the keyword argument <code class="docutils literal notranslate">fetch_hostvars</code>. Here is an example using all three methods: <div class="highlight-python notranslate"><div class="highlight"><pre>def add_host(self, hostname, host_vars): self.inventory.add_host(hostname, group='all') for var_name, var_value in host_vars.items(): self.inventory.set_variable(hostname, var_name, var_value) strict = self.get_option('strict') # Add variables created by the user's Jinja2 expressions to the host self._set_composite_vars(self.get_option('compose'), host_vars, hostname, strict=True) # Create user-defined groups using variables and Jinja2 conditionals self._add_host_to_composed_groups(self.get_option('groups'), host_vars, hostname, strict=strict) self._add_host_to_keyed_groups(self.get_option('keyed_groups'), host_vars, hostname, strict=strict) </pre></div> </div> By default, group names created with <code class="docutils literal notranslate">_add_host_to_composed_groups()</code> and <code class="docutils literal notranslate">_add_host_to_keyed_groups()</code> are valid Python identifiers. Invalid characters are replaced with an underscore <code class="docutils literal notranslate">_</code>. A plugin can change the sanitization used for the constructed features by setting <code class="docutils literal notranslate">self._sanitize_group_name</code> to a new function. The core engine also does sanitization, so if the custom function is less strict it should be used in conjunction with the configuration setting <code class="docutils literal notranslate">TRANSFORM_INVALID_GROUP_CHARS</code>. <div class="highlight-python notranslate"><div class="highlight"><pre>from ansible.inventory.group import to_safe_group_name class InventoryModule(BaseInventoryPlugin, Constructable): NAME = 'ns.coll.myplugin' @staticmethod def custom_sanitizer(name): return to_safe_group_name(name, replacer='') def parse(self, inventory, loader, path, cache=True): super(InventoryModule, self).parse(inventory, loader, path) self._sanitize_group_name = custom_sanitizer </pre></div> </div> </section> </section> <section id="common-format-for-inventory-sources"> <h3><a class="toc-backref" href="#id14" role="doc-backlink">Common format for inventory sources</a><a class="headerlink" href="#common-format-for-inventory-sources" title="Link to this heading"></a></h3> To simplify development, most plugins use a standard YAML-based configuration file as the inventory source. The file has only one required field <code class="docutils literal notranslate">plugin</code>, which should contain the name of the plugin that is expected to consume the file. Depending on other common features used, you might need other fields, and you can add custom options in each plugin as required. For example, if you use the integrated caching, <code class="docutils literal notranslate">cache_plugin</code>, <code class="docutils literal notranslate">cache_timeout</code> and other cache-related fields could be present. </section> <section id="the-auto-plugin"> <h3><a class="toc-backref" href="#id15" role="doc-backlink">The ‘auto’ plugin</a><a class="headerlink" href="#the-auto-plugin" title="Link to this heading"></a></h3> From Ansible 2.5 onwards, we include the <a class="reference internal" href="../collections/ansible/builtin/auto_inventory.html#auto-inventory">auto inventory plugin</a> and enable it by default. If the <code class="docutils literal notranslate">plugin</code> field in your standard configuration file matches the name of your inventory plugin, the <code class="docutils literal notranslate">auto</code> inventory plugin will load your plugin. The ‘auto’ plugin makes it easier to use your plugin without having to update configurations. </section> </section> <section id="developing-inventory-scripts"> <h2><a class="toc-backref" href="#id16" role="doc-backlink">Inventory scripts</a><a class="headerlink" href="#developing-inventory-scripts" title="Link to this heading"></a></h2> Even though we now have inventory plugins, we still support inventory scripts, not only for backwards compatibility but also to allow users to use other programming languages. <section id="inventory-script-conventions"> <h3><a class="toc-backref" href="#id17" role="doc-backlink">Inventory script conventions</a><a class="headerlink" href="#inventory-script-conventions" title="Link to this heading"></a></h3> Inventory scripts must accept the <code class="docutils literal notranslate">--list</code> and <code class="docutils literal notranslate">--host <hostname></code> arguments. Although other arguments are allowed, Ansible will not use them. Such arguments might still be useful for executing the scripts directly. When the script is called with the single argument <code class="docutils literal notranslate">--list</code>, the script must output to stdout a JSON object that contains all the groups to be managed. Each group’s value should be either an object containing a list of each host, any child groups, and potential group variables, or simply a list of hosts: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "group001": { "hosts": ["host001", "host002"], "vars": { "var1": true }, "children": ["group002"] }, "group002": { "hosts": ["host003","host004"], "vars": { "var2": 500 }, "children":[] } } </pre></div> </div> If any of the elements of a group are empty, they may be omitted from the output. When called with the argument <code class="docutils literal notranslate">--host <hostname></code> (where <hostname> is a host from above), the script must print a JSON object, either empty or containing variables to make them available to templates and playbooks. For example: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "VAR001": "VALUE", "VAR002": "VALUE" } </pre></div> </div> Printing variables is optional. If the script does not print variables, it should print an empty JSON object. </section> <section id="tuning-the-external-inventory-script"> <h3><a class="toc-backref" href="#id18" role="doc-backlink">Tuning the external inventory script</a><a class="headerlink" href="#tuning-the-external-inventory-script" title="Link to this heading"></a></h3> <div class="versionadded"> New in version 1.3. </div> The stock inventory script system mentioned above works for all versions of Ansible, but calling <code class="docutils literal notranslate">--host</code> for every host can be rather inefficient, especially if it involves API calls to a remote subsystem. To avoid this inefficiency, if the inventory script returns a top-level element called “_meta”, it is possible to return all the host variables in a single script execution. When this meta element contains a value for “hostvars”, the inventory script will not be invoked with <code class="docutils literal notranslate">--host</code> for each host. This behavior results in a significant performance increase for large numbers of hosts. The data to be added to the top-level JSON object looks like this: <div class="highlight-text notranslate"><div class="highlight"><pre>{ # results of inventory script as above go here # ... "_meta": { "hostvars": { "host001": { "var001" : "value" }, "host002": { "var002": "value" } } } } </pre></div> </div> To satisfy the requirements of using <code class="docutils literal notranslate">_meta</code>, to prevent ansible from calling your inventory with <code class="docutils literal notranslate">--host</code> you must at least populate <code class="docutils literal notranslate">_meta</code> with an empty <code class="docutils literal notranslate">hostvars</code> object. For example: <div class="highlight-text notranslate"><div class="highlight"><pre>{ # results of inventory script as above go here # ... "_meta": { "hostvars": {} } } </pre></div> </div> If you intend to replace an existing static inventory file with an inventory script, it must return a JSON object which contains an ‘all’ group that includes every host in the inventory as a member and every group in the inventory as a child. It should also include an ‘ungrouped’ group which contains all hosts which are not members of any other group. A skeleton example of this JSON object is: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "_meta": { "hostvars": {} }, "all": { "children": [ "ungrouped" ] }, "ungrouped": { "children": [ ] } } </pre></div> </div> An easy way to see how this should look is using <a class="reference internal" href="../cli/ansible-inventory.html#ansible-inventory">ansible-inventory</a>, which also supports <code class="docutils literal notranslate">--list</code> and <code class="docutils literal notranslate">--host</code> parameters like an inventory script would. <div class="admonition seealso"> See also <dl class="simple"> <dt><a class="reference internal" href="developing_api.html#developing-api">Python API</a></dt><dd>Python API to Playbooks and Ad Hoc Task Execution </dd> <dt><a class="reference internal" href="developing_modules_general.html#developing-modules-general">Developing modules</a></dt><dd>Get started with developing a module </dd> <dt><a class="reference internal" href="developing_plugins.html#developing-plugins">Developing plugins</a></dt><dd>How to develop plugins </dd> <dt><a class="reference external" href="https://github.com/ansible/awx">AWX</a></dt><dd>REST API endpoint and GUI for Ansible, syncs with dynamic inventory </dd> <dt><a class="reference internal" href="../community/communication.html#communication">Communication</a></dt><dd>Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide </dd> </dl> </div> </section> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="developing_plugins.html" class="btn btn-neutral float-left" title="Developing plugins" accesskey="p" rel="prev"> Previous</a> <a href="developing_core.html" class="btn btn-neutral float-right" title="Developing ansible-core" accesskey="n" rel="next">Next </a> </div> <hr/> <div role="contentinfo"> © Copyright Ansible project contributors. Last updated on Feb 25, 2025. </div> </footer> </div> </div> </section> </div> <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>