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'Unhan