Introduction

Ansible is a powerful automation tool used for configuration management, application deployment, and task automation. While it comes with a rich set of modules and plugins, there are times when you might need to extend its capabilities by writing custom plugins. In this article, we will walk you through the process of creating a custom Ansible plugin to retrieve user data from an API endpoint.

Why Create a Custom Plugin?

Creating a custom plugin allows you to:

  • Extend Ansible's functionality to meet specific needs.
  • Integrate with external APIs that are not covered by existing modules.
  • Simplify complex tasks by encapsulating them in reusable plugins.

Our Goal

We will create a custom lookup plugin that fetches a list of users from https://reqres.in/api/users?page=2 and makes this data available for use in Ansible playbooks.

Prerequisites

  • Basic understanding of Ansible and Python.
  • Ansible installed on your machine.
  • Internet connection to access the API.

Step-by-Step Guide

Step 1: Directory Structure

Create the necessary directory structure for the custom plugin. By default, Ansible looks for plugins in the lookup_plugins directory within your project.

``sh

mkdir -p my_ansible_project/lookup_plugins

`

Step 2: Write the Plugin Code

Create a file named list_users.py inside the lookup_plugins directory with the following content:

`python

python 3 headers, required if submitting to Ansible

from __future__ import (absolute_import, division, print_function)

__metaclass__ = type

DOCUMENTATION = r"""

name: list_users

author: Your Name <[email protected]>

version_added: "0.1"

short_description: Retrieve list of users from an API

description:

- This lookup retrieves the list of users from the provided API.

"""

from ansible.errors import AnsibleError

from ansible.plugins.lookup import LookupBase

from ansible.utils.display import Display

import requests

display = Display()

class LookupModule(LookupBase):

_URL_ = "https://reqres.in/api/users?page=2"

def run(self, terms, variables=None, **kwargs):

try:

res = requests.get(self._URL_)

res.raise_for_status()

users = res.json().get('data', [])

except requests.exceptions.HTTPError as e:

raise AnsibleError(f'There was an error retrieving users. The lookup API returned {res.status_code}')

except Exception as e:

raise AnsibleError(f'Unhandled exception in lookup plugin. Origin: {e}')

return users

`

This code defines a custom lookup plugin that makes a GET request to the specified API endpoint and returns the list of users. The run method handles the API request and error handling.

Step 3: Using the Custom Plugin in a Playbook

Now that we have our custom plugin, let's use it in an Ansible playbook. Create a playbook file named test_plugin.yml with the following content:

``yaml

---

  • name: Test custom plugi