Inventory iocage - get inventory alias from iocage tags. (#10207)

* Get inventory hostname from iocage tags.

* Change iocage newe options version_added.

* Update iocage DOCUMENTATION

* Add changelog fragment.

* Update changelogs/fragments/10207-iocage-inventory-alias.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/inventory/iocage.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/inventory/iocage.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/inventory/iocage.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/inventory/iocage.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/inventory/iocage.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Updated copyright.

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/10207-iocage-inventory-alias.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - iocage inventory plugin - the new parameter ``inventory_hostname_tag`` of the plugin provides the name of the tag in the C(iocage properties notes) that contains the jails alias. The new parameter ``inventory_hostname_required``, if enabled, makes the tag mandatory (https://github.com/ansible-collections/community.general/issues/10206, https://github.com/ansible-collections/community.general/pull/10207).

plugins/inventory/iocage.py

@@ -80,6 +80,20 @@ options:
     type: list
     elements: path
     version_added: 10.4.0
+  inventory_hostname_tag:
+    description:
+      - The name of the tag in the C(iocage properties notes) that contains the jails alias.
+      - By default, the C(iocage list -l) column C(NAME) is used to name the jail.
+      - This option requires the notes format C("t1=v1 t2=v2 ...")
+      - The option O(get_properties) must be enabled.
+    type: str
+    version_added: 11.0.0
+  inventory_hostname_required:
+    description:
+      - If enabled, the tag declared in O(inventory_hostname_tag) is required.
+    type: bool
+    default: false
+    version_added: 11.0.0
 notes:
   - You might want to test the command C(ssh user@host iocage list -l) on
     the controller before using this inventory plugin with O(user) specified
@@ -253,6 +267,8 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
         env = self.get_option('env')
         get_properties = self.get_option('get_properties')
         hooks_results = self.get_option('hooks_results')
+        inventory_hostname_tag = self.get_option('inventory_hostname_tag')
+        inventory_hostname_required = self.get_option('inventory_hostname_required')
 
         cmd = []
         my_env = os.environ.copy()
@@ -357,6 +373,21 @@ class InventoryModule(BaseInventoryPlugin, Constructable, Cacheable):
 
                 results['_meta']['hostvars'][hostname]['iocage_hooks'] = iocage_hooks
 
+        # Optionally, get the jails names from the properties notes.
+        # Requires the notes format "t1=v1 t2=v2 ..."
+        if inventory_hostname_tag:
+            if not get_properties:
+                raise AnsibleError('Jail properties are needed to use inventory_hostname_tag. Enable get_properties')
+            update = {}
+            for hostname, host_vars in results['_meta']['hostvars'].items():
+                tags = dict(tag.split('=', 1) for tag in host_vars['iocage_properties']['notes'].split() if '=' in tag)
+                if inventory_hostname_tag in tags:
+                    update[hostname] = tags[inventory_hostname_tag]
+                elif inventory_hostname_required:
+                    raise AnsibleError(f'Mandatory tag {inventory_hostname_tag!r} is missing in the properties notes.')
+            for hostname, alias in update.items():
+                results['_meta']['hostvars'][alias] = results['_meta']['hostvars'].pop(hostname)
+
         return results
 
     def get_jails(self, t_stdout, results):