Concept - Ansible4IOM Server Configuration Management 1.0 - 1.1

1 Introduction

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.

1.1 Glossary

Term
Description
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.
DBDatabase
EPELExtra Packages for Enterprise Linux is a repository of the Fedora-Project (https://fedoraproject.org/wiki/EPEL).
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
PGPostgreSQL
RHEL

Red Hat Enterprise Linux

SQLStructured Query Language

1.2 References

and

and

2 Ansible

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 (https://www.ansible.com), especially about:

3 Ansible4IOM

3.1 Installation

As a first step Ansible has to be installed on your Ansible Control Machine according to the instructions given in Ansible Installation (http://docs.ansible.com/ansible/intro_installation.html). 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 Docu.

3.2 General Concept

Ansible4IOM provides a set of roles, modules and processes. Content delivered with Ansible4IOM must not be modified. Instead of it, 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 1.0 is part of this documentation.

general concept Ansible4IOM

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 (http://docs.ansible.com/ansible). You also have to pass the process to be executed on the command line (setup_oms_node in example below) and you have to pass the path to 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_ROLES_PATH=Ansible4IOM/roles/ \
ansible-playbook -i PreProdIntegrationTest/inventory \
Ansible4IOM/processes/setup_oms_node.yml

3.3 Assignment of Machines to Groups

The predefined processes (Reference - Ansible4IOM Processes 1.0) 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 it to assign to a group within 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_single_node - will be treated as standalone installation of IOM application server
  • oms_ha_node - will be treated as high-availibilty node of a distributed IOM installation
  • oms_azure_node - will be treated as high-availability node of distributed IOM installation in Azure cloud
  • load_balancer - will be treated a load-balancer in front of high-availability IOM nodes

A machine can be assigned to different groups. E.g., if you want to install PostgreSQL-server and 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
...
[pg_server]
my.oms-single-server.private.net
[oms_single_node]
my.oms-single-server.private.net

3.4 Configuration of Processes

3.4.1 Variables

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 are providing 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 1.0) gives also many hints about which variables exist and how to use them.

3.4.1.1 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, are using 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 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 standalone installation (group oms_single_node), information about PostgreSQL-host and -port are not automatically available for different processes acting on different groups (e.g., Process - Setup Postgres Server 1.0 and Process - Setup OMS Node 1.0). This makes it possible to run processes separately. E.g., if you are using a high-availability PostgreSQL-Server setup by your own or used as a service, you can simply configure Process - Setup OMS Node 1.0 to use this database.

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

3.4.2 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 will be explained here in detail.

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 1.0) is part of this documentation. Additionally a much more detailed description of hooks can be found in Reference - Ansible4IOM Processes 1.0, along with some examples how to use them.

3.4.2.1 Example

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.

post_pgserver_configuration_hook.yml
- 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 10.0.0.0/8 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 1.0 provides information about relations between hooks and processes, and process description shows exactly when hooks are executed. See Reference - Ansible4IOM Processes 1.0.

3.4.2.2 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.

Hence, we have the situation, that we have many installations, which need to have identical project setup. Nevertheless all installations will also have specific configurations. E.g., the hook from the example above, which is opening 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
     hook1
     hook3
  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
        hook1
        hook2
     installation_files/  # directory to hold files accessible for installation specific hooks
     inventory            # inventory file
     group_vars/          # directory to hold group specific configurations
        group1
        group2
     host_vars            # directory to hold host specific configurations
        hostname1
        hostname2
     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
     installation_hooks/
        hook3
     installation_files/
     inventory
     group_vars/
        group1
        group2
     host_vars
        hostname3
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 hooks is always executed last and the least specific hook is always executed first.

3.4.3 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.

Disclaimer

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
Support Tickets