Inventory plugin loader ignores NAME attribute and uses filename instead

[Yannik]

Summary

The NAME configured for an inventory plugin is ignored by the plugin loader (not set as plugin name, nor as alias), and cannot be used with ANSIBLE_INVENTORY_ENABLED.

Issue Type

Bug Report

Component Name

plugins/loader.py

Ansible Version

$ ansible --version
ansible [core 2.18.2]
  config file = None
  configured module search path = ['/home/yannik/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /home/yannik/venv/lib/python3.12/site-packages/ansible
  ansible collection location = /home/yannik/.ansible/collections:/usr/share/ansible/collections
  executable location = /home/yannik/venv/bin/ansible
  python version = 3.12.3 (main, Jan 17 2025, 18:03:48) [GCC 13.3.0] (/home/yannik/venv/bin/python3)
  jinja version = 3.1.5
  libyaml = True

Configuration

$ ansible-config dump --only-changed -t all
CONFIG_FILE() = None
GALAXY_SERVERS:

OS / Environment

Ubuntu 24.04

Steps to Reproduce

Create inventory_plugins/dynamic-inventory-plugin.yml

from ansible.plugins.inventory import BaseInventoryPlugin

class InventoryModule(BaseInventoryPlugin):
    NAME = ' myorg.mygroup.custom_inventory '

    def verify_file(self, path):
        return True

    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)

        self.inventory.add_host('localhost')

Then execute ANSIBLE_INVENTORY_ENABLED=myorg.mygroup.custom_inventory ANSIBLE_INVENTORY_PLUGINS=$(pwd)/inventory_plugins ansible-inventory –list

Expected Results

The command should list the host localhost defined in the inventory plugin.

Actual Results

The following error occurs:

[WARNING]: Failed to load inventory plugin, skipping myorg.mygroup.custom_inventory
ERROR! No inventory plugins available to generate inventory, make sure you have at least one enabled.

By appending a couple of lines of debugging code to plugins/loader.py:

for plugin in inventory_loader.all():
  display.warning("_original_path: %s" % plugin._original_path)
  display.warning("_load_name: %s " % plugin._load_name)
  display.warning("ansible_name %s " % plugin.ansible_name)
  display.warning("aliases: %s " % plugin.ansible_aliases)

we can observe that NAME is ignored and instead the filename is set as plugin name and alias:

[WARNING]: _original_path: /home/yannik/ansible-test/inventory_plugins/dynamic-inventory-plugin.py
[WARNING]: _load_name: dynamic-inventory-plugin
[WARNING]: ansible_name dynamic-inventory-plugin
[WARNING]: aliases: ['dynamic-inventory-plugin']

Code of Conduct

• [x] I agree to follow the Ansible Code of Conduct

[ansibot]

Files identified in the description:

None

If these files are incorrect, please update the component name section of the description or use the component bot command.

[bcoca]

Correct, NAME is not used for finding/loading/configuring the plugin. It is used for verifying that the correct file was loaded in case there was a file name clash.

[sivel]

Per above, the NAME is not used for loading. You should aim for the filename and the NAME to match. You cannot create a fake collection by specifying a NAME that looks like a collection, it must actually reside within a collection. In the end the filename is what is used for loading. We believe there is a documentation inconsistency that we can adjust to further clarify this.

I'll migrate this issue to our docs repo.

[ansible-documentation-bot[bot]]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on Matrix at #docs:ansible.im if you ever want to join us and chat about the docs! We meet on Matrix every Tuesday. See the Ansible calendar for meeting details. We welcome additions to our weekly agenda items too. You can add the dawgs-meeting tag to a forum topic to bring it up at the next meeting.