InterSystems IRIS Deployment Guide for AWS using CloudFormation template

Primary tabs


InterSystems IRIS Deployment Guide for AWS using CloudFormation template 


Please note: following this guide, especially the prerequisites section requires Intermediate to Advanced level of knowledge of AWS. You'll need to create and manage S3 buckets, IAM roles for EC2 instances, VPCs and Subnets. You'll also need access to InterSystems binaries (usually downloaded via WRC site) as well as IRIS license key.

Table of Contents

InterSystems IRIS Deployment Guide – AWS Partner Network. 1

Introduction. 3

Prerequisites and Requirements. 3

Time. 3

Product License and Binaries. 3

AWS Account 3

IAM Entity for user 3

IAM Role for EC2. 4

S3 Bucket 4

VPC and Subnets. 4

EC2 Key Pair 4

Knowledge Requirements. 5

Architecture. 6

Multi-AZ Fault Tolerant Architecture Diagram (Preferred) 6

Single Instance, Single AZ Architecture Diagram (Development and Testing) 7

Deployment 8

Security. 9

Encrypting IRIS Data at Rest 9

Encrypting IRIS data in transit 9

Secure access to IRIS Management Portal 9

Logging/Auditing. 10

Sizing/Cost 11

Deployment Assets. 12

Deployment Options. 12

Deployment Assets (Recommended for Production) 12

CloudFormation Template Input Parameters. 12

Clean Up. 13

Testing the Deployment 14

Health Check. 14

Failover Test 14

Backup and Recovery. 15

Backup. 15

Instance Failure. 15

Availability-Zone Failure. 15

Region Failure. 15

RPO/RTO.. 15

Storage Capacity. 16

Security certificate expiration. 16

Routine Maintenance. 17

Emergency Maintenance. 18

Support 18

Troubleshooting. 18

Contact InterSystems Support 19

Appendix. 20

IAM Policy for EC2 instance. 20






This guide is based CloudFormation Template for users to set up their own InterSystems IRIS Data Platform according to InterSystems and AWS best practices.

This guide will detail the steps to deploy the CloudFormation template. 

In this guide, we cover two types of deployments for the InterSystems IRIS CloudFormation template. The first method is highly available, multi-availability zone (AZ), targeted to production workloads, and the second method is a single availability zone deployment for development and testing workloads.


Prerequisites and Requirements

In this section, we detail the prerequisites and requirements to run and operate our solution.


The deployment itself takes about 4 minutes, but with prerequisites and testing it could take up to 2 hours.

Product License and Binaries

InterSystems IRIS binaries are available to all InterSystems customers via Login with your WRC credentials, follow links to Actions -> SW Distributions -> InterSystems IRIS. This Deployment Guide is written for InterSystems IRIS 2020.1 build 197 (preview release of IRIS 2020.1). Red Hat platform. IRIS Binaries files look like ISCAgent-2020. and IRIS-2020.


InterSystems IRIS license key – you should be able to use your existing InterSystems IRIS license key (iris.key). You can also request evaluation key via InterSystems IRIS Evaluation Service

AWS Account

You must have an AWS account set up. If you don't visit:


IAM Entity for user

Create an IAM user or role. Your IAM user should have a policy that allows AWS CloudFormation actions. Do not use your root account to deploy the CloudFormation template. In addition to AWS CloudFormation actions, IAM users who create or delete stacks will also require additional permissions that depend on the stack template. This deployment requires permissions to all services listed in the following section.



IAM Role for EC2

The CloudFormation template requires an IAM role that allows your EC2 instance to access S3 bucket and put logs into CloudWatch. See Appendix “IAM Policy for EC2 instance” for an example of the policy, associated with such role.



S3 Bucket

Create S3 bucket “my-bucket” (your name should be unique), copy IRIS binaries files and iris.key



aws s3 mb s3://$BUCKET

aws s3 cp ISCAgent-2020. s3://$BUCKET

aws s3 cp IRIS-2020. s3://$BUCKET

aws s3 cp iris.key s3://$BUCKET


VPC and Subnets

Template is designed to deploy IRIS into existing VPC and Subnets. In the regions where three or more Availability Zones are available we recommend creating three subnets across three different availability zones. You can follow the AWS example below to create VPC and Subnets with the CloudFormation template:


EC2 Key Pair

To access EC2 instances provisioned by this template you’ll need at least one EC2 Key Pair. Refer to for details.

Knowledge Requirements

Knowledge of the following AWS services:


Account limit increases will not be required for this deployment.


More information on proper policy and permissions here:


Note: Individuals possessing the AWS Associate certifications should have a sufficient depth of knowledge




In this section, we give architecture diagrams of two deployment possibilities and talk about architecture design choices.

Multi-AZ Fault Tolerant Architecture Diagram (Preferred)

In the multi-AZ fault tolerant deployment option, the mirrored InterSystems IRIS instances are situated behind a load balancer in two availability zones to ensure high availability and fault tolerance. In the regions with three or more availability zones, Arbiter node is located in the third AZ.


  1. Network Load Balancer directs database traffic to the currently Primary IRIS node.
  2. An Internet Gateway allows communication between instances in your VPC and the Internet.
  3. IRIS Stores all the customer data in the encrypted EBS volumes.
    1. EBS is encrypted and uses AWS Key Management Service (KMS) managed key. 
    2. For regulated workloads where encryption of data in transit is required  you can choose to use r5n family of instances, since they do provide automatic instance to instance traffic encryption. IRIS-level traffic encryption is also possible, but not enabled by CloudFormation (see Encrypting Data in Transit section of this guide).
  4. Security groups restrict access to the greatest degree possible, by only allowing necessary traffic.



Single Instance, Single AZ Architecture Diagram (Development and Testing)


InterSystems IRIS can also be deployed in a single availability zone for development and evaluation purposes. The data flow and architecture components are the same as the ones highlighted above. This solution does not provide high availability or fault tolerance and is not suitable for production use.







  1. Log into AWS account with the IAM entity created in the prerequisites section with the required permissions to deploy the solution.
  2. Make sure all the Prerequisites, such as VPC, S3 bucket, IRIS binaries and license are in place.
  3. Click the following link to deploy CloudFormation template (deploys in us-east-1): for multi - AZ fault-tolerant deployment.
  4. In ‘Step 1 - Create Stack’, press the ‘Next’ button.
  5. In ‘Step 2 - Specify stack details’, fill out and adjust CloudFormation parameters depending on requirements.
  6. Press the ‘Next’ button.
  7. In ‘Step 3 - Configure stack options’, enter and adjust optional tags, permissions, and advanced options.
  8. Press the ‘Next’ button.
  9. Review your CloudFormation configurations.
  10. Press the ‘Create Stack’ button.
  11. Wait approximately 4 minutes for your CloudFormation template to deploy.
  12. You can verify your deployment has succeeded by looking for a ‘CREATE_COMPLETE’ status.
  13. If the status is ‘CREATE_FAILED’, see the troubleshooting section in this guide. If it succeeds, please use health checks.





In this section, we discuss the InterSystems IRIS default configuration deployed by this guide, general best practices, and options for securing your solution on AWS.

Encrypting IRIS Data at Rest

On a database instances running InterSystems IRIS, data is stored at rest in the underlying EBS volumes which are encrypted. This CloudFormation template creates EBS volumes, encrypted with the account-default AWS managed Key, named aws/ebs.


Encrypting IRIS data in transit


This CloudFormation does not secure Client – Server and Instance to Instance connection. Should data in transit encryption be required follow the steps outlined below after the deployment is completed.


Enabling SSL for SuperServer connections (JDBC/ODBC connections):


For Durable Multi-AZ Configuration traffic between IRIS EC2 instances might need to be encrypted too. It can be achieved either by enabling SSL Encryption for mirroring or switching to r5n family of instances which provides the automatic encryption of instance-to-instance traffic.


You can use AWS Certificate Manager (ACM) to easily provision, manage, and deploy Secure Sockets Layer/Transport Layer Security (SSL/TLS) certificates.

Secure access to IRIS Management Portal


By default, IRIS Management portal exposed as unsecured HTTP web server. Consider one of the following options to enable secure connection to Management Portal:


  • Placing IRIS within Private Subnet and using Bastion Host to access it.



InterSystems IRIS stores logging information in messages.log file. CloudFormation does not setup any additional logging/monitoring services. We recommend that you enable Structured Logging:


The CloudFormation template does not enable AWS CloudTrail logs. You can enable CloudTrail logging by navigating to the CloudTrail service console, and enabling CloudTrail logs. With CloudTrail, activity related to actions across your AWS infrastructure are recorded as an event in CloudTrail. This helps you enable governance, compliance, and operational and risk auditing of your AWS account. 






This guide will create the AWS resources outlined in Deployment Assets section of this document. You are responsible for the cost of AWS services used while running this deployment. The minimum viable configuration for a InterSystems IRIS deployment provides high availability and security.


The template in this guide is using BYOL (Bring Your Own License) InterSystems IRIS licensing model.


You can access Pay Per Hour IRIS Pricing at AWS at InterSystems IRIS Marketplace page:


Please contact InterSystems for details on BYOL pricing.


The following AWS assets are required to provide a functional platform:

  • 3 EC2 Instances (including EBS volumes and provisioned IOPS)
  • 1 Elastic Load Balancer

The following table outlines recommendations for EC2 and EBS capacity, built into Deployment CloudFormation template, as well as AWS resource costs.


AWS cost estimate is based on On-Demand pricing, North Virginia Region. Cost of snapshots and data transfer not included. Please consult AWS Pricing for the latest information. Unit - $/Month.





Prod Small

Prod Medium

Prod Large



2 * r5.large

2 * r5.4xlarge

2 * r5.8xlarge

EC2 Arbiter*






gp2 20GB

gp2 50GB

io1 512GB 1,000iops

io1 600GB 2,000iops


gp2 128GB

gp2 128GB

io1 1TB 10,000iops

io1 4TB 10,000iops


gp2 64GB

gp2 64GB

io1 256GB 1,000iops

io1 512GB 2,000iops

Cost Compute





Cost EBS vol










Support (Basic)





Cost Total





Calculator link





*All EC2 instances include additional 20GB gp2 root EBS volume



Deployment Assets

Deployment Options

The InterSystems IRIS CloudFormation template provides two different deployment options. The multi-AZ deployment option provides a highly available redundant architecture that is suitable for production workloads. The single-AZ deployment option provides a lower cost alternative that is suitable for development or test workloads.

Deployment Assets (Recommended for Production)

The InterSystems IRIS deployment is executed via a CloudFormation template that receives input parameters and passes them to the appropriate nested template which are executed in order based on conditions and dependencies.


AWS Resources Created:

  • VPC Security Groups
  • EC2 Instances for IRIS nodes and Arbiter
  • Amazon Elastic Load Balancing (Amazon ELB) Network Load Balancer (NLB)


CloudFormation Template Input Parameters

General AWS

  • EC2 Key Pair Name that would be used to connect to the instance via ssh. (See prerequisites)
  • EC2 Instance Role. Role should have access to the S3 bucket with the IRIS distribution. (See prerequisites and appendix)


  • Name of S3 bucket where IRIS distribution and license key are located (created as prerequisite)


  • Select the VPC and three Subnets, that belong to that VPC where resources will be launched


  • Database Master Password. Must be at least 4 alphanumeric characters long.
  • EC2 instance type for Database nodes


Stack Creation

There are three outputs for the master template. JDBC endpoint that can be used to connect JDBC clients to IRIS and Management Portal URLs for both IRIS nodes.


Clean Up

  • Follow the AWS CloudFormation Delete documentation to delete the resources deployed by this document
  • Delete any other resources that you manually created to integrate or assist with the deployment, such as S3 bucket and VPC.




Testing the Deployment

Health Check


Follow the template output links to Node 01/02 Management Portal. Login with the username: SuperUser and the password you selected in the CloudFormation.


Navigate to System Administration -> Configuration -> Mirror Settings -> Edit Mirror. Make sure system is configured with two Failover members.


Verify that mirrored database is created and active. System Administration -> Configuration -> Local Databases


JDBC connection validation - Follow “First Look JDBC” document to validate JDBC connectivity to IRIS via Load Balancer. Make sure to change url variable to the value displayed in Template Output and password form “SYS” to the one you have selected during the setup.


Failover Test


On the Node02 navigate to System Management Portal (see “HealthCheck” section above). Open Configuration->Edit Mirror page. At the bottom of the page you will see This member is the backup. Changes must be made on the primary.


Locate Node01 instance in AWS EC2 management dashboard. Its name will look similar to : MyStackName-Node01-1NGXXXXXX


Restart the Node01 instance. This will simulate instance/AZ outage.


Reload Node02 “Edit Mirror” page. Status message should change to: This member is the primary. Changes will be sent to other members.



Backup and Recovery


CloudFormation deployment does not enable backups for InterSystems IRIS. We recommend backing up IRIS EBS volumes, using EBS Snapshot in combination with IRIS Write Daemon Freeze.

Instance Failure

Unhealthy IRIS instances are detected by IRIS mirroring and Load Balancer and traffic is redirected to another mirror node. Instances that are capable to recover will rejoin the mirror and continue normal operations. If you encounter persistently unhealthy instances, please see IRIS Documentation and the “Emergency Maintenance” section of this guide.

Availability-Zone Failure

In the event of an availability-zone failure, temporary traffic disruptions may occur. Similar to instance failure IRIS mirroring and Load Balancer would handle the event by switching traffic to the IRIS instance in the remaining available AZ.

Region Failure

The architecture outlined in this guide does not deploy configuration that supports multi-region operation. IRIS Asynchronous mirroring and AWS Route53 can be used to build configurations capable of handling Region Failure with minimal disruption. Please refer to  for details.



Recovery Point Objective (RPO)

  • Single node Dev/Test configuration is defined by the time of the last successful backup.
  • Multi Zone Fault Tolerant setup provides Active-Active configuration, that ensures full data consistency in the event of failover with RPO of the last successful transaction.


Recovery Time Objective (RTO)

Storage Capacity

IRIS Journal and Database EBS volumes might reach capacity. InterSystems recommends monitoring Journal and Database volume state using IRIS Dashboard as well as Linux file-system tools such as df.


Both Journal and Database volumes might be expanded following the EBS guide Note: both EBS volume explanation and extending Linux file system steps need to be performed. Optionally, after the database backup is performed, journal space can be reclaimed by running Purge Journals


You might consider enabling CloudWatch Agent on your instances to monitor disk space (not enabled by this CloudFormation)


Security certificate expiration

You can use AWS Certificate Manager (ACM) to easily provision, deploy, manage, and monitor expiration of the Secure Sockets Layer/Transport Layer Security (SSL/TLS) certificates.


Certificates must be monitored for expiration. InterSystems does not provide an integrated process for monitoring certificate expiration. AWS provides a CloudFormation template that can help set up an alarm. Please visit the following link for details:

Routine Maintenance

For IRIS Upgrade procedures in mirrored configurations please refer to:


InterSystems recommends following the AWS and InterSystems best practices for ongoing tasks, including: 

Additionally you might consider adding CloudWatch Agent

 to your EC2 instances.



Emergency Maintenance


If EC2 instances are available, connect to the System Management Portal following the link in the Template Output. User: SuperUser, password you’ve entered at stack creation.


Note: Public IP of an instance might change after instance stop/start. That does not affect availability of the IRIS cluster and JDBC connection.


For command line access connect to them using EC2 SSH keys:


$ ssh -i my-private-key.pem ec2-user@<instance public IP>


To connect to IRIS command prompt use:


$ iris session iris


Consult InterSystems IRIS Management and Monitoring guide:


Contact InterSystems Support.


If EC2 instances are not available/reachable, contact AWS Support.


NOTE: AZ or instance failures will automatically be handled in our Multi-AZ deployment.




I cannot “Create stack” in CloudFormation

Please check that you have the appropriate permissions to “Create Stack”. Contact your AWS account admin for permissions, or AWS Support if you continue to encounter this issue.


Stack is being created, but I can’t access IRIS

It takes ~2 minutes from the moment EC2 instance status turns into “CREATE COMPLETED” to the moment IRIS is being fully available. SSH to the EC2 Node instances and identify if IRIS is running


$iris list


If you don’t see any active IRIS instances or the message “iris: command not found” appears then IRIS installation has failed. Check $cat /var/log/cloud-init-output.log on the instance to identify any problems with IRIS installation during instance first start.


IRIS is UP, but I can’t access either Management Portal or connect from my [Java] application

Make sure that Security Group, created by CloudFormation lists your source IP address as allowed.


Contact InterSystems Support

InterSystems’ Worldwide Response Center (WRC) provides expert technical assistance.


InterSystems IRIS Support is always included into your IRIS subscription.


Phone, email and online support are always available to all our clients 24 hours a day, 7 days a week. We maintain support advisers in 15 countries around the world and have specialists fluent in English, Spanish, Portuguese, Italian, Welsh, Arabic, Hindi, Chinese, Thai, Swedish, Korean, Japanese, Finnish, Russian, French, German, Hebrew, and Hungarian. Every one of our clients immediately gets help from a highly qualified support specialist who really cares about client success.


For Immediate Help


Support phone:

+1-617-621-0700 (US)

+44 (0) 844 854 2917 (UK)

0800615658 (NZ Toll Free)

1800 628 181 (Aus Toll Free)


Support email:


Support online:

WRC Direct

Contact for a login.





IAM Policy for EC2 instance


The following IAM policy would allow EC2 instance to read objects from S3 bucket ‘my-bucket’ and write logs to CloudWatch.



  "Version": "2012-10-17",

  "Statement": [


      "Sid": "S3BucketReadOnly",

      "Effect": "Allow",

      "Action": ["s3:GetObject"],

      "Resource": "arn:aws:s3:::my-bucket/*"



      "Sid": "CloudWatchWriteLogs",

      "Effect": "Allow",

      "Action": [






      "Resource": "arn:aws:logs:*:*:*"







Hi @Anton Kukharenka excellent work on this (and a lot of it too).

I was wondering if you can check the stack into an intersystems github repo so I can suggest some changes  and additions to the CF Template through a PR?  If not I can create one out of band too but thought it would be nice since its available to have it hosted in CC.