Custom Module: iim_package
Relevant source files
The following files were used as context for generating this wiki page:
The iim_package module is a core component of the spm_middleware collection designed to manage the lifecycle of IBM software packages via the IBM Installation Manager (IIM). It provides a high-level Ansible interface for installing, updating, and uninstalling products such as IBM HTTP Server (IHS), WebSphere Application Server (WAS) Network Deployment, and WebSphere Liberty.
This module works in conjunction with the iim role, which ensures that the IBM Installation Manager agent is present on the target system before package operations are attempted. It leverages the IIMAgent utility class to interface with the underlying IIM binaries to perform state-based management of enterprise middleware components.
Sources: plugins/modules/iim_package.py:10-15, roles/iim/README.md:3-8
Module Architecture and Logic
The module follows the standard Ansible module structure, utilizing an argument_spec to define supported parameters and interacting with the system through a specialized agent.
Core Components
- IIMAgent: A utility class imported from
ansible_collections.merative.spm_middleware.plugins.module_utils.iimthat encapsulates the logic for interacting with the IBM Installation Manager command-line interface. - AnsibleModule: The standard Ansible library used to handle input parameters and return JSON results to the execution engine.
Sources: plugins/modules/iim_package.py:90-100
Execution Workflow
The module's logic is primarily driven by the state parameter. It performs idempotency checks by verifying if a base version or an exact version of the requested product_id is already present before taking action.
The diagram illustrates the decision logic based on the requested state and current system inventory.
Module Parameters
The following parameters are available for configuring the iim_package module:
| Parameter | Type | Default | Description |
|---|---|---|---|
iim_path | path | /opt/IBM/InstallationManager | Absolute path to the IBM Installation Manager installation. |
shared_resources | path | /opt/IBM/IMShared | Absolute path to the IIM shared resources directory. |
product_id | list | (Required) | List of product IDs or families (e.g., com.ibm.websphere.IHS.v90) to be managed. |
repos | list | List of repository paths or URLs containing the installation files. Aliased as repo. | |
path | path | Absolute path where the product should be installed. | |
state | str | present | Desired state of the package. Choices: absent, present. |
preferences | dict | Dictionary of preferences to pass to the IIM installer. | |
properties | dict | Dictionary of properties to pass to the IIM installer. |
Sources: plugins/modules/iim_package.py:16-56, plugins/modules/iim_package.py:92-101
Practical Implementation Examples
Installing IBM HTTP Server (IHS)
The module is frequently used within the ihs role to install the base server along with Java SDKs. It can handle multiple product IDs in a single task execution.
- name: Install IHS
iim_package:
iim_path: "{{ iim_install_path }}"
product_id:
- "com.ibm.websphere.IHS.v90"
- com.ibm.java.jdk.v8
path: "{{ ihs_install_path }}"
repo: "{{ repo_list }}"
properties:
"user.ihs.httpPort": 80
state: present
Sources: roles/ihs/tasks/v90_base_install.yml:71-82
Managing WebSphere Liberty
In the liberty role, the module is used to ensure the exact version specified in the liberty_pid is installed. This highlights the module's ability to handle specific version strings within the product_id.
# Internal logic check for installation
if state == 'present' and (not iim.have_base_version(product_id[0]) or not iim.have_exact_version(product_id[0])):
result = iim.install_package(product_id)
Sources: plugins/modules/iim_package.py:121-123, roles/liberty/tasks/main.yml:15-18
Return Values
The module returns the following information, which can be registered for use in subsequent tasks:
| Key | Type | Returned | Description |
|---|---|---|---|
packages | list | always | A list of all packages currently installed in the IIM instance. |
base_installed | str | always | Boolean-like indicator if the base product family is installed. |
exact_installed | str | when supported | Indicator if the specific version string requested matches the installed version. |
changed | bool | always | Indicates if the module performed any installation or removal. |
Sources: plugins/modules/iim_package.py:68-83, plugins/modules/iim_info.py:38-53
Integration with iim_info
Before calling iim_package, roles often use the iim_info module to inspect the current state of the environment. iim_info provides the inventory data that allows roles to conditionally execute installation tasks.
Sequence diagram showing the typical interaction between the info and package modules during a middleware deployment.
Sources: plugins/modules/iim_info.py:59-86, roles/websphere/tasks/main.yml:6-14
Summary
The iim_package module provides an idempotent wrapper around the IBM Installation Manager. By abstracting the complex CLI flags of IIM into standard Ansible parameters like product_id, repo, and state, it enables consistent deployment of IBM middleware across the SPM ecosystem. It is the primary tool used by the collection to ensure that components like WAS, IHS, and Liberty are correctly versioned and configured.