Process

ANSIBLE_LIBRARY=<path to Ansible4IOM>/modules/ \
ANSIBLE_ROLES_PATH=<path to Ansible4IOM>/roles/ \
ansible-playbook -i <path to inventory file>/inventory \
<path to Ansible4IOM>/processes/setup_load_balancer.yml

Steps

The process consists of the following steps:

1. osuser_install
   1. Create group of Apache user.
   2. Create user to run Apache.
2. Apache_install
   1. Stop Apache service.
   2. Download Apache package.
   3. Prepare filesystem
   4. execute pre_apache_extract_hook
   5. install Apache package.
   6. Enable/start Apache service.
3. Apache_configure
   1. Create OMS specific configuration file.
   2. Update httpd.conf.
   3. Create a management user, able to access management URLs.
   4. Execute post_apache_configuration_hook.
   5. Restart Apache service.

Background Information

The load balancer, installed this way, is an Apache HTTP-server, configured to work as load balancer for IOM. It fulfills all preconditions listed in Guide - Intershop Order Management - Technical Overview:

• Sessions stickiness,
• Session fail-over for undertow subsystem of Wildfly application-server,
• Health check requests.

Configuration Values at roles/apache_config/defaults

The Configuration of the Apache httpd-server to be used as a load balancer is controlled by variables defined in roles/apache_config/defaults. Please have a look at this file to get first hand information about configuration settings.

To setup a working Apache httpd-server, the following variables have to be overwritten:

• APACHE_VERSION - Please use the newest Apache version available at repository.
• APACHE_REPO_URL - URL of Maven repository to download Apache package from
• APACHE_REPO_USER - Name of repository user
• APACHE_REPO_PASSWD - Password of repository user
• APACHE_SERVER_ADMIN - Email address to be rendered into error pages
• APACHE_LB_OMSSERVER_LIST - List of IOM application severs to be served by load-balancer

APACHE_LB_OMSSERVER_LIST is the most important variable in the list above. Every IOM application server to be served by the load balancer has to be listed there. Every entry of the list consists of a hash, holding all required information of one application server.

• host - Hostname or IP of the frontend application server.
• port - Port of the frontend application server. According to Guide - Intershop Order Management - Technical Overview, frontend application servers use a port-offset of 100. If no further changes applied, the default value of 8180 can be used.
• server_id - For session-stickiness and session-failover to work, it is essential that server_id is identical to expanded value of $SERVER_ID from installation.properties of according frontend application-server, see Guide - Intershop Order Management - Technical Overview.
• healthcheck_url - The url to make healthchecks on frontend application-server. The default value can be used.

Extended Configuration of Apache Httpd-Server

The variables defined in roles/apache_config/defaults cover basic configuration settings only. To make further configuration changes, implement the post_apache_configuration_hook (see section Examples below).

Examples

Minimum Configuration of Load Balancer in Front of Two IOM Azure Nodes

Precondition for setting up an Apache httpd-server as a load balancer for two IOM Azure nodes is the installation of these two nodes, see Process - Setup OMS node. According to the section Background Information above, the group_vars/load_balancer file has to have the content shown in box below. APACHE_LB_OMSSERVER_LIST is a list of hashes, which cannot be defined in the inventory file directly. File group_vars/load_balancer is able to define complex variables. To hold all load balancer specific settings at a single place, it is a good idea to define any other load balancer specific settings within the same file.

# information required to access repo to download apache package
APACHE_VERSION: 2.4.27.0
APACHE_REPO_URL: https://repository.intershop.de/releases/
APACHE_REPO_USER: MyRepoAccount
APACHE_REPO_PASSWD: MySecretPassword
 
APACHE_SERVER_ADMIN: "admin@yoursite.com"
 
APACHE_LB_OMSSERVER_LIST: [
 {
   host: "node1",
   port: "8180",
   server_id: "node1_frontend",
   healthcheck_url: "/monitoring/services/health/status"
 },
 {
   host: "node2",
   port: "8180",
   server_id: "node2_frontend",
   healthcheck_url: "/monitoring/services/health/status"
 }
]

Keep in mind that the machine where the load balancer should be installed, has to be able to resolve hostnames of node1 and node2 correctly. Assuming the default value of SERVER_ID at installation.properties, which is $(hostname)_$OMS_SERVER_TYPE, the values for server_is were set to node1_frontend and node2_frontend. This assumption is valid only, if the shell command hostname expands on host node1 to node1 and on host node2 to node2.

Now the process setup_load_balancer can be executed.

ANSIBLE_LIBRARY=<path to Ansible4IOM>/modules/ \
ANSIBLE_ROLES_PATH=<path to Ansible4IOM>/roles/ \
ansible-playbook -i <path to inventory file> \
<path to Ansible4IOM>/processes/setup_load_balancer.yml

Changing Listening Port of Apache Httpd-Server to 81

The listening port of the Apache httpd-server is not reflected by a configuration variable defined in roles/apache_config/defaults. To change the listing port, adapt httpd.conf directly. To make this change of the configuration a part of the configuration repository and to automate this configuration change, implement post_apache_configuration_hook. This hook is a snippet of Ansible code, stored in the configuration repository, which is executed during installation (see section Steps above).

Create a file post_apache_configuration_hook.yml in your configuration repository within the directory global_hooks or installation_hooks, depending on the scope of the configuration change. Also see Concept - Ansible4IOM Server Configuration Management 1.0 - 1.1.

- name: update httpd.conf
  lineinfile:
    dest: "{{APACHE_INSTALL_DIR}}/conf/httpd.conf"
    regexp: "{{item.regexp}}"
    line: "{{item.line}}"
    state: present
  with_items:
    - { regexp: "^[ \t]*Listen[ \t]", line: "Listen 81" }
  become: true

Now process setup_load_balancer can be executed.

ANSIBLE_LIBRARY=<path to Ansible4IOM>/modules/ \
ANSIBLE_ROLES_PATH=<path to Ansible4IOM>/roles/ \
ansible-playbook -i <path to inventory file> \
<path to Ansible4IOM>/processes/setup_load_balancer.yml

Enable HTTPS Protocol

This example has not the intention to explain the do's and don'ts and basics of Apaches SSL configuration. If you want to get information about this topic, you should consult external resources, e.g., the Howto about SSL/TLS Strong encryption.

The example has only the intention to show you, how to use Ansible4IOM to enable HTTPS protocol. The configuration example is very simple and based on Apaches default configuration. Only the following minimal changes will be made to default configuration:

• Enable default ssl-configuration,
• Load required modules,
• Install certificate and key file.

To make these changes a part of the configuration repository, you have to implement post_apache_configuration_hook. This hook is a snippet of Ansible code, stored in the configuration repository, which is executed during installation (see section Steps above). Additionally you have to provide the files server.key and server.crt within your config-repository. The right place for these files is installation_files, since certificate files are mostly specific for each installation (host name). Within ansible code, this directory can be accessed by variable hook_file_dir.

- name: update httpd.conf
  lineinfile:
    dest: "{{APACHE_INSTALL_DIR}}/conf/httpd.conf"
    regexp: "{{item.regexp}}"
    line: "{{item.line}}"
    state: present
  with_items:
    - { regexp: "Include conf/extra/httpd-ssl.conf", line: "Include conf/extra/httpd-ssl.conf" }
    - { regexp: "LoadModule ssl_module modules/mod_ssl.so", line: "LoadModule ssl_module modules/mod_ssl.so" }
    - { regexp: "LoadModule socache_shmcb_module modules/mod_socache_shmcb.so", line: "LoadModule socache_shmcb_module modules/mod_socache_shmcb.so" }
  become: true

- name: copy key files
  copy:
    src: "{{item.src}}"
    dest: "{{item.dest}}"
  with_items:
    - { src: "{{hook_file_dir}}/server.key", dest: "{{APACHE_INSTALL_DIR}}/conf/" }
    - { src: "{{hook_file_dir}}/server.crt", dest: "{{APACHE_INSTALL_DIR}}/conf/" }
  become: true

Now process setup_load_balancer can be executed.

ANSIBLE_LIBRARY=<path to Ansible4IOM>/modules/ \
ANSIBLE_ROLES_PATH=<path to Ansible4IOM>/roles/ \
ansible-playbook -i <path to inventory file> \
<path to Ansible4IOM>/processes/setup_load_balancer.yml