Creating New Ansible Roles
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Creating new Ansible roles within the spm-middleware collection allows for the modular distribution of middleware components required for installing Cúram Social Program Management (SPM). Roles are packaged within a structured collection format that includes plugins, playbooks, and documentation, ensuring they can be reused across different internal test and development environments.
Sources: README.md:1-12, CONTRIBUTING.md:118-121
The development process emphasizes technical standards such as idempotency, automated linting, and comprehensive Molecule testing. Each role must adhere to a specific directory structure and metadata requirements to be compatible with Ansible Galaxy and the internal deployment pipelines.
Sources: CONTRIBUTING.md:123-128, CONTRIBUTING.md:139-142
Role Structure and Initialization
New roles must follow the standard Ansible collection layout. A skeleton structure is provided to ensure consistency across the project. Roles are primarily located within the roles/ directory of the repository.
Sources: README.md:23-40, CONTRIBUTING.md:144-148
Initialization Command
To create a new role using the project-specific skeleton, developers should use the ansible-galaxy command. This ensures the necessary directories and files (like meta/main.yml and tasks/main.yml) are present.
ansible-galaxy role init --init-path ./roles --role-skeleton ./skeleton_role <role_name>
Sources: CONTRIBUTING.md:150-153
Minimum File Requirements
Every new role must contain at least the following three files:
README.md: Describes functionality, requirements, and variables.meta/main.yml: Contains authorship, licensing (standardized as MIT), and platform compatibility.tasks/main.yml: Contains the main entry point for the role's execution logic.
Sources: CONTRIBUTING.md:144-148, roles/websphere/meta/main.yml:10-14
Metadata and Platform Compatibility
The meta/main.yml file is critical for role discovery and dependency management. It defines the minimum Ansible version supported (typically 2.9) and the supported Operating Systems.
Sources: roles/websphere/meta/main.yml:16-18, roles/weblogic/meta/main.yml:16-18
Supported Platforms
The project focuses on Enterprise Linux (EL) distributions, specifically versions 7, 8, and 9 for most middleware roles.
| Role | Supported Platforms | Minimum Ansible |
|---|---|---|
| WebSphere | EL 7, 8 | 2.9 |
| WebLogic | EL 7, 8, 9 | 2.9 |
| IIM | EL 7, MacOSX, Ubuntu, Windows | 2.9 |
Sources: roles/websphere/meta/main.yml:28-32, roles/weblogic/meta/main.yml:28-33, roles/iim/meta/main.yml:28-37
Development and Testing Workflow
The project uses a containerized development environment called "Molecule" to verify roles. All contributions must pass these tests before being merged.
Testing Lifecycle
The following diagram illustrates the standard Molecule testing flow used in the project for role verification:
The workflow ensures that the role can be applied multiple times without changing the system state after the initial run (idempotency) and that the final state matches expectations.
Sources: CONTRIBUTING.md:20-25, CONTRIBUTING.md:123-128
Local Environment Setup
Developers are encouraged to use a Python virtual environment to manage dependencies for Molecule and Ansible Lint.
- Initialize venv:
python3 -m venv ~/venv/molecule - Install requirements:
pip install -r ci-requirements.txt - Install Molecule with Docker driver:
pip install "molecule[docker,lint]"
Sources: CONTRIBUTING.md:4-8, CONTRIBUTING.md:168-176
Configuration and Variables
Roles should expose configuration options through variables to remain flexible. These are typically documented in the role's README.md.
Common Role Variables
Middleware roles often share common variable patterns for installers and directories.
| Variable Name | Description |
|---|---|
download_url | HTTP server URL for license and installer downloads. |
download_header | Headers (e.g., Authorization) used for the download request. |
profiled_path | Target directory for shell profile scripts (usually /opt/profile.d). |
Sources: roles/ohs/README.md:18-35, roles/weblogic/README.md:13-25
Role Dependencies
Dependencies between roles must be explicitly declared in the meta/main.yml file. For example, the websphere role requires the iim role to be present in the execution path.
Sources: roles/websphere/README.md:41, roles/websphere/meta/main.yml:50-52
While some roles like ohs can be used independently, they often require other middleware components (like WebLogic) to function correctly in a production-like context.
Sources: roles/ohs/README.md:39-41, roles/websphere/README.md:55-58
Summary
Creating a new role for spm-middleware involves initializing the role from a skeleton, defining platform support and metadata in meta/main.yml, and implementing idempotent tasks. The process is finalized by creating Molecule scenarios to verify the role against supported EL platforms and ensuring it passes the project's linting standards.