IRIS on AWS

Partner Solution Deployment Guide

QS

February 2021
Steve LeBlanc, InterSystems Corp.
Dave May, AWS Integration & Automation team

Refer to the GitHub repository to view source files, report bugs, submit feature ideas, and post feedback about this Partner Solution. To comment on the documentation, refer to Feedback.

This Partner Solution was created by InterSystems Corp. in collaboration with Amazon Web Services (AWS). Partner Solutions are automated reference deployments that help people deploy popular technologies on AWS according to AWS best practices. If you’re unfamiliar with AWS Partner Solutions, refer to the AWS Partner Solution General Information Guide.

Overview

This Quick Start deploys IRIS on the AWS Cloud. If you are unfamiliar with AWS Quick Starts, refer to the AWS Quick Start General Information Guide.

The InterSystems IRIS data platform, used mainly in healthcare and financial services, supports rapid ingestion of data from various sources and sophisticated analytics. This Quick Start is for users who want to install IRIS on their own AWS account according to InterSystems and AWS best practices.

With the InterSystems IRIS data platform, you can build high-performance, machine learning applications that connect data and application silos. Specifically, IRIS is a database engine that supports transactional-analytic applications. Transactional applications deal with real-time data. Analytic applications deal with historical (non-real-time) data. Transactional-analytic applications make it possible for organizations to use insights gleaned from both real-time and historical data.

Costs and licenses

There is no cost to use this Quick Start, but you will be billed for any AWS services or resources that this Quick Start deploys. For more information, refer to the AWS Quick Start General Information Guide.

This deployment requires a noncontainer version of an InterSystems IRIS license key. If you’re an InterSystems customer, you can use your IRIS license key (iris.key) if you have one or request one by using the IRIS Evaluation Service. Otherwise, contact InterSystems.

Architecture

Deploying this Quick Start for a new virtual private cloud (VPC) with default parameters builds the following IRIS environment in the AWS Cloud.

Architecture
Figure 1. Quick Start architecture for IRIS on AWS

As shown in Figure 1, the Quick Start sets up the following:

  • An architecture that spans three Availability Zones.*

  • A VPC configured with public and private subnets, according to AWS best practices, to provide you with your own virtual network on AWS.*

  • In the public subnets:

    • Managed network address translation (NAT) gateways (not shown) to allow outbound internet access for resources in the private subnets.*

    • A Linux bastion host in an Auto Scaling group to allow inbound Secure Shell (SSH) access to Amazon Elastic Compute Cloud (Amazon EC2) instances in public and private subnets. If this bastion host becomes unavailable, a second host is provisioned.*

  • In the private subnets:

    • Two Amazon EC2 instances running as IRIS mirror nodes 1 and 2 in a security group across Availability Zones 1 and 2. Data is replicated in real time between the nodes.

    • One Amazon EC2 instance acting as a mirror arbiter in Availability Zone 3. The arbiter checks the health of the two mirror nodes and detects when a node is offline.

  • A Network Load Balancer, which distributes inbound traffic across the workload instances that you want to protect from outside access.

*The template that deploys the Quick Start into an existing VPC skips the components marked by asterisks and prompts you for your existing VPC configuration.

Deployment options

This Quick Start provides two deployment options:

  • Deploy IRIS into a new VPC. This option builds a new AWS environment consisting of the VPC, subnets, NAT gateways, security groups, bastion hosts, and other infrastructure components. It then deploys IRIS, consisting of two IRIS mirrored nodes and one arbiter node into this new VPC.

  • Deploy IRIS into an existing VPC. This option provisions IRIS in your existing AWS infrastructure.

The Quick Start provides separate templates for these options. It also lets you configure Classless Inter-Domain Routing (CIDR) blocks, instance types, and IRIS settings, as discussed later in this guide.

Predeployment steps

Acquire IRIS binaries files and license key

  1. Acquire the two InterSystems IRIS binaries files. They’re available to InterSystems customers at https://wrc.intersystems.com/. Log in with your InterSystems Worldwide Response Center (WRC) credentials and follow the links to Actions, SW Distributions, InterSystems IRIS. This Quick Start deployment guide is written for the InterSystems IRIS 2020.1 build 215. IRIS binaries file names have the format ISCAgent-2020.1.0.215.0-lnxrhx64.tar.gz and IRIS-2020.1.0.215.1-lnxrhx64.tar.gz.

  2. If you don’t already have one, acquire an IRIS license key (iris.key). For details, see the [Software licenses] section.

Prepare for the deployment

  1. Create an S3 bucket or select an existing S3 bucket where you’d like to put the two binaries files and your IRIS license key. Note this S3 bucket name; during deployment you will enter it for S3BucketNameParameter.

  2. Upload the two IRIS binaries files and your IRIS license key to the S3 bucket (replacing the bracketed text with your bucket name):

BUCKET=<my bucket>
aws s3 mb s3://$BUCKET
aws s3 cp ISCAgent-2020.1.0.215.0-lnxrhx64.tar.gz s3://$BUCKET
aws s3 cp IRIS-2020.1.0.215.1-lnxrhx64.tar.gz s3://$BUCKET
aws s3 cp iris.key s3://$BUCKET

Deployment steps

  1. Sign in to your AWS account, and launch this Partner Solution, as described under Deployment options. The AWS CloudFormation console opens with a prepopulated template.

  2. Choose the correct AWS Region, and then choose Next.

  3. On the Create stack page, keep the default setting for the template URL, and then choose Next.

  4. On the Specify stack details page, change the stack name if needed. Review the parameters for the template. Provide values for the parameters that require input. For all other parameters, review the default settings and customize them as necessary. When you finish reviewing and customizing the parameters, choose Next.

    Unless you’re customizing the Partner Solution templates or are instructed otherwise in this guide’s Predeployment section, don’t change the default settings for the following parameters: QSS3BucketName, QSS3BucketRegion, and QSS3KeyPrefix. Changing the values of these parameters will modify code references that point to the Amazon Simple Storage Service (Amazon S3) bucket name and key prefix. For more information, refer to the AWS Partner Solutions Contributor’s Guide.

  5. On the Configure stack options page, you can specify tags (key-value pairs) for resources in your stack and set advanced options. When you finish, choose Next.

  6. On the Review page, review and confirm the template settings. Under Capabilities, select all of the check boxes to acknowledge that the template creates AWS Identity and Access Management (IAM) resources that might require the ability to automatically expand macros.

  7. Choose Create stack. The stack takes about 20 minutes to deploy.

  8. Monitor the stack’s status, and when the status is CREATE_COMPLETE, the IRIS deployment is ready.

  9. To view the created resources, choose the Outputs tab.

Postdeployment steps

Test the deployment

  1. Connect to IRIS node 1 using the bastion host (replacing bracketed text).

$ chmod 400 <my-ec2-key>.pem
$ ssh-add <my-ec2-key>.pem
$ ssh -J ec2-user@<bastion-public-ip> ec2-user@<node01-private-ip> -L 52773:<node01-private-ip>:52773

The IRIS Management Portal for the instance should be available at http://localhost:52773/csp/sys/%25CSP.Portal.Home.zen with the following credentials:

  • User: SuperUser

  • Password: <password you entered at stack creation>

  1. Navigate to System Administration, Configuration, Mirror Settings, Edit Mirror. Make sure that the system is configured with two failover members.

  2. Navigate to System Administration, Configuration, Local Databases. Verify that the mirrored database is created and active.

  3. Following First Look JDBC and InterSystems Databases, validate JDBC connectivity to IRIS using the load balancer. Change the URL variable to the value displayed in the template output, and change the password from SYS to the one you selected during setup.

Failover test

This Quick Start is architected to be highly available. This means that the site remains available in the case of an instance or Availability Zone failure. To verify high availability, follow these steps to simulate a failure and perform a failover test.

  1. On node 2, navigate to the Management Portal (see Test the deployment section earlier).

  2. Open the Configuration, Edit Mirror page. At the bottom of the page you should see "This member is the backup. Changes must be made on the primary."

  3. Locate the node 1 instance in the Amazon EC2 management dashboard. Its name has the format MyStackName-Node01-1NG<XXXXXX>.

  4. Restart the node 1 instance. This will simulate an instance or Availability Zone outage.

  5. Reload the node 2 Edit Mirror page. The status should change to this: "This member is the primary. Changes will be sent to other members."

Troubleshooting

The IRIS Management Portal for the instance should be available at http://localhost:52773/csp/sys/%25CSP.Portal.Home.zen Credentials - User: SuperUser, and the password you entered at stack creation. If the IRIS Management Portal is inaccessible, troubleshooting the IRIS installation can be done from the command line.

  1. For command-line access, connect to the IRIS nodes using the bastion host (replacing the bracketed text):

$ chmod 400 <my-ec2-key>.pem
$ ssh-add <my-ec2-key>.pem
$ ssh -J ec2-user@<bastion-public-ip> ec2-user@<node-private-ip> -L 52773:<node-private-ip>:52773

  1. Connect to the EC2 node instances by using SSH. Verify that IRIS is running:

$iris list

  1. If you don’t see any active IRIS instances, or if the message iris: command not found appears, then IRIS installation has failed. View this log file on the instance to identify any problems with the IRIS installation during instance first start:

$cat /var/log/cloud-init-output.log

  1. To connect to the IRIS command prompt use:

$ iris session iris

Consult the InterSystems IRIS Management and Monitoring guide.

Contact InterSystems Support.

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

For troubleshooting common Quick Start issues, refer to the AWS Quick Start General Information Guide and Troubleshooting CloudFormation.

Customer responsibility

After you deploy a Partner Solution, confirm that your resources and services are updated and configured—including any required patches—to meet your security and other needs. For more information, refer to the Shared Responsibility Model.

Feedback

To submit feature ideas and report bugs, use the Issues section of the GitHub repository for this Partner Solution. To submit code, refer to the Partner Solution Contributor’s Guide. To submit feedback on this deployment guide, use the following GitHub links:

Notices

This document is provided for informational purposes only. It represents current AWS product offerings and practices as of the date of issue of this document, which are subject to change without notice. Customers are responsible for making their own independent assessment of the information in this document and any use of AWS products or services, each of which is provided "as is" without warranty of any kind, whether expressed or implied. This document does not create any warranties, representations, contractual commitments, conditions, or assurances from AWS, its affiliates, suppliers, or licensors. The responsibilities and liabilities of AWS to its customers are controlled by AWS agreements, and this document is not part of, nor does it modify, any agreement between AWS and its customers.

The software included with this paper is licensed under the Apache License, version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at https://aws.amazon.com/apache2.0/ or in the accompanying "license" file. This code is distributed on an "as is" basis, without warranties or conditions of any kind, either expressed or implied. Refer to the License for specific language governing permissions and limitations.