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 guide gives a short tutorial of how to use Ansible4IOM and how to become familiar with it. The target group of this document are developers of a project as well as system administrators.

1.1 Glossary

1.2 References

• Concept - Ansible4IOM
• Reference - Ansible4IOM Processes
• Reference - Ansible4IOM Variables
• Reference - Ansible4IOM Hooks

and

• Intershop Repository
• Process - Setup Postgres Server
• Process - Setup or Reconfigure Database Account
• Process - Setup OMS Node

and

• Ansible Documentation
• Ubuntu Documentation - SSH/OpenSSH/Keys

1.3 Foreword

The following example is not intended to work as a best practice document. This tutorial has the intention to enable users to go their first steps with Ansible4IOM done as easy as possible. Before turning this into production, you should read all the available documentation provided for Ansible, see Ansible Documentation, and you should be familiar with Linux-administration.

To make the example as easy as possible, client machine and Ansible Control Machine are identical. Nevertheless a kind of configuration was chosen that makes it easy to split the example to different machines.

1.4 Requirements

You will need a Linux machine running CentOS 7.3 or RedHat 7.3. with root access to this machine.
Furthermore, a regular user account is required. For the following examples use this regular user account only, unless otherwise noted.

2 Setup of Ansible Control Machine

2.1 Install Ansible

Ansible has to be installed on the Ansible Control Machine only, not on clients, where IOM, PostgreSQL, etc. will be installed.

Ansible is part of Extra Packages for Enterprise Linux (EPEL), which is a community repository of non-standard packages for the RHEL distribution.

1. Install the EPEL repository.

   Install the EPEL repository

   # as root on Ansible Control Machine do
   sudo yum -y install epel-release
   sudo yum repolist

2. Install Ansible and any required packages.

   Ansible Installation

   # as root on Ansible Control Machine do
   sudo yum -y install ansible

2.2 Install Ansible4IOM

1. Download the latest version of Ansible4IOM from the Intershop Repository.
2. Extract the package into the home directory of the regular user on the Ansible Control Machine.

3 Prepare Client Machine for IOM Installation

3.1 Create an Ansible User

You have to create a user ansible on all client machines. Since the example combines Ansible Control Machine and client, the user has to be created locally at your machine.

This user has to be able to execute every command passwordless via sudo. To do so, add the user to group wheel and make sure wheel is able to execute sudo without entering password.

1. Create an Ansible user.

   create ansible user

   # as root on client machine do
   # create user ansible, add the new user to group wheel
   useradd -m -G wheel -U ansible
   # set password for user ansible
   passwd ansible

2. Ensure that the file /etc/sudoers contains the following lines.

   make sure, file /etc/sudoers contains following lines

   ## Allows people in group wheel to run all commands
   # %wheel        ALL=(ALL)       ALL
    
   ## Same thing without a password
   %wheel  ALL=(ALL)       NOPASSWD: ALL

3. Allow passwordless sudo for group wheel.

   allow passwordless sudo for group wheel

   # as root on client machine do
   # edit /etc/sudoers using visudo only, otherwise it might be possible to lockout yourself.
   visudo

3.2 Allow Passwordless Remote Access for Ansible User

To allow passwordless access from Ansible Control Machine to client machine, you have to add the public key of your regular user account on the Ansible Control Machine to ~/.ssh/authorized_keys file of the Ansible user on client machine.

If you do not have a ssh-key-pair for your regular user account on the Ansible Control Machine yet, you have to create one.

1. Create a key-pair.

   create key-pair

   # as regular user on Ansible Control Machine do
   ssh-keygen -t rsa

   You will be prompted for a location to save the keys, and a passphrase for the keys. Accept default location and create keys without passphrase.

2. Transfer the public key to the account of the user ansible on the client machine.

   transfer public key to Ansible user on client machine

   # as regular user on Ansible Control Machine do
   ssh-copy-id ansible@localhost

   When copying the public key, you will be asked for the password of the Ansible user. Enter the password you have chosen, when creating the user ansible.

3. Test passwordless remote access to user ansible on the client machine.

   test passwordless access to user ansible on client machine

   # as regular user on Ansible Control Machine do
   ssh ansible@localhost

For further information on ssh key generation and installation have a look at SSH/OpenSSH/Keys in the Ubuntu Documentation.

4 Setup configuration repository

The only thing that is still missing before starting IOM installation is the configuration repository, which holds all information about the IOM setup.

4.1 Setup Directory Structure

In real live environments, the configuration repository should be managed in some kind of source code control system. For purpose of demonstration, it is fully sufficient to create the configuration repository locally on the Ansible Control Machine.

1. Create the following directory structure in the regular users home directory on the Ansible Control Machine.

   directory layout

   ~/config-repo/                 # base directory of configuration repositories
       plain-oms/                 # base directory for all plain IOM installations
          localdemo/              # configuration directory of demo-installation
             installation_hooks/  # directory to hold hooks to be applied in current installation only
             group_vars/          # directory to hold group specific configurations

4.2 Setup Inventory File

The inventory file is the central source of information of any installation managed by Ansible.

1. Create the file at following location: ~/config-repos/plain-oms/localdemo/inventory
   

   ~/config-repos/plain-oms/localdemo/inventory

   ################################################################################
   # hosts
   ################################################################################
   localhost ansible_host=localhost ansible_port=22 ansible_user=ansible
   
   ################################################################################
   # global variables
   ################################################################################
   [all:vars]
   PG_VERSION='9.6'
   OMS_VERSION=2.11.0.0
   OMS_REPO_URL=https://repository.intershop.de/oms-releases
   OMS_REPO_USER=<your account name>
   OMS_REPO_PASSWD=<your password>
   
   # control setup of PostgreSQL-server
   PGSERVER_SUPERUSER="postgres"
   PGSERVER_SUPERUSER_PASSWD="s3cr3t"
    
   # control setup of IOM DB-account
   OMSDB_HOST="localhost"
   OMSDB_SUPERUSER="{{PGSERVER_SUPERUSER}}"
   OMSDB_SUPERUSER_PASSWD="{{PGSERVER_SUPERUSER_PASSWD}}"
    
   # control setup of IOM
   is_oms_db_hostlist="localhost:5432"
   is_oms_db_name="dbname"
   is_oms_db_user="oms_user"
   is_oms_db_pass="dbpasswd"
   
   ################################################################################
   # groups
   ################################################################################
   [pg_server]
   localhost
   
   [oms_cluster_node]
   localhost

The example inventory does not contain any email configuration (smtp-server, email-addresses), hence, the email functionality of IOM will not work. For the purpose of this document, the missing email functionality of IOM, is acceptable. For any other system (developer, pre-production, production, etc.) it is not.

The inventory file can only hold simple variables. Complex variables, hashes, arrays or combinations of both, can only be defined in group_vars and host_vars. Since the list of trusted hosts for PostgreSQL-server is an array, it has to be defined in ~/config-repo/plain-oms/localdemo/group_vars/pg_server.

PGSERVER_TRUSTED_HOSTS: [ "::1", "127.0.0.1" ]

For more information, see description of Process - Setup Postgres Server, Process - Setup or Reconfigure Database Account and Process - Setup OMS Node.

4.3 Setup Hook

To get a better understanding of the hook concept, the example contains a simple hook-implementation too. It extends log-messages provided by PostgreSQL-server, see process Process - Setup Postgres Server.

Fill the file ~/config-repos/plain-oms/localdemo/installation_hooks/post_pgserver_configuration_hook.yml with following Ansible code:

- name: update postgreSQL configuration for extended logging
  ini_file:
    dest: "{{PGSERVER_DATA}}/postgresql.conf"
    section: ""
    option: "{{item.option}}"
    value: "{{item.value}}"
  with_items:
    - { option: log_destination, value: "'stderr,csvlog'" }
    - { option: log_filename, value: "'pg-{{inventory_hostname}}_{{PGSERVER_PORT}}-%Y%m%d%_%H%M.log'" }
    - { option: log_rotation_age, value: 30 }
    - { option: log_truncate_on_rotation, value: "off" }
    - { option: log_min_duration_statement, value: 250 }
  become: true
  become_user: "{{PGServerOSUser}}"

5 Install IOM

Once the configuration repository is prepared, the installation process can be started. It consists of the following three steps:

• Process - Setup Postgres Server,
• Initialization of database account (Process - Setup or Reconfigure Database Account) and
• Installation of IOM standalone server (Process - Setup OMS Node).

A load balancer is not needed, when using IOM standalone installation.

1. Setup Postgres Server.

   setup_pgserver

   ANSIBLE_LIBRARY=~/Ansible4IOM/modules/ \
   ANSIBLE_ROLES_PATH=~/Ansible4IOM/roles/ \
   ansible-playbook -i ~/config-repo/plain-oms/localdemo/inventory \
   ~/Ansible4IOM/processes/setup_pgserver.yml

2. Setup OMS database.

   setup_omsdb

   ANSIBLE_LIBRARY=~/Ansible4IOM/modules/ \
   ANSIBLE_ROLES_PATH=~/Ansible4IOM/roles/ \
   ansible-playbook -i ~/config-repo/plain-oms/localdemo/inventory \
   ~/Ansible4IOM/processes/setup_omsdb.yml 

3. Setup OMS node.

   setup_oms_node

   ANSIBLE_LIBRARY=~/Ansible4IOM/modules/ \
   ANSIBLE_ROLES_PATH=~/Ansible4IOM/roles/ \
   ansible-playbook -i ~/config-repo/plain-oms/localdemo/inventory \
   ~/Ansible4IOM/processes/setup_oms_node.yml

6 Access IOM Installation

Now the IOM installation is ready to be used. You can access the Web-GUI at http://localhost:8080/omt/app/start. Use the following credentials to log in:

• Account: admin
• Password: !InterShop00!