Tutorial: Replay and compare in AWS Mainframe Modernization Application Testing using CardDemo for AWS Blu Age deployed on Amazon EC2

In this tutorial, you will complete required steps to replay and compare testing workloads with the CardDemo application running on AWS Blu Age deployed on Amazon EC2.

Step 1: Obtain AWS Blu Age Amazon EC2 Amazon Machine Image (AMI)

Follow the instructions in the AWS Blu Age Runtime (on Amazon EC2) Setup tutorial for onboarding steps required to get access to AWS Blu Age on Amazon EC2 AMI.

Step 2: Start an Amazon EC2 instance using the AWS Blu Age AMI

1. Set up your AWS credentials.

2. Identify the location of the 3.5.0 Amazon EC2 AMI binary file (CLI only/AWS Blu Age version) from the Amazon S3 bucket:

   aws s3 ls s3://aws-bluage-runtime-artifacts-xxxxxxx-eu-west-1/
   aws s3 ls s3://aws-bluage-runtime-artifacts-xxxxxxx-eu-west-1/3.5.0/AMI/

   Note

   Application Testing feature is only available to use in 4 regions in prod (us-east-1, sa-east-1, eu-central-1 and ap-southeast-2).

3. Restore the AMI in your account with the following command:

   aws ec2 create-restore-image-task --object-key 3.5.0/AMI/ami-0182ffe3b9d63925b.bin --bucket aws-bluage-runtime-artifacts-xxxxxxx-eu-west-1 --region eu-west-1 --name "AWS BLUAGE RUNTIME AMI"

   Note

   Replace the AMI bin file name and the Region where you want to create the AMI.

4. After you create an Amazon EC2 instance you can find the correct AMI ID that was restored AMI from the Amazon S3 bucket in the Amazon EC2 image catalog.

   Note

   In this tutorial, the AMI ID is ami-0d0fafcc636fd1e6d, and you must change this ID in the different configuration files to the one provided to you.

   1. If the aws ec2 create-restore-image-task fails, then check your version of Python and CLI using the following command:

      aws --version

      Note

      Python version must be >= 3 and CLI version must be >= 2.

   2. If these versions are obsolete, the CLI must be updated. To update the CLI:

      1. Follow the instructions in Install or update the latest version of the AWS CLI.

      2. Remove CLI v1 with the following command:

         sudo yum remove awscli

      3. And install CLI v2 with the following commands:

         curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
         unzip awscliv2.zip
         sudo ./aws/install

      4. Finally, check version of Python and CLI with the following command:

         aws --version

   3. You can then redo the aws ec2 create-restore-image-task.

Step 3: Upload CardDemo dependent files to S3

Copy the content of folders databases, file-system, and userdata. Download and unzip the CardDemo applications. These three folders must be copied into one of your buckets called amzn-s3-demo-bucket in this documentation.

Step 4: Load databases and initialize the CardDemo application

Create a temporary Amazon EC2 instance that you will use as a compute resource to generate the required database snapshots for the CardDemo application. This EC2 instance will not run the CardDemo application itself, but instead generate the database snapshots that will be used later.

Start by editing the provided CloudFormation template named ‘load-and-create-ba-snapshots.yml.’ This is the CloudFormation template that's used to create the Amazon EC2 instance used to generate the database snapshots.

1. Generate and provide your EC2 key pair that will be used for the EC2 instance. For more information, see Create key pairs.

   Example:

   Ec2KeyPair:
       Description: 'ec2 key pair'
       Default: 'm2-tests-us-west-2'
       Type: String

2. Specify the Amazon S3 path of your folder where you have put the database folder from the previous step:

   S3DBScriptsPath:
       Description: 'S3 DB scripts folder path'
       Type: String
       Default: 's3://amzn-s3-demo-bucket/databases'

3. Specify the Amazon S3 path of your folder where you have put the file-system folder from the previous step:

   S3ApplicationFilesPath:
       Description: 'S3 application files folder path'
       Type: String
       Default: 's3://amzn-s3-demo-bucket/file-system'

4. Specify the Amazon S3 path of your folder where you have put the userdata folder from the previous step:

   S3UserDataPath:
       Description: 'S3 userdata folder path'
       Type: String
       Default: 's3://amzn-s3-demo-bucket/userdata'

5. Also specify an Amazon S3 path where you will save the result files to be used in the next step.

   S3SaveProducedFilesPath:
       Description: 'S3 path folder to save produced files'
       Type: String
       Default: 's3://amzn-s3-demo-bucket/post-produced-files'

6. Change the AMI ID with the correct one obtained earlier in this tutorial using the following template:

   
     BaaAmiId:
       Description: 'ami id (AL2) for ba anywhere'
       Default: 'ami-0bd41245734fd20d9'
       Type: String

   1. You can optionally change the name of the three snapshots that will be created by the run of the load databases with CloudFormation. These will be visible in the CloudFormation stack as it’s being created and will be used later in this tutorial. Remember to note the names used for the database snapshots.

      SnapshotPrimary:
          Description: 'Snapshot Name DB BA Primary'
          Type: String
          Default: 'snapshot-primary'
      
        SnapshotBluesam:
          Description: 'Snapshot Name DB BA Bluesam'
          Type: String
          Default: 'snapshot-bluesam'
      
        SnapshotJics:
          Description: 'Snapshot Name DB BA Jics'
          Type: String
          Default: 'snapshot-jics'

      Note

      In this document, we assume that the name of the snapshots remains consistent.

7. Run the CloudFormation with CLI or AWS console using the Create Stack button and wizard. At the end of the process, you should see three snapshots in the RDS console with the name you chose followed by a unique ID. You will need these names in the next step.

   Note

   RDS will add postfixes to the snapshots names defined in the AWS CloudFormation template. Be sure to obtain the full snapshot name from RDS before proceeding to the next step.

   Sample CLI command-

   aws cloudformation create-stack --stack-name load-and-create-ba-snapshots --template-url https://your-apptest-bucket.s3.us-west-2.amazonaws.com/load-and-create-ba-snapshots.yml --capabilities CAPABILITY_NAMED_IAM

   You can also check in the Amazon S3 path that you provided for S3SaveProducedFilesPath that the datasets have been correctly created.

Step 5: Launch AWS Blu Age runtime CloudFormation

Use CloudFormation to run the Amazon EC2 instance with the CardDemo AWS Blu Age application. You must replace some variables in the CloudFormation named m2-with-ba-using-snapshots-https-authentication.yml by editing the YAML file or by modifying the values in the console during launch of the CFN.

1. Modify the AllowedVpcEndpointPrincipals to specify which account will reach the VPC endpoint for accessing the AWS Blu Age runtime, using the following commands:

   AllowedVpcEndpointPrincipals:
       Description: 'comma-separated list of IAM users, IAM roles, or AWS accounts'
       Default: 'apptest.amazonaws.com'
       Type: String

2. Change the value of variables SnapshotPrimaryDb, SnapshotBlusamDb, and SnapshotJicsDb to the name of the snapshots. Also obtain the snapshots names from RDS after they were created in the previous step.

   SnapshotPrimary:
       Description: 'Snapshot DB cluster for DB Primary'
       Type: String
       Default: 'snapshot-primary87d067b0'
   
     SnapshotBluesam:
       Description: 'Snapshot DB cluster for DB Bluesam'
       Type: String
       Default: 'snapshot-bluesam87d067b0'
   
     SnapshotJics:
       Description: 'Snapshot DB cluster for DB Jics'
       Type: String
       Default: 'snapshot-jics87d067b0'

   Note

   RDS will add its own postfix to the snapshot names.

3. Provide your Amazon EC2 key pair for the EC2 instance, using this command:

   Ec2KeyPair:
       Description: 'ec2 key pair'
       Default: 'm2-tests-us-west-2'
       Type: String

4. Provide the AMI ID that you have obtained during the AMI registration process for the variable BaaAmiId, using:

   BaaAmiId:
       Description: 'ami id (AL2) for ba anywhere'
       Default: 'ami-0d0fafcc636fd1e6d'
       Type: String

5. Provide the Amazon S3 folder path that you used in the previous step to save the produced files, using the following command:

   S3ApplicationFilesPath:
       Description: 'bucket name'
       Type: String
       Default: 's3://amzn-s3-demo-bucket/post-produced-files'

6. Lastly, provide the folder path of the s3-userdata-folder-path:

   S3UserDataPath:
       Description: 'S3 userdata folder path'
       Type: String
       Default: 's3://amzn-s3-demo-bucket/userdata'

   • (Optional) You can enable the HTTPS mode and the basic HTTP authentication for tomcat. Although the default settings would also work.

     Note

     By default, the HTTPS mode is disabled and set to mode HTTP in the parameter BacHttpsMode:

     For example:

     BacHttpsMode:
         Description: 'http or https for Blue Age Runtime connection mode '
         Default: 'http'
         Type: String
         AllowedValues: [http, https]

   • (Optional) To enable HTTPS mode, you must change the value to HTTPS and to provide your ACM certificate ARN by changing the value of the variable ACMCertArn:

     ACMCertArn:
         Type: String
         Description: 'ACM certificate ARN'
         Default: 'your arn certificate'

   • (Optional) The basic authentication is disabled by default with the parameter WithBacBasicAuthentication set to false. You can enable it by setting the value to true.

     WithBacBasicAuthentication:
         Description: 'false or true for Blue Age Runtime Basic Authentication '
         Default: false
         Type: String
         AllowedValues: [true, false]

7. When you have completed the configuration, you can create the stack by using the edited CloudFormation template.

Step 6: Testing the AWS Blu Age Amazon EC2 instance

Manually run the CloudFormation template to create the AWS Blu Age Amazon EC2 instance for the CardDemo application to make sure that it starts without errors. This is done to verify that the CloudFormation template and all prerequisites are valid, before using the CloudFormation template with the Application Testing feature. You can then use Application Testing to automatically create the target AWS Blu Age Amazon EC2 instance during replay and compare.

1. Run the CloudFormation create stack command to create the AWS Blu Age Amazon EC2 instance, providing the m2-with-ba-using-snapshots-https-authentication.yml CloudFormation template you edited in the previous step:

   aws cloudformation create-stack --stack-name load-and-create-ba-snapshots —-template-url https://apptest-ba-demo.s3.us-west-2.amazonaws.com/m2-with-ba-using-snapshots-https-authentication.yml --capabilities CAPABILITY_NAMED_IAM --region us-west-2

   Note

   Remember to specify the correct Region where the AWS Blu Age AMI was restored.

2. Make sure that everything is working correctly by looking in the console to find the running Amazon EC2 instance. Connect to it using Session Manager.

3. After you are connected to the Amazon EC2 instance, use the following commands:

   sudo su
   cd /m2-anywhere/tomcat.gapwalk/velocity/logs
   cat catalina.log

4. Make sure that there are no exceptions or errors in the log.

5. Next, check that the application is responding by using this command:

   curl http://localhost:8080/gapwalk-application/

You will see the message, "Jics application is running."

Step 7: Validate previous steps were completed correctly

In the next several steps, we will use AWS Mainframe Modernization Application Testing to replay and compare datasets created by the CardDemo application. These steps rely on successful completion of all previous steps in this tutorial. Validate the following before proceeding:

1. You have successfully created the AWS Blu Age on Amazon EC2 instance through the AWS CloudFormation template.

2. The Tomcat service on the AWS Blu Age on Amazon EC2 is up and running, without exceptions.

When you get the EC2 instance running with the CardDemo application, complete the following steps on the Application Testing console to perform replay and compare for batch datasets.

Step 8: Create the test case

In this step, you create the test case that will be used to compare the datasets created in the Card Demo application.

1. Create a new test case. Give it a name and description.

2. Specify CREASTMT.JCL as the JCL name.

3. Add following datasets to Test case definition:

   Name	CCSID	RecordFormat	RecordLength
   AWS.M2.CARDDEMO.STATEMNT.PS	"037"	FB	80
   AWS.M2.CARDDEMO.STATEMNT.HTML	"037"	FB	100

   Note

   Your JCL name and dataset details must match.

Step 9: Create a test suite

1. Create a new test suite, and provide a name and description for it.

2. Add the test case that you created in the previous step to your test suite.

3. Once the test suite is created, capture test cases on mainframe, and upload mainframe reference data to AWS Application Testing.

4. Choose Create test suite.

Step 10: Create a test environment configuration

1. Create a new test environment configuration, and provide a name and description for it.

2. Add your CloudFormation template. You can also add input parameter name and value from you CloudFormation template.

3. Choose AWS Mainframe Modernization service AWS Blu Age non-managed as your runtime.

4. Add the output variable name for name for AWS Mainframe Modernization application ID, output variable name for VPC endpoint service ID, output variable name for Listener port, and output variable name for WebApp name.

   Note

   The names of these fields should match the output variable names from the CloudFormation template that will be returned from AWS Mainframe Modernization during stack creation.

5. (Optional) Choose output variable name for DMS (Database Migration Service) task ARN and source database DDL (Database definition language) S3 URI location.

6. (Optional) Customize your Key Management Service (KMS) key. For more information, see Managing access to customer managed keys in the AWS Key Management Service Developer Guide.

7. Choose Create test environment configuration.

Step 11: Upload your input data in test suite

In this step, you run test cases on the source. To do that:

1. Download and run the datasets that originated from the mainframe run of the CardDemo application.

2. Upload the unzipped folder to your Amazon S3 bucket. This Amazon S3 bucket must be in the same Region as your other Application Testing resources.

   Note

   There should be two files with the names matching the dataset names passed in the previous test case.

3. On the Test suite overview page, choose the Upload button.

4. On the Upload reference data page, specify the Amazon S3 location to where you uploaded the datasets obtained from the source mainframe.

5. Choose Upload to start the upload process.

   Note

   Wait for the recording to complete before you perform replay and compare.

Step 12: Replay and compare

Run the test suite and test cases in the target AWS AWS Blu Age on Amazon EC2 environment. Application Testing will capture the replay produced datasets, and compare them to the reference datasets that were recorded on the mainframe.

1. Choose Replay and compare. It should take about three minutes to create the CloudFormation stack, and perform the comparison.

Once everything is complete, you should have comparison results with a few differences intentionally created for the purpose of this demo.