How to create a hello world Ansible module with Documentation

If you cannot locate a plugin that suits your needs by using Ansible, you can easily extend the default functionality by creating your own python module. In this article I will explain the procedure for the creation of a module.

First of all you should create a python code and use Ansible SDK. A detailed description for the creation of the development environment can be found on official documentation.

The example module is a hello world, that gets as an input your name, surname and prints a hello message.

Copy your hello.py on ansible modules location. On my working machine this is the path /usr/local/lib/python3.9/site-packages/ansible/modules

When you include your documentation on the python file, you can explore it with:

ansible-doc hello
Documentation for module

If you try a module run without the required parameters, it will fail as shown below:

Plugin run without required parameters

Run your custom module by using the below playbook:

Input with only name as parameter:

---
- name: test playbook using custom code
  hosts: localhost
  tasks:
    - name: using my custom module
      hello:
        name: Gerasimos
      register: result
      
    - name: show output
      debug:
        var: result

Input with name and surname as parameters:

---
- name: test playbook using custom code
  hosts: localhost
  tasks:
    - name: using my custom module
      hello:
        name: Gerasimos
        surname: Alexiou
      register: result
      
    - name: show output
      debug:
        var: result

Code for the example module can be found on my github repo.

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.