- Introduction
- Diagram of example
- CloudFormation template overview
- Quick, repeatable deployment process
- Quick cleanup of all resources
- How to use these templates
- DevFootprintNetwork.json
- Post creation steps
- DevFootprintRDS_MySql.json
- Post creation steps
- DevFootprintServers.json
- Authenticated S3 bucket tips
- Post creation steps
- Troubleshooting
- CloudFormation console
- cfn-hup logs
- What next?
Introduction
This document is an example of how to set up IdentityIQ on Amazon Web Services (AWS) components for learning and development purposes only. The reader assumes responsibility for the use of these examples and scripts in AWS. The reader should reference AWS documentation and training for any questions related to AWS.
This article is a walk-through of the attached examples that shows you how to use the attached CloudFormation (CF) templates to set up or tear down the AWS resources you need for a small IdentityIQ development environment in just minutes. This environment consists of:
- One MySql Relational Database Service(RDS) instance
- One VPC (virtual private cloud) that has two subnets, each in different availability zones (AZ)
- Two Windows servers with Tomcat installed, each in different availability zones (AZ)
- One load balancer for the Tomcat server traffic
Diagram of example
Note that for brevity some details are omitted from this diagram, but it provides the overall structure of the CloudFormation template output.
CloudFormation template overview
Quick, repeatable deployment process
CF is an AWS service that lets you define templates to quickly provision networks, servers, and applications to AWS.
The attached CF templates are specifically designed for setting up a small IdentityIQ development environment (i.e. this is not representative of a production environment). Each template defines an interactive web form for gathering custom information, such as the names to assign to each server or the AZs to deploy them in. This information (stored in CF parameters) is combined with other configuration information contained in the template to create the AWS resources. All the resources created by any single template are collectively known as a "stack". Shown below is a screenshot of the CloudFormation console, including the "Create Stack" button:
Shown below is a sample CloudFormation template input form:
Finally, here is an example of a template build in process:
Quick cleanup of all resources
Later when you are done with the stack you can delete it with just a couple of clicks, which will delete all the resources that were deployed in that stack. This makes it very easy to start with a fresh environment. Shown below is a screenshot of deleting a stack using the CloudFormation console:
How to use these templates
To set up a development environment using these templates you upload each template to the CF console. There are three CF template examples included with this article.
- DevFootprintNetwork.json - This template creates a network to deploy the RDS instance and servers. This template is optional, but if it is to be used it must be run before the other templates.
- DevFootprintRDS_MySql.json - This template creates a MySQL RDS database instance for IdentityIQ. This template is not necessary if you have an existing database service that will be used by IdentityIQ.
- DevFootprintServers.json - This template deploys two Windows servers, one in each availability zone and subnet selected. This CF template requires external scripts and installation media to perform setup actions via AWS::CloudFormation::Init.
DevFootprintNetwork.json
This template creates a new AWS VPC, two subnets, and three security groups for the IdentityIQ servers. If you have these components in your environment already then you do not need to use this template, and you can skip to the other templates. If you are using this template it is helpful to have the information below ready, or use the suggested values that the template provides.
- The IP address from which administrative traffic originates
- The IP address from which end user traffic originates
- The IP CIDR for the subnet for the VPC that will be created
- The IP CIDR for each of the 2 subnets that will be created
- The AZs in which each subnet will be created
Post creation steps
Verify that the resources were created as expected, especially the IP addressing used in any security groups.
DevFootprintRDS_MySql.json
This template creates a MySql RDS database instance. If you are using this template it is helpful to have the information below ready, or use the suggested values that the template provides.
- The VPC where the RDS instance will be available
- The subnets where the RDS instance will be available
- The security groups that provide access to administrators, end-users, and other hosts in the VPC
- The IP CIDR of the IdentityIQ servers (even if not yet deployed)
- RDS configuration information
Post creation steps
Verify that the resources were created as expected, especially the IP addressing used in any security groups. Also update the passwords of any resources that were created.
DevFootprintServers.json
The deployment of EC2 instances with layered automation inevitably calls for accessing scripts or installation media from a common location. While this article discusses a non-production IdentityIQ deployment, information security should still be a consideration. In our example, we utilize an authenticated, non-public S3 bucket. Before using S3 buckets, please refer to the AWS security guide on this topic; Help Ensure Your S3 Resources Are Secure. As an example, putting your generated identityiq.war file in a public S3 bucket means anyone on internet can download your build file; this is likely not what anyone wants for any IdentityIQ environment, and our example here demonstrates how to avoid this issue while still allowing for proper automation. When in doubt, check with your information security team.
This template creates two Windows Server EC2 instances from an AWS Amazon Machine Image (AMI) of our choosing; for this example, we recommend the Windows Server 2016 Base AMI for the region you target.
Here is an example of where you would locate the AMI ID:
Several configuration changes to the servers, including installing Tomcat, are part of the deployment. In addition, an AWS load balancer is also deployed. If you are using this template it is helpful to have the information below ready, or use the suggested values that the template provides.
- The AMI ID of the image you will build your Windows servers from (e.g. you can look this up in the AMI catalog when you use the EC2 "launch instance" button)
- The VPC where the instances will be deployed
- The subnets where the instances will be deployed
- The security groups that provide access to administrators, end-users and other hosts in the VPC
- Server name, IP address and administrator password to assign each server
- The security groups that provide access to administrators, end-users and other hosts in the VPC
- A non-public S3 bucket and the secret key ID & value for accessing the bucket
Some preparation is required if Tomcat is to be installed:
- Several script files are included in the zip file. These must be saved to a location on your network that is accessible to the instances being deployed; an ideal place is an authenticated, non-public S3 bucket, which we use in this example.
- The binaries for installing Tomcat, Notepad++, JDK, and other software are not included in the example files. You must download and save the binary files to a location on your network that is accessible to the instances being deployed; again, an ideal place is an authenticated, non-public S3 bucket, which we use in this example.
- The identityiq.war is not included in the example files and must be distributed like points 1 & 2 immediately above. Do not put this in a public S3 bucket.
Specifically, here are the files & versions used for the Windows setup:
- npp.7.5.6.bin.minimalist.7z (Notepad++)
- jdk-8u171-windows-x64.exe (Oracle JDK
- apache-tomcat-8.5.31-windows-x64.zip (Tomcat 8.5)
- identityiq.war (IdentityIQ deployment file for Tomcat, which you must provide via another build method, like the SSB)
- Miscellaneous scripts files from the zip file attached to this article; upload these without renaming them, but know there are some hard-coded versions in the installation scripts (e.g. Install_Tomcat8.ps1), and you should be mindful of each script's content if you change versions of Tomcat or JDK, etc.
Once all the files are uploaded, an example S3 bucket for this sample deployment might look like this:
The template will use a base path (e.g. your non-public S3 bucket) and secret key ID & value and build paths to each specific item for download. Check in the json file for segments like this to distinguish all the files:
In the above screenshot, you can also confirm S3 credentials are used with the "authentication" reference parameter.
Authenticated S3 bucket tips
To create a S3 bucket that will require authentication and provide a measure of protection, you must first create an IAM user that has the rights to look into S3 buckets. In this case, I granted broad "read only" rights.
Next, you must have appropriate credentials for the API (e.g. to use S3 type authentication in a CF template). You do this by creating an access key for your user, as shown here (some info obscured):
When you create the access key, you get a key ID and a key secret value - keep the secret value safe, as it is essentially a password.
Once you've got these taken care of, you can create your S3 bucket (by default it is private) and upload all the files for the build (as we mention in the previous section).
Finally, when using the server CF template, you can insert your appropriate access key ID and secret value into the CF input form like shown (some info obscured):
Post creation steps
Verify that the resources were created as expected, especially the IP addressing used in any security groups. Also update the passwords of any resources that were created.
Log into each server and verify that the programs were installed as expected (e.g. is Tomcat listening on 8080?).
Troubleshooting
CloudFormation console
The CF console shows the current status and success/failure of each resource operation.
cfn-hup logs
The cfn-hup helper is a daemon deployed on the AWS instances that detects changes in resource metadata and runs user-specified actions when a change is detected. This service runs the configuration scripts that are referenced in the templates. These logs record each step of the deployment scripts and errors. Missing script or binary files, no permissions to download files, syntax errors are some of what you will find in these logs. They are located in c:\cfn\logs
What next?
Deployment is only a small part of the larger software development & maintenance life cycle. This example provides an example for creating a simple environment for testing, but may lack connectivity to other business systems your company manages. Connection to these line-of-business systems is left as an exercise for the reader, as they will vary with each client-specific implementation. As a hybrid on-premise & cloud architecture matures, the networking and security requirements will likely dictate some sort of private connection (e.g. a VPN tunnel from on-premise data centers to one or more AWS regions). This architectural component is beyond the scope of this article (due to complexity and client-specific implementations) and should be addressed via other mechanisms.
The reader should also be aware that a default setup of IdentityIQ, using the approach contained herein, may leave some elements exposed. For more information on securing IdentityIQ, please refer to the IdentityIQ Secure Deployment Guide. For all other related components, domain-specific knowledge is required, with responsibility for security and administration involving a number of groups/individuals at your company.
