Ansible IS Module

This project implements a set of Ansible modules and utilities designed for the integration and management of Information System (IS) resources. The project's architecture is detailed below, broken down by its core components.

Project Architecture

The architecture of this Ansible module is designed to promote modularity, code reuse, and maintainability. It adheres to Ansible best practices by decoupling connection logic and API abstractions (in utilities) from the specific resource implementations (in modules).

REF: https://docs.ansible.com/projects/ansible/latest/dev_guide/developing_modules_general.html

plugins/modules Directory

The plugins/modules directory (often simply referred to as modules in the context of development) constitutes the operational core of the Ansible integration. It contains the custom modules written in Python that Ansible executes on target nodes or locally. Each module exposes a declarative interface to manage a specific domain entity or resource.

The modules within this directory are designed to be idempotent and to return standardized output (JSON) compatible with the Ansible ecosystem. The responsibilities of the current modules include:

• is_token.py: Responsible for managing the lifecycle of authentication tokens required to interact with the API services. It handles token negotiation, retrieval, and validation, ensuring that subsequent requests are properly authorized.
• is_context.py: Handles the definition and management of the operational context. This module allows isolating and configuring the logical environment where other resources (such as services and relations) will be allocated or modified, ensuring proper data partitioning.
• is_eservice.py: Manages the "EService" entity. It enables the creation, update, reading, or deletion of exposed services, acting as a bridge between the Ansible playbooks and the service registry.
• is_query_template.py: Manages the Query Template definitions within the registry. Query Templates provide a reusable and parameterizable way to search for resources using the Query by Example (QBE) paradigm.
• is_relation.py: Governs the correlations and constraints between different system entities. It allows declaratively defining how various services or contexts interact and depend on one another.

plugins/module_utils Subdirectory

The plugins/module_utils subdirectory serves as the fundamental support library for the modules. Its primary purpose is to encapsulate shared logic, reducing code duplication in the main modules and centralizing core interactions.

• Purpose and Functionalities: It provides abstractions for HTTP/HTTPS communication, standardized Ansible error handling, JSON response parsing, and authentication configuration. The files within this directory (such as is_common.py) define base classes and helper methods that are imported and extended by the operational modules. They handle shared operations such as executing query templates, finding specific facets, and verifying relation existence across all API abstractions.
• Structure: It is organized into Python modules that group functionalities by logical domain. For instance, the management of a persistent HTTP session or the standard construction of request headers are centralized in this area, guaranteeing that all modules behave consistently from a network integration standpoint.

tests Directory

The tests directory is dedicated to the automated and manual validation of the developed modules' behavior. It is a critical element for ensuring code stability and correctness (Test-Driven Development or Integration Testing).

• Organization and Structure: The folder is primarily structured with Ansible playbooks (.yml files) and environmental configuration files.
  • Test Playbooks (e.g., test_is_context.yml, test_is_instance.yml, test.yml): These YAML files define test scenarios (Integration Tests). Each playbook invokes one or more custom modules, simulating real-world usage within an Ansible workflow. They verify idempotency (running the module twice to confirm no unnecessary changes occur), correct input handling, and expected outputs.
  • inventory: Contains the definition of the hosts on which the tests will be executed. Often, for modules interacting with remote APIs, localhost is used with specific directives to mock or contact staging environments.
• Role in the Project: It guarantees code non-regression. The tests serve both as a continuous validation mechanism and as living documentation: by reading the test playbooks, developers and operators can quickly understand how to use the various parameters of the is_* modules and what results to expect in specific scenarios.