How to Build Custom Ansible Module

Sharing is caring!

Ansible Custom Module

I am going very short about Ansible module description, here is from Ansible website:

Ansible ships with a number of modules (called the ‘module library’) that can be executed directly on remote hosts or through Playbooks. Users can also write their own modules. These modules can control system resources, like services, packages, or files (anything really), or handle executing system commands.

Ansible built-in modules are practical and handy. Indeed, their modules cover your needs. But, in several cases, you need more. So let say their built-in modules sometimes is not enough. Hence Ansible custom module comes to play.

Use Case

Let’s build a simple custom module. It is a dice game. The game is about guessing the result. And you have maximum three chances for each guess.


First of all, we need to create project structure as follow:


There are several steps for implementing our dice game in this file.

Import required library

Since this has correlation with ansible module, then we need import ansible module utils. And one more thing, because dice means probability, so we need to import python random class as well.

Note: the hash bang (#!) is required for creating custom module

Main method

Next step is creating an entry point, which is the main() method. In this main method, we determine each field that are going to be define in playbook, then pass those fields into AnsibleModule constructor. Subsequently, pass the module.params object into custom function, then exit the program gracefully using exit_json, if success or fail_json whenever it fails.


  • roll_dice function will be implemented in next paragraph.
  • each field contains choices key, to limit the input between those number. This key is optional.

roll_dice Function

This function is basically

  • Produce random number between 1 – 6 (of course, this is dice).
  • Check the outcome between the guess number.
  • Change Ansible state and you win. Otherwise you lose and no state will be changed.

Note: Getting value from yml input can be done by putting field name as a dictionary key.


It is time to put our module in playbook file. Please take a note on two things. First, module name refers with filename (without .py extension) under library folder. Second, module parameters refer with key dictionary in fields property (see main method section).

Run Playbook

Now it is time to run the playbook by executing this command:

Then, you should get output similar with this. Hopefully you have some lucky guesses 🙂

Sorry, you lose


And that’s all folks. Viola! Now we can continue to create more useful custom module, such as creating server group in wildfly domain mode or deploying war files into application server. Hopefully, I will take those topics up in the next post (*finger crossed*).

PS: you can checkout this full example on my github, in the subfolder dice_module.

Author: ru rocker

I have been a professional software developer since 2004. Java, Python, NodeJS, and Go-lang are my favorite programming languages. I also have an interest in DevOps. I hold professional certifications: SCJP, SCWCD, PSM 1, AWS Solution Architect Associate, and AWS Solution Architect Professional.

Leave a Reply

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