September 2018

First thing, we need to know about the module and its working, let’s take an example code and try to explain what it does for you?
Sample Code: mapr_service.py
you can treat the ansible module as a python script that does a very specific thing and it is exactly working as a script. Instead of running script manually with python3 <test-module>.py , we going to run the script with Ansible.

Ansible will handle a lot of things for us like

  1. Input / Outputs
  2. Formatting
  3. Compatibility across various OS
  4. Input / Output Validation & Verification
  5. No Need to create/manage SSH or WINRM or API Sessions

Part 1 ( Header )

It includes various things like
1. Shebang to include Python3
2. Copyright Content ( if applicable )
3. Imports of Some default classes for compatibility.

Part 2 ( Documentation + Example )

We have to write to optional things called documentation and examples code snippets in YAML format in this part.

Part 3 ( Beginning of Code + Inputs )

Now, we need to import Ansible libraries to make our script compatible with Ansible and Ansible based input handling.
AnsibleModule provides various ansible functions/classes which handle inputs and their validation for the script.

Part 4 ( Inbuilt Helper Functions )

we can write helper functions or classes as well inside our script but it will much better to keep them in separate helper libraries later I will explain where to put them and how to use them but for now, you can do them inside the same module. The above function only runs a command in the Linux shell and will return the hostname of a given machine.

Part 5 ( Input handling )

This part is optional, it’s not required at least in this module but I never updated it :D.
1. Variable assignment is just to make code a bit beautiful.
2. If-Else for maprUsername, maprPassword, serviceName, serviceState, mcsUrl, and serviceState should be handled by using Ansible built-in functions like required_if / etc. and that will reduce our codebase.

Part 6 ( Actual Job Code + Outputs )

Now, the actual magic code that will do our actual job. let’s try to understand it.
First, I get the hostname of the current machine with helper function then I create a string of parameters then API Url and last headers for API call.
Once we have all these values we just use another Ansible Function called fetch_url because it provides wrapper on urllib2/similar library and returns results in JSON as required by Ansible.
At last, we need to parse API response so we can show them in Ansible output as per response like if status is not 200 then we should fail ansible with fail_jsonand print error and response of API call so user can understand what thing failed and fix it.

Part 7 ( Call to Main Function )

At last, we should run our main function in a #pythonic way.

Part 8 ( Testing )

Let’s write a sample task as well to test our code and run against one of our test servers where you can see the response and debug it further.

Please do use -vvvv parameter with ansible so you can see much more details for ansible task and while development of module, set no_log=False so you can see masked fields as well.

Now you know a bit more about Ansible Module Creation Process. this part got a bit longer because it’s easy to understand in one shot than to break it down across multiple articles.

I will write the next part very soon as well about making a real collection. :)

Senior Software Engineer III ( R&D )