Concept - Ansible4IOM Server Configuration Management

Table of Contents

Product Version


Product To Version



Ansible4IOM is a tool of the Intershop Order Management (IOM) for automated server configuration management. Additionally, operational tasks are predefined in operational processes which can be customized by using hooks.

This document describes the general concepts of Ansible4IOM.

In a nutshell, server configuration management is a solution for turning infrastructure administration into a codebase, describing all processes necessary for deploying a server in a set of provisioning scripts that can be versioned and easily reused. This document is addressed to administrators who want to install and operate IOM in their Linux based infrastructure. It enables them to use the IOM Ansible sample configuration for the configuration management tool Ansible to automate the installation, configuration and deployment of all required IOM artifacts.


Ansible4IOMAnsible4IOM is a tool of IOM for server configuration management. Additionally operation tasks are predifined and can be customized.
AzureA cloud computing service created by Microsoft for building, testing, deploying, and managing applications and services through a global network of Microsoft-managed data centers.
CIContinous integration
Configuration RepositoryIn the scope of Ansible4IOM a configuration repository is a set of configurations that describes the used machines, values of variables hooks and more. It's a descripton of how to install a custom IOM.
EPELExtra Packages for Enterprise Linux is a repository of the Fedora-Project (
FSFile system
Gluster-FSA scale-out network-attached storage file system
HookHooks are part of Ansible4IOM. Hooks are a sophisticated way to customize processes. Additionally the behavior of processes can be simply customized by various variables.
IOMThe abbreviation for Intershop Order Management
IOM WatchdogA tool of IOM to monitor and manage the availablity of IOM application servers
JMSJava Message Service
OMSThe abbreviation for Order Management System, the technical name of the IOM

Red Hat Enterprise Linux

SQLStructured Query Language





Ansible4IOM is a ready to use set of roles, processes and modules based on Ansible. Additionally, it comes along with a customization concept to adapt predefined roles and concepts to your projects and infrastructure.

In order to use Ansible4IOM you should get an overview about Ansible, especially about:



As a first step Ansible has to be installed on your Ansible Control Machine according to the instructions given in the Ansible Installation Guide. After that, you can download Ansible4IOM from the Intershop Repository. After downloading the package, simply extract it on your Ansible Control Machine.

Before running any processes, the client machines (the machines where you want to install IOM), have to be prepared according the documentation at Ansible Install Guide.

General Concept

Ansible4IOM provides a set of roles, modules and processes. Content delivered with Ansible4IOM must not be modified. Instead, create configuration repositories for all your IOM installations, which are used to configure roles and processes to your needs. Processes provided by Ansible4IOM can be used to install and reconfigure simple PostgreSQL-servers suitable for IOM. You can install, update and reconfigure IOM installations and load-balancers. The Reference - Ansible4IOM Processes is part of this documentation.

This concept is also reflected on the command line. You have to tell Ansible where to find roles and modules (in variables ANSIBLE_LIBRARY and ANSIBLE_ROLES_PATH, there are different ways to this, see Ansible documentation ( You also have to pass the process to be executed on the command line (setup_oms_node in the example below) and you have to pass the path to the inventory file, which is central part of the configuration repository. The command line does not contain any information about client machines, where IOM should be installed. This information is taken from the configuration repository.

Example: execute setup_oms_node process
ANSIBLE_LIBRARY=Ansible4IOM/modules/ \
ansible-playbook -i PreProdIntegrationTest/inventory \

Assignment of Machines to Groups

The predefined processes (Reference - Ansible4IOM Processes) are delivered with Ansible4IOM are working on predefined groups. That means, the processes do not know anything about your machines. To give a machine a purpose, you have to assign it to a group within the inventory file.

The following groups are supported by Ansible4IOM:

  • pg_server - a machine assigned to this will be treated by processes as PostgreSQL server.
  • oms_cluster_node - will be treated as high-availibilty node of a distributed IOM installation. Can also be used to manage IOM on a single machine.
  • oms_azure_cluster_node - will be treated as high-availability node of distributed IOM installation in Azure cloud. Can also be used to manage IOM on a single Azure machine.
  • load_balancer - will be treated a load-balancer in front of IOM nodes.

A machine can be assigned to different groups. E.g., if you want to install PostgreSQL-server and a standalone Installation of IOM on a single machine, you have to assign the machine to both groups.

inventory file: assignment of a machine to different groups

Configuration of Processes


Hooks, described below, are a sophisticated way to customize processes. Additionally the behavior of processes can be simply customized by various variables, which you have to set in your configuration repository.

Processes do not provide any variables by themselves. Processes are built from roles (see Ansible4IOM/roles), and these roles provide configuration options via variables. In general Ansible4IOM is compliant with repositories described in Ansible Best Practices. You can use inventory-, group- and host-files to set variables for a whole installation, for a special server-group or a single host only.

There are two sources of information about variables available to configure IOM processes:

  • You can directly check the content of Ansible4IOM/roles/*/defaults/main.yml files.
  • The description of processes (Reference - Ansible4IOM Processes) also gives many hints about which variables exist and how to use them.

Organization of Variables

In many cases Ansible4IOM provides different roles, which share a common configuration. E.g., roles pgserver_install, used to setup PostgreSQL-server software, and pgserver_configuration, used to configure the database server, use common variables defined in Ansible4IOM/roles/pgserver_config/defaults.

In fact, all roles provided by Ansible4IOM follow this pattern. The directory roles/<role-type>_config/defaults provides the common configuration for all roles matching roles/<role_type>_*. Nevertheless single roles may also provide an own configuration in the defaults-directory, which is valid for this single role only.

Besides the roles/<role_type>_config/defaults pattern, there is no sharing of variables between roles. Whenever a variable of a role has to be set from a value defined in another role, this dependency will always be handled inside the process.

The following box shows an example. Role omsdb_initialization uses its local variables OMSDB_* for configuration, which are initialized by variables defined in oms_config.

process setup_omsdb.yml
    - role: oms_config
    - { role: omsdb_initialization,
        OMSDB_USER: "{{is_oms_db_user}}",
        OMSDB_PASSWD: "{{is_oms_db_pass}}",
        OMSDB_NAME: "{{is_oms_db_name}}"

On the other side, variables are not shared between groups. E.g., if you setup a PostgreSQL-server (group pg_server) and an IOM installation (group oms_cluster_node), information about PostgreSQL-host and -port are not automatically available for different processes acting on different groups (e.g., Process - Setup Postgres Server and Process - Setup OMS Node). This makes it possible to run processes separately. E.g., if you use a high-availability PostgreSQL-Server setup by your own or used as a service, you can simply configure Process - Setup OMS Node to use this database.

More information are available in the process descriptions, accessible on Reference - Ansible4IOM Processes.

Hooks in Configuration Repository

Hooks as part of the configuration repository are an idea introduced with Ansible4IOM. For this reason you will not find any information about it in the Ansible Documentation. It is explained in detail below.

Hooks are custom Ansible code snippets, which are part of your configuration repository, to be executed at specific points of processes. This way you can customize your IOM installations much more than it would be possible with variables only. Of course, the same result can be achieved by modifying roles and processes provided by Ansible4IOM. If you choose this way though, more than one disadvantage would be the result:

  • It would become impossible to update Ansible4IOM. You would not be able to benefit from improvements or bugfixes provided in newer versions.
  • You might require differently modified versions of Ansible4IOM for different installations. At the end, all the standard code of Ansible4IOM would become part of your configuration repository too.

An overview about available hooks (Reference - Ansible4IOM Hooks) is part of this documentation. Additionally a much more detailed description of hooks can be found in Reference - Ansible4IOM Processes, along with some examples how to use them.


The following example shows a hook, which changes the access-rights to a PostgreSQL-server. Normally only named users from named client machines knowing the required password are able to access the PostgreSQL-server. When you setup a CI-system or other type of non-productive IOM system, developers should be able to access the database of such systems easily. The default roles and processes setting up the PostgreSQL-server do not provide any variables that can be used to configure an open or a secured database-server. The only way to change the according configuration file is implementing a hook.

- name: extend remote hosts access to PostgreSQL for users of network 10.X.X.X
  lineinfile: dest={{PGSERVER_DATA}}/pg_hba.conf line='host all all trust' state=present
  become: true

The filename of the hook determines when the hook will be called. You have to use the name of the hook with extension .yml as filename. The Reference - Ansible4IOM Hooks provides information about relations between hooks and processes. The process description shows exactly when hooks are executed, see Reference - Ansible4IOM Processes.

Project- vs. Installation-specific Hooks

The most important purpose of hooks is customizing IOM for a special project. Such a project might contain custom code, custom files, and custom SQL-configurations, which have to be integrated in a special way into the IOM standard product. Every developer of this project needs an own IOM installation, running the project code. There are CI-systems, test-systems and of course production systems, which all need this special project configuration.

Therefore, there are many installations that require identical project setup. Nevertheless all installations will also have specific configurations. E.g., the hook from the example above, which opens the database for a whole network, must only be executed on CI systems.

To solve this problem, Ansible4IOM extends the directory layout of configuration repositories this way:

directory layout
project1/                 # base directory for all IOM installations of a certain project
  global_hooks/           # directory to hold hooks to be applied in all IOM installations of current projects
  global_files/           # directory to hold files accessible for global hooks
  installation1/          # configuration directory of installation1 of current project
     installation_hooks/  # directory to hold hooks to be applied in current installation only
     installation_files/  # directory to hold files accessible for installation specific hooks
     inventory            # inventory file
     group_vars/          # directory to hold group specific configurations
     host_vars            # directory to hold host specific configurations
     host_hooks/          # directory to hold host specific hooks
        hostname1/        # directory to hold hooks to be applied to hostname1 only
     host_files/          # directory to hold files accessible for host specific hooks only
        hostname1/        # directory to hold files accessible to host specific hooks of hostname1 only
  installation2/          # configuration directory of a second IOM installation of the same project
project2/                 # directory to hold configuration of another project

Configurations of different installations are grouped by projects. All installation directories within a project directory share the same hooks, which are located inside directory global_hooks, located at the same level as installation directories.

Additionally host-specific hooks are supported, which have to be stored to host_hooks/<hostname> inside the installation directory.

If the same hook is implemented on different levels (e.g., project and installation), the most specific hook is always executed last and the least specific hook is always executed first.

Files in Configuration Repository

Having a look at the directory structure above, you will find file directories in parallel to hook directories. These are extensions of Ansible4IOM too, intended to enable adding of custom files to configuration repositories too. You should never use this feature to store your project files in these directories. Your projects should be provided packed and versioned by some kind of binary repository.

The file directories should only contain files that are required to customize your infrastructure. A good example for such files are public keys, which you have to install by your hooks.


The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources