Deploying new IRIS instances can be a time-consuming task, especially when setting up multiple environments with mirrored configurations.
I’ve encountered this issue many times and want to share my experience and recommendations for using Ansible to streamline the IRIS installation process. My approach also includes handling additional tasks typically performed before and after installing IRIS.
This guide assumes you have a basic understanding of how Ansible works, so I won’t go into much detail on its fundamentals. However, if you have questions about anything mentioned here, feel free to ask in the comments below.
The examples provided in this guide were tested using Ansible 3.6 on a Red Hat 8 server, with IRIS 2023.1.1 and Red Hat 8 as the client environment. Other versions of Ansible, Red Hat (or other UNIX flavors), and IRIS may also work, but your mileage may vary.
Ansible install
The Ansible server must be a Linux distribution. We use Red Hat 8 in this article, but other Linux distros and versions should work as well.
To install the Ansible packages, you must first install EPEL:
[ansible@auto01 ansible]$ yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
Then install Ansible:
[ansible@auto01 ansible]$ yum install ansible
In addition to the packages, Ansible requires SSH access to remote servers. I recommend creating an SSH key pair, which is more secure than using traditional passwords. Also, the user used to connect to remote servers must have administrative privileges (i.e., be part of the wheel group).
Files and folders
To maintain an organized structure, I recommend the following files and folders under the ansible directory:
[ansible@auto01 ansible]$ ls -l
total 4
-rw-r--r--. 1 ansible ansible 247 Dec 5 00:57 ansible.cfg
drwxrwxr-x. 2 ansible ansible 6 Dec 5 00:56 files
drwxrwxr-x. 2 ansible ansible 6 Dec 5 00:56 inventory
drwxrwxr-x. 2 ansible ansible 6 Dec 5 00:56 library
drwxrwxr-x. 2 ansible ansible 6 Dec 5 00:56 playbooks
drwxrwxr-x. 2 ansible ansible 6 Dec 5 00:56 templates
drwxrwxr-x. 2 ansible ansible 6 Dec 5 00:56 vars
drwxrwxr-x. 2 ansible ansible 6 Dec 5 00:56 vault
After setting up this folder structure, copy the IRIS installer and IRIS license key into the files folder. It should look like this:
[ansible@auto01 ansible]$ ls -l files/
total 759976
-rw-rw-r--. 1 ansible ansible 778207913 Dec 5 14:32 IRISHealth-2023.1.1.380.0.22870-lnxrh8x64.tar.gz
-rw-rw-r--. 1 ansible ansible 1160 Sep 5 19:13 iris.key
The inventory
To run playbooks in Ansible, you must define your inventory of servers. There are several ways to do this, each with its own advantages. In this article, we’ll use a single file to define all servers.
The servers.yml file will contain the entire inventory, listing each server along with the variables required for the IRIS installation. Here’s an example:
[ansible@auto01 ansible]$ cat inventory/servers.yml
---
all:
hosts:
test01.mydomain:
iris_user: irisusr
iris_group: irisgrp
mgr_user: irisown
mgr_group: irismgr
platform: lnxrh8x64
iris_cmd: iris
iris_instances:
- name: TEST01
superserver_port: 51773
webserver_port: 52773
binary_file: IRISHealth-2023.1.1.380.0.22870-lnxrh8x64
key_file: iris.key
install_dir: /test/iris
jrnpri_dir: /test/jrnpri
jrnsec_dir: /test/jrnsec
config_globals: 16384
config_errlog: 10000
config_routines: "0,128,0,128,0,1024"
config_gmheap: 1048576
config_locksiz: 128057344
The vault
To keep passwords secure, create a vault file containing the passwords for the IRIS SuperUser and CSPSystem accounts.
Use the following command to edit the default vault file:
[ansible@auto01 ansible]$ ansible-vault edit vault/defaults.yml
---
iris_user_passwd: "Ch4ngeTh!s"
The playbook
To perform an IRIS installation, several tasks must be executed on the target server. These tasks are grouped and ordered in a file called a playbook.
A playbook is essentially a list of tasks that are executed sequentially on the remote hosts.
Below is the playbook I developed to install IRIS:
[ansible@auto01 ansible]$ cat playbooks/install_iris.yml
- hosts: all
become: yes
gather_facts: no
tasks:
- name: "Load default passwords"
include_vars: "../vault/defaults.yml"
- name: "Install required packets"
yum:
name: "{{ item }}"
state: latest
loop:
- "httpd"
- "java-1.8.0-openjdk"
- "mod_auth_mellon"
- "mod_ssl"
- name: "Create iris group"
group:
name: "{{ iris_group }}"
gid: 5005
- name: "Create iris mgr group"
group:
name: "{{ mgr_group }}"
gid: 5006
- name: "Create iris owner user"
user:
name: "{{ mgr_user }}"
uid: 5006
group: "{{ iris_group }}"
groups: "{{ mgr_group }}"
- name: "Create iris user"
user:
name: "{{ iris_user }}"
uid: 5005
group: "{{ iris_group }}"
- name: "Create mgr folder"
file:
path: "{{ item.install_dir }}/mgr"
state: directory
owner: "{{ iris_user }}"
group: "{{ iris_group }}"
mode: 0775
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Copy license key"
copy:
src: "../files/{{ item.key_file }}"
dest: "{{ item.install_dir }}/mgr/iris.key"
owner: "{{ iris_user }}"
group: "{{ iris_group }}"
backup: yes
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Create /install folder"
file:
path: "/install"
state: directory
mode: 0777
- name: "Create Instances install folders"
file:
path: "/install/{{ item.name }}"
state: directory
mode: 0777
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Copy IRIS installer"
copy:
src: "../files/{{ item.binary_file }}.tar.gz"
dest: "/install/{{ item.name }}/"
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Untar IRIS installer"
command:
cmd: "tar -xzf /install/{{ item.name }}/{{ item.binary_file }}.tar.gz"
chdir: "/install/{{ item.name }}/"
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Install Iris"
command:
cmd: "./irisinstall_silent"
chdir: "/install/{{ item.name }}/{{ item.binary_file }}"
environment:
ISC_PACKAGE_INSTANCENAME: "{{ item.name }}"
ISC_PACKAGE_INSTALLDIR: "{{ item.install_dir }}"
ISC_PACKAGE_PLATFORM: "{{ platform }}"
ISC_PACKAGE_UNICODE: "Y"
ISC_PACKAGE_INITIAL_SECURITY: "Normal"
ISC_PACKAGE_MGRUSER: "{{ mgr_user }}"
ISC_PACKAGE_MGRGROUP: "{{ mgr_group }}"
ISC_PACKAGE_USER_PASSWORD: "{{ iris_user_passwd }}"
ISC_PACKAGE_CSPSYSTEM_PASSWORD: "{{ iris_user_passwd }}"
ISC_PACKAGE_IRISUSER: "{{ iris_user }}"
ISC_PACKAGE_IRISGROUP: "{{ iris_group }}"
ISC_PACKAGE_SUPERSERVER_PORT: "{{ item.superserver_port }}"
ISC_PACKAGE_WEBSERVER_PORT: "{{ item.webserver_port }}"
ISC_PACKAGE_CLIENT_COMPONENTS: "standard_install"
ISC_PACKAGE_STARTIRIS: "N"
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Remove installers"
file:
path: "/install/{{ item.name }}"
state: absent
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Change iris.cpf"
lineinfile:
path: "{{ item[0].install_dir }}/iris.cpf"
regexp: "{{ item[1].from }}"
line: "{{ item[1].to }}"
backup: yes
with_nested:
- "{{ iris_instances }}"
- [ { from: "^TerminalPrompt=.*", to: "TerminalPrompt=8,3,2" },
{ from: "^FreezeOnError=0", to: "FreezeOnError=1" },
{ from: "^AutoParallel=.*", to: "AutoParallel=0" },
{ from: "^FastDistinct=.*", to: "FastDistinct=0" },
{ from: "^LockThreshold=.*", to: "LockThreshold=10000" },
{ from: "^EnsembleAutoStart=.*", to: "EnsembleAutoStart=1" },
{ from: "^MaxIRISTempSizeAtStart=.*", to: "MaxIRISTempSizeAtStart=300" } ]
loop_control:
label: "{{ item[0].name }}: {{ item[1].to }}"
- name: "Change Journal Current Dir"
lineinfile:
path: "{{ item.install_dir }}/iris.cpf"
regexp: "^CurrentDirectory=.*"
line: "CurrentDirectory={{ item.jrnpri_dir }}"
backup: yes
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Change Journal Alternate Dir"
lineinfile:
path: "{{ item.install_dir }}/iris.cpf"
regexp: "^AlternateDirectory=.*"
line: "AlternateDirectory={{ item.jrnsec_dir }}"
backup: yes
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Change Journal Prefix name"
lineinfile:
path: "{{ item.install_dir }}/iris.cpf"
regexp: "^JournalFilePrefix=.*"
line: "JournalFilePrefix={{ item.name }}_"
backup: yes
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Change Globals memory"
lineinfile:
path: "{{ item.install_dir }}/iris.cpf"
regexp: "^globals=.*"
line: "globals=0,0,{{ item.config_globals }},0,0,0"
backup: yes
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Change errlog memory"
lineinfile:
path: "{{ item.install_dir }}/iris.cpf"
regexp: "^errlog=.*"
line: "errlog={{ item.config_errlog }}"
backup: yes
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Change routines memory"
lineinfile:
path: "{{ item.install_dir }}/iris.cpf"
regexp: "^routines=.*"
line: "routines={{ item.config_routines }}"
backup: yes
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Change gmheap memory"
lineinfile:
path: "{{ item.install_dir }}/iris.cpf"
regexp: "^gmheap=.*"
line: "gmheap={{ item.config_gmheap }}"
backup: yes
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Change locksiz memory"
lineinfile:
path: "{{ item.install_dir }}/iris.cpf"
regexp: "^locksiz=.*"
line: "locksiz={{ item.config_locksiz }}"
backup: yes
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
- name: "Start Iris"
command: "iris start {{ item.name }}"
loop: "{{ iris_instances }}"
loop_control:
label: "{{ item.name }}"
...
As you can see, there are multiple tasks in this playbook—most of them self-explanatory by name. The comments indicate pre-install tasks, installation, and post-install customizations. After executing this playbook, you will have a new IRIS instance installed on the target system, customized with memory and other settings.
Run the installation!
After configuring the inventory, vault, and playbooks, you’re ready to execute the IRIS installation using Ansible.
To do so, run the following command:
[ansible@auto01 ansible]$ ansible-playbook -K --ask-vault-pass -i inventory/servers.yml playbooks/install_iris.yml
BECOME password:
Vault password:
PLAY [all] **************************************************************************************************************************************************
. . .
Once the playbook execution finishes, you’ll receive a summary of task statuses where you can verify that everything completed successfully.
And that’s it — you’ve just installed IRIS using Ansible! 😁
.png)
.png)
If KeepIntegrity is enabled, the purge task will only purge complete sessions. By definition, a complete session contains only messages with the status of Complete, Error, Aborted, or Discarded. Notice that if any message in the session is not of one of these four statuses (e.g., the message is Queued or Suspended), all messages in the session will not be purged..jpg)
.png)