Create an ansible module

In the last article, I explained why I moved all my domains to Porkbun. One of the reasons was the API and its compatibility with Ansible. I frequently use Ansible to set up and manage my home server as well as a few remote ones. This often involves creating and managing DNS records. However, the method I demonstrated in the New DNS Registrar article is quite verbose, requiring at least three tasks with numerous parameters. I believe we can improve upon it.

Let's write an Ansible module to summarize the logic of the three tasks.

In order to create a module we need a single file and a some python knowledge. First we create a library folder and inside it we create a file with the name of our module. In the case of our porkbun module, we choose porkbun_record.py. We start our module with a class which handles the porkbun api.

We need methods to get, create, update, and delete records. For each of those methods, we need the api_key and the secret_api_key. Therefore, we pass the keys in the constructor (the __init__ method). To use the keys, we have to store them for later use. In addition to the keys, we define the API_URL and specify the default headers for our method calls. Now, our constructor should look like the following:

We need methods to get, create, update, and delete records. For each of those methods, we need the api_key and the secret_api_key. Therefore, we pass the keys in the constructor (the __init__ method). To use the keys, we have to store them for later use. In addition to the keys, we define the API_URL and specify the default headers for our method calls. Now, our constructor should look like the following:

After that, we can begin the implementation of our methods.

As we can see, we use the open_url method to make a POST request to the Porkbun API. We use f to format the URL with our API_URL and the domain we want to retrieve the records for. We also pass the headers and the data to the open_url method, which we defined in the constructor. The open_url method returns a file-like object that we can read and parse with the json module. The DNS records are stored in the records key of the JSON response.

For the get_record method, we use the get_records method we just implemented. We iterate over the records and return the first record that matches the record_type and name parameters.

For the create_record method, we create a dictionary with the base_params and the parameters we want to pass to the API. We then make another POST request to the API, as we did in the get_records method.

The update_record method is very similar to the create_record method and does not require further explanation.

For the delete_record method, we require the record_id, which is returned by the get_records method.

Now that we have implemented the PorkbunAPI class, we can move on to the module itself.

An Ansible module requires a main method, which is the entry point of the module. It also requires some metadata, which we define in the ANSIBLE_METADATA variable.

In the main method, we define the parameters that we want to pass to the module. In our case this are the parameters which are required for our PorkbunAPI class. We define the parameters with the argument_spec variable, which is a parameter of the AnsibleModule class. But before we can use the AnsibleModule class, we need to import it at the top of our file.

Now we can start to implement the main method.

The state parameter is used to determine whether we want to create or delete a record. After we can use the PorkbunAPI class to create an instance of the API.

Now we can fetch the state of the record, we want to manage.

Now it is time to implement the logic for the present state.

If the record does not exist, we create it. The module.exit_json method is used to return the result of the module. The changed key indicates whether the module changed the state of the system. The msg key contains a message that is displayed to the user. If the record exists, we check if the content is the same as the one we want to set. If it is not, we update the record.

If the content is the same, we do not need to do anything and we can exit the module.

Now we can implement the logic for the absent state.

If the record exists, we delete it. If the record does not exist, we do not need to do anything and we can exit the module.

Finally, we need to call the main method.

Now we can test our module.

To test our module, we create a playbook with the following content.

Ok, we are ready to test our module.

If everything works as expected, we should see that the module created the DNS record. That is it, we have created an Ansible module to manage DNS records with the Porkbun API.

After we have tested our module, we can publish it to Ansible Galaxy. But before we can publish it, we should add some documentation to our module.

We start with the DOCUMENTATION variable. The DOCUMENTATION variable is a YAML string which contains the documentation for our module.

Next we define the EXAMPLES variable.

We also define the RETURN variable.

We also need a README.md file, which should contain a short documentation of our module.

Now we can publish our module to Ansible Galaxy. To publish our module, we have to create a collection. Collections use a different folder structure than our module does. Therefore, we have to move our module to a folder called plugins/modules folder. We also have to create a galaxy.yml file in the root of our collection. The galaxy.yml file contains metadata about our collection.

Now we can build our collection.

The build command creates a tarball with the namespace, name and version of the collection (sdorra-porkbun-1.0.0.tar.gz). This tarball can be uploaded to Ansible Galaxy. To upload the tarball, we have to create an account on Ansible Galaxy and create an API key. After we have our API key, we can upload the tarball.

After we have published our collection, we can install it with the ansible-galaxy command.

And use it in our playbooks:

In this article, we have seen how to create an Ansible module for managing DNS records on Porkbun. We have also learned how to publish the module to Ansible Galaxy. For the complete source code of the module, please visit the GitHub repository. The final version of the module is also available on Ansible Galaxy.