Developing Ansible Modules – Parameter Validation

AnsibleModule has some handy helper functions that allow us to control which parameters are provided when running our custom module. In this blog note, we’ll look at these and provide examples of a full code block so you can see how to use this in your module.

This post builds on top of the excellent post by Joe Seeder over at his blog mobygeek. Thanks for the inspiration Joe!

Below are the examples detailed in Joe’s blog post but in more detail that you could just copy and paste in to your code!

mutually_exclusive

Use Case: This allows you to specify two parameters that cannot be provided together at the same time.

from ansible.module_utils.basic import AnsibleModule

def main():
    args = dict(
        example_1=dict(required=False, type="str"),
        example_2=dict(required=False, type="str")
    )

    mutually_exclusive_args = [["example_1", "example_2"]]
    module = AnsibleModule(
        argument_spec=args,
        mutually_exclusive=mutually_exclusive_args
    )

required_if

Use Case: When you must supply a specific set of parameters depending on the value of another parameter. For example, this is very useful when using ‘state’, as you may only need a username in the event of a ‘state = absent’ run of the module (i.e. to delete the user)

from ansible.module_utils.basic import AnsibleModule

def main():
    args = dict(
        state=dict(
          choices=["present", "absent"],
          default="present", 
          required=True,
          type="str"
        ),
        username=dict(required=False, type="str"),
        user_roles=dict(required=False, type="str")
    )

    required_if_args = [
      ["state", "present", ["username", "user_roles"]],
      ["state", "absent", ["username"]]
    ]

    module = AnsibleModule(
        argument_spec=args,
        required_if=required_if_args
    )

required_one_of

Use Case: When you must supply at least one of a set of parameters. An example might be a module where you can provide either a password or a password_hash, but we need at least one of them for the module to succeed.

from ansible.module_utils.basic import AnsibleModule

def main():
    args = dict(
        password=dict(
          no_log=True, 
          required=False, 
          type="str"
        ),
        password_hash=dict(
          no_log=True,
          required=False,
          type="str"
        )
    )

    required_one_of_args = [["password", "password_hash"]]

    module = AnsibleModule(
        argument_spec=args,
        required_one_of=required_one_of_args
    )

required_together

Use Case: When two parameters must be supplied together, or not at all. A good example here might be username and password if doing some sort of authentication in your module.

from ansible.module_utils.basic import AnsibleModule

def main():
    args = dict(
        password=dict(no_log=True, required=False, type="str"),
        username=dict(required=False, type="str")
    )

    required_together_args = [["password", "username"]]

    module = AnsibleModule(
        argument_spec=args,
        required_together=required_together_args
    )

1 thought on “Developing Ansible Modules – Parameter Validation

  1. Lohmar Reply

    Hi
    thanks for the great info.
    I’d like to add that with ansible 2.7.7 I’m getting:
    “Module alias error: internal error: required and default are mutually exclusive for …”

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.