Implement #9650 Add parameter hooks to inventory plugin iocage

[vbotka]

SUMMARY

Implement #9650 Add parameter hooks to inventory plugin iocage.

ISSUE TYPE

• Feature Pull Request

COMPONENT NAME

iocage.py

ADDITIONAL INFORMATION

Tested in Ubuntu 24.04

[felixfontein]

Thanks for your contribution!

I'm wondering a bit about the term hook. Is this some nomenclature that's used in the iocage surroundings for such things? If not, maybe another name would be better. I'm not very good at coming up with names, but maybe something like read_file_contents, resulting in iocage_file_contents being set?

[felixfontein]

Maybe a warning should be printed in this case? (Or the behavior should be configurable - ignore, warn, error.)

[vbotka]

The jails may be heterogeneous, and a hook that works for one jail may not work for the other. I want to keep the spirit of silently ignoring No such file or any other error:

• I don't want to complicate the use case where different jails use different hooks or no hooks at all. List all hooks and let the compose option pick what is needed.

• The admins should be responsible for intercepting anything. And they should be used to it, especially in the case of the hooks. For example, the /etc/dhclient-enter-hooks and /etc/dhclient-exit-hooks silently ignore any failing lines in the scripts. It is expected, that the admin is responsible for checking what a hook is doing. There are also security implications.

We can add the options (ignore, warn, error) later.

[felixfontein]

Same here.

Also, why not using None instead of -? None can never appear as a real value, so you can distinguish "error happened" from "- was actually read".

[vbotka]

The dash "-" is used in iocage to represent a missing value. See for example ioc_list.py#L259 or ioc_list.py#L276. We've already used it too:

if iocage_ip4_dict['ip4']:
    iocage_ip4 = ','.join([d['ip'] for d in iocage_ip4_dict['ip4']])
else:
    iocage_ip4 = '-'

[vbotka]

I'm wondering a bit about the term hook. Is this some nomenclature that's used in the iocage surroundings for such things? If not, maybe another name would be better.

The nomenclature is general. A hook is a method to intercept . For example,

• Linux kernel hooking library
• Using ftrace to hook to functions
• Package maintainer scripts and hooks

In particular, dhclient-script says:

... dhclient-script will check for the existence of /etc/dhclient-enter-hooks. If found, it will be sourced (see sh(1)). After taking action according to $reason, dhclient-script will check for the existence of /etc/dhclient-exit-hooks. If found, it will be sourced (see sh(1)). These hooks scripts can be used to dynamically modify the environment at appropriate times during the DHCP negotiations.

There is no better name.

[felixfontein]

But generally hooks are running code. I would expect to be able to provide a script that runs something when reading "hook". So I think the name "hook" is not a good choice in this context.

[vbotka]

I see. I renamed the parameter to hooks_results.

[russoz]

LGTM as far as I can tell.

One thing I noticed, but probably for a different PR, is that the YAML indentation is not consistent within the file (or with other plugins for that matter).

[vbotka]

... YAML indentation is not consistent within the file ...

Thank you for the review!

• I fixed the 4-space indentation in the DOCUMENTATION block. There is the 2-space indentation in the EXAMPLES block. Both blocks pass the YAML lint. YAML doesn't enforce the indentation size. The syntax of the YAML blocks is correct.

• I assume the 4 spaces in DOCUMENTATION might be needed to merge the fragments, but I'm not sure when I see the inconsistencies for example in constructed.py. The rendering is horrible

shell> ansible-doc -t inventory community.general.iocage
  ...
   keyed_groups  Add hosts to group based on the values of a variable.
        default: []
        elements: dict
        type: list
        suboptions:

           default_value          The default value when the host variable's value is an empty
                          string.
                          This option is mutually exclusive with
                          `keyed_groups[].trailing_separator'.
          default: null
          type: str
          added in: version 2.12 of ansible-core

           key          The key from input dictionary used to generate groups.
          default: null
  ...