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.
Term | Description |
---|---|
Ansible4IOM | Ansible4IOM is a tool of IOM for server configuration management. Additionally operation tasks are predifined and can be customized. |
Azure | A cloud computing service created by Microsoft for building, testing, deploying, and managing applications and services through a global network of Microsoft-managed data centers. |
CI | Continous integration |
Configuration Repository | In 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. |
DB | Database |
EPEL | Extra Packages for Enterprise Linux is a repository of the Fedora-Project (https://fedoraproject.org/wiki/EPEL). |
FS | File system |
Gluster-FS | A scale-out network-attached storage file system |
Hook | Hooks are part of Ansible4IOM. Hooks are a sophisticated way to customize processes. Additionally the behavior of processes can be simply customized by various variables. |
IOM | The abbreviation for Intershop Order Management |
IOM Watchdog | A tool of IOM to monitor and manage the availablity of IOM application servers |
JMS | Java Message Service |
OMS | The abbreviation for Order Management System, the technical name of the IOM |
PG | PostgreSQL |
RHEL | Red Hat Enterprise Linux |
SQL | Structured Query Language |
and
and
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.
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.
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.
Install the EPEL repository.
# as root on Ansible Control Machine do sudo yum -y install epel-release sudo yum repolist
Install Ansible and any required packages.
# as root on Ansible Control Machine do sudo yum -y install ansible
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.
Create an 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
Ensure that the file /etc/sudoers contains the 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
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
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.
Create a 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.
Transfer the public key to the account of the user ansible on the 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.
Test passwordless remote access to user ansible on the 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.
The only thing that is still missing before starting IOM installation is the configuration repository, which holds all information about the IOM setup.
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.
Create the following directory structure in the regular users home directory on the Ansible Control Machine.
~/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
The inventory file is the central source of information of any installation managed by Ansible.
Create the file at following location: ~/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.
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}}"
Once the configuration repository is prepared, the installation process can be started. It consists of the following three steps:
A load balancer is not needed, when using IOM standalone installation.
Setup Postgres Server.
ANSIBLE_LIBRARY=~/Ansible4IOM/modules/ \ ANSIBLE_ROLES_PATH=~/Ansible4IOM/roles/ \ ansible-playbook -i ~/config-repo/plain-oms/localdemo/inventory \ ~/Ansible4IOM/processes/setup_pgserver.yml
Setup OMS database.
ANSIBLE_LIBRARY=~/Ansible4IOM/modules/ \ ANSIBLE_ROLES_PATH=~/Ansible4IOM/roles/ \ ansible-playbook -i ~/config-repo/plain-oms/localdemo/inventory \ ~/Ansible4IOM/processes/setup_omsdb.yml
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
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:
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.