Writing a new Ansible FreeIPA module

Minimum requirements

A ansible-freeipa module should have:

• Code:

  • A module file placed in plugins/modules/<ipa_module_name>.py

• Documentation:

  • README-<module_name>.md file in the root directory and linked from the main README.md
  • Example playbooks in playbooks/<module_name>/ directory

• Tests:

  • Test cases (also playbooks) defined in tests/<module_name>/test_<something>.yml. It's ok to have multiple files in this directory.

Code

The module file have to start with the python shebang line, license header and definition of the constants ANSIBLE_METADATA, DOCUMENTATION, EXAMPLES and RETURNS. Those constants need to be defined before the code (even imports). See https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#starting-a-new-module for more information.

Although it's use is not yet required, ansible-freeipa provides FreeIPABaseModule as a helper class for the implementation of new modules. See the example bellow:

from ansible.module_utils.ansible_freeipa_module import FreeIPABaseModule


class SomeIPAModule(FreeIPABaseModule):
    ipa_param_mapping = {
        "arg_to_be_passed_to_ipa_command": "module_param",
        "another_arg": "get_another_module_param",
    }

    def get_another_module_param(self):
        another_module_param = self.ipa_params.another_module_param

        # Validate or modify another_module_param ...

        return another_module_param

    def check_ipa_params(self):

        # Validate your params here ...

        # Example:
        if not self.ipa_params.module_param in VALID_OPTIONS:
            self.fail_json(msg="Invalid value for argument module_param")

    def define_ipa_commands(self):
        args = self.get_ipa_command_args()

        self.add_ipa_command("some_ipa_command", name="obj-name", args=args)


def main():
    ipa_module = SomeIPAModule(argument_spec=dict(
        module_param=dict(type="str", default=None, required=False),
        another_module_param=dict(type="str", default=None, required=False),
    ))
    ipa_module.ipa_run()


if __name__ == "__main__":
    main()

In the example above, the module will call the command some_ipa_command, using "obj-name" as name and, arg_to_be_passed_to_ipa_command and another_arg as arguments.

The values of the arguments will be determined by the class attribute ipa_param_mapping.

In the case of arg_to_be_passed_to_ipa_command the key (module_param) is defined in the module argument_specs so the value of the argument is actually used.

On the other hand, another_arg as mapped to something else: a callable method. In this case the method will be called and it's result used as value for another_arg.

NOTE: Keep mind that to take advantage of the parameters mapping defined in ipa_param_mapping you will have to call args = self.get_ipa_command_args() and use args in your command. There is no implicit call of this method.

Disclaimer

The FreeIPABaseModule is new and might not be suitable to all cases and every module yet. In case you need to extend it's functionality for a new module please open an issue or PR and we'll be happy to discuss it.