• Ansible Module Development – parameters

    by  • 16th February 2016 • post

    Some time ago, I have started writing a lot of ansible modules. As well as started providing  lightweight docker image.

    Things like Marathon, Chronos, or Consul needed love, which I given them.

    Quite recently I have been tasked to work on Azure platform and I have noticed that it will again need my love.

    During the development process, I have noticed that documentation is pretty vague on what you can do when you are initializing parameters for the module. They are only showing examples how to put requirements or types on individual params, but there is no documentation on how you can put logic into interaction between parameters.

    Lets say, in Azure resource group deployment you can specify a template-file or template-uri , but can’t do both.

    Example :

    /ansible # azure group deployment create --help
    help: Creates a deployment
    help: 
    help: Usage: group deployment create [options] [resource-group] [name]
    help: 
    help: Options:
    ...
    help: -f --template-file  the path to the template file in the file system
    help: --template-uri  the uri to the remote template file
    

    How to implement it ?

    lets say we will have 3 arguments for the module :

    • a
    • b
    • state

    So in python we will declare the module as follows:

    mutually_exclusive
    module = AnsibleModule(
      argument_spec=dict(
       a=dict(type="int"),
       b=dict(type="bool"),
       state=dict(default="present", choices=['present', 'absent']
      )
      mutually_exclusive=[
        [ 'a', 'b' ]
      ]
    )
    

    As you can see, “mutually_exclusive” takes a list of lists, where each embedded list consists of names of parameters which can not appear together.

    There is more

    I have been trying to find a nice list of these filters/constrains but could not find it , so I dug down into the code and fond a few more.

    required_together

    This is self explanatory, all specified parameters need to be specified together:

    required_together=[
      [ 'a', 'b' ]
    ]
    

    You can not specify “a” without specifying “b” parameters

    required_one_of

    at least one of them needs to be specified, in case of our template we would use this constrain as well, ( we need at least one of, but not all of them at once )

    required_of=[
      [ 'a', 'b' ]
    ]
    
    required_if

    This one is a little bit more complicated, it checks the value of one parameter and if that value matches, it requires specified parameters to be present as well.

    Imagine you require to pass arguments “a” and “b” only when your “state” is “present”, and when “state” is “absent”, only “a” is required.

    required_if=[
      [ "state", "present", [ "a", "b" ] ],
      [ "state", "absent", [ "a" ] ]
    ]
    
    
    

    Hope this quick little guide to parameter constrains for ansible modules helped you a bit.

    I’ve used the code from ansible/module_utils/basic.py to find these gems.