Topaz on AWS - Documentation

Table of Contents

Technology Introduction

What Is Amazon AppStream 2.0?

Amazon AppStream 2.0 is a fully managed, secure application streaming service that allows you to stream desktop applications from AWS to a web browser running on Windows and Linux PCs, Macs and Chromebooks, without rewriting them. Amazon AppStream 2.0 provides users instant-on access to the applications they need and a responsive, fluid user experience on the device of their choice. Read about AWS AppStream or review the AppStream 2.0 FAQ for further information about this service.

What Is CloudFormation?

AWS CloudFormation is a service that helps you model and set up your Amazon Web Services resources so that you can spend less time managing those resources and more time focusing on your applications that run in AWS.

You create a template within CloudFormation that describes all of the AWS resources that you want (like Amazon AppStream 2.0 or AWS Virtual Private Cloud networks), and AWS CloudFormation takes care of provisioning and configuring those resources for you. You don't need to individually create and configure AWS resources, or understand underlying dependencies; AWS CloudFormation handles all of that.

The following templates demonstrate how AWS CloudFormation can help with deploying Compuware Topaz Workbench on AWS. Please see the CloudFormation FAQ for further information about this AWS service.

What Is this Repository for?

This document outlines the Parameters and Resources needed to deploy Compuware Topaz Workbench on AWS AppStream 2.0 using AWS CloudFormation. At the end of this tutorial, you will be able to deploy a single VPN connection, deploy an auto-scaling group (up to ~2,000 instances) within an AppStream 2.0 architecture, and access a web-based streaming instance of Compuware's Topaz Workbench.

Who Is this Repository for?

This repository is for system administrators who are deploying Compuware Topaz Workbench on AppStream 2.0 in all available regions that are supported by AWS AppStream 2.0. As of October 2, 2017, the Topaz on AWS AppStream 2.0 templates can be deployed to us-west-2 (Oregon), us-east-1 (North Virginia), us-west-1 (Ireland), and ap-northeast-1 (Tokyo). AWS continues to expand the AppStream 2.0 service to additional regions.

Topaz on AWS contains two (2) templates to be used with the AWS CloudFormation service. Download your templates.

Please visit Compuware's Customer Success website for Topaz on AWS news and updates.

Cloud Security Notice



Traditional security frameworks, regulations and organizational policies define security requirements related to things such as firewall rules, network access controls, internal/external subnets, and operating system hardening. You can implement these in an AWS environment as well, but you now have the opportunity to capture them all in a script that defines a “Golden Environment.” This means you can create an AWS CloudFormation script that captures your security policy and reliably deploy it. With this script, security best practices can now be reused among multiple projects and become part of your Continuous Integration pipeline. You can perform security testing as part of your release cycle, and automatically discover application gaps that drift from your security policy.

Getting Started

The following instructions connect to the US-WEST-2 (Oregon) AWS region. Always validate you are creating resources in the correct AWS region.

Select a valid AWS region that supports the AWS AppStream service. This can be changed by using the region menu in the top right corner of the AWS Management Console. This is a global menu that is available from anywhere within AWS. As of October 2, 2017, the Topaz on AWS AppStream 2.0 templates can be deployed to us-west-2 (Oregon), us-east-1 (North Virginia), us-west-1 (Ireland), and ap-northeast-1 (Tokyo). AWS continues to expand the AppStream 2.0 service to additional regions.

If you have a custom download link from Compuware License Management then proceed to download our latest Topaz Workbench release. Otherwise, please contact Compuware License Support at

Topaz Workbench Deployment

  1. Create AWS Account or login to existing AWS account.
  2. Create a topaz_automation key in the AWS EC2 Management Console 'Key Pairs' dashboard. Creating this key allows CloudFormation to create the infrastructure required for this deployment.

    • Protip: Type 'EC2' within the console search box to locate the AWS EC2 Management Console. The keypairs option is located on the left side of the console in the network and security sub-section. Follow steps 1-5 on AWS on how to create an EC2 keypair.


  1. Deploy AWS Network. Download our CloudFormation template (topaz_appstream_network.yaml) or build your own using AWS VPC.

If you choose to build your own, you will need the following: Private cloud, gateways, private subnets, route tables, and security groups at a minimum.

Skip to Topaz Workbench AppStream Deployment if you have deployed your own network.


The following diagram illustrates the network topology that will be deployed when the template deployment is complete. The template will create two (2) subnets for high availability.


Make sure that your LAN routers are routing traffic for both AWS subnets (Subnet One and Subnet Two) to your gateway (likely a firewall). Your gateway will send the traffic over secure tunnels to AWS. See notes and step four (4) below on how to configure your local network.

Using Dynamic Routing

Using Static Routing

Select the CREATE_COMPLETE stack and take note of TopazPrivateSubnetOne, TopazPrivateSubnetTwo, TopazSecurityGroup, and TopazVPC keys located in the Outputs tab. See following image for an example. You will need these when deploying AWS AppStream.


  1. Configure an AWS VPN Connection to your data center

    • Navigate to the AWS VPC Dashboard.
    • (Optional) Use the VPC filter to organize the dashboard for your newly created VPC.
    • Navigate to your VPN Connection, and then download your hardware VPN Configuration. See AWS's list of tested devices

    This action will download an AWS-authored document with unique VPN configuration options for your AWS account. This file will include implementation directions.


Topaz Workbench AppStream Deployment

You are now ready to deploy Topaz Workbench.

If you have a custom download link from Compuware License Management then proceed to download our latest release. Otherwise, please contact Compuware License Support

The following steps will allow you to easily create the following AWS AppStream and Topaz architecture. This architecture will allow you to create a single instance of Compuware Topaz Workbench that can be streamed to mainframe developers globally. Using the AppStream service, a mainframe developer will only need a web browser (Internet Explorer, Edge, Firefox and Chrome are supported)


Build an AppStream 2.0 Topaz Workbench Image

Follow the AppStream 2.0 Image Builder guide. This AWS guide will assist you with creating an instance that will act as an origin for each stream created. Start with referencing steps 1 through 6 in section Step 1: Create an Image Builder.

Continue with Step 2: Installing Applications to an Image in the AppStream 2.0 Image Builder guide.

Install Topaz Workbench using the Topaz Workbench Installation Guide during product installation to help you configure product build options and integration points with other Compuware services residing on your Mainframe.

Once Topaz is installed on a AppStream Image, run Windows Notepad as Administrator to edit the Dosgi.instance.area option located in /Topaz Workbench/eclipse/topaz.ini*.

Take time now to create your standardized golden image that will be streamed to your development workforce.

Continue with Step 3: Adding Applications to an Image in the AppStream 2.0 Image Builder guide.

Deploy AWS AppStream 2.0 Auto-scaling Fleet

By using an AWS CloudFormation template, you will be able to easily deploy Topaz Workbench on AWS. The template will help you create a group of instances that will scale to the demand of Topaz Workbench.

  1. Navigate to your AWS CloudFormation dashboard.

  2. Select Create Stack.

  3. Download the Topaz for AWS AppStream 2.0 CloudFormation default template, and use the file selection tool in the CloudFormation dashboard to select the AppStream template from your local file system.

  4. In a few moments you will be able to access a fully capable streaming instance of Topaz Workbench that can communicate with your mainframe.

  5. Provide the input values that are required for the template and then select Next. Short descriptions are provided inline with each input parameter. If you used the Topaz on AWS network template as part of the Topaz on AWS solution, then you can use the keyword Topaz in the search-enabled input fields to quickly identify the appropriate subnets for this stack. Further details on each template parameter can be found below in the AppStream Template Reference within this document.

  6. Once you have provided the necessary CloudFormation parameters select Next.

  7. (Optional) Provide Tags to your deployment. Read more on AWS Tag strategies.
  8. Select Next to review your stack deployment.
  9. Make sure to allow the template to create IAM resources. This will be located at the bottom of the template review page. The stack will not create unless this parameter is true.
  10. Finally, Create the stack. This will take approximately ten (10) minutes to complete.

This stack creates an EC2 instance for temporary automation purposes. It can be identified by reviewing the EC2 instance resources in CloudFormation. Once identified, navigate to the AWS EC2 dashboard and remove this instance.

Start Topaz Workbench Streams

CloudFormation consumed the natural answers you provided in the template provisioning process and converted them into configuration options that AWS understands. Once the CloudFormation stack completes:

  1. Navigate to the AWS AppStream service dashboard to view your Topaz AppStream Fleets and Stacks.

CloudFormation orchestrated the deployment of your AppStream image, the Fleet it is associated to, and the Stack that will be deployed to developers. The template created the resources, but did not start streaming.

  1. Select the Fleet in the AppStream Management Console, and then select Start from the Actions menu.

Once the Fleet starts (~10 minutes), you will be able to provide access links to developers. You can either create new users by using AppStream's native User Pool, or you can integrate AppStream with Active Directory (ADFS). See AWS official documentation for configuring User Pools or ADFS integration.

By default, AWS limits the number of AppStream instances per account. Contact AWS Support by creating a Service Limit Increase case from within the AWS Management Console to increase your AppStream limits to your desired capacity.

Upgrade Topaz on AWS

To upgrade Topaz on AWS, repeat the process above by creating a new AppStream image using the AppStream Image Builder. The upgrade can be performed using your existing Topaz Workbench AppStream image, or a new one can be built from an AppStream-managed base operating system. Once complete, use the AWS CloudFormation template outlined in this document to create a new AppStream Fleet or use the AWS AppStream Management Console Stack and Fleet management tools.

Once the Fleet is created, it can be distributed and assigned to users by associating it to an existing AppStream Stack.

(Optional) Create a new AppStream Stack and assign users the new Stack alongside any existing Topaz Workbench Stack(s). This will allow users to have two (2) or more different versions of Topaz Workbench running concurrently. This is a great use case for managing different levels of deployment.

Single Stack Use Case


Concurrent Stack Use Case


AppStream Template Reference

Review the following section if you would like to gain a better understanding of various automation techniques used in our CloudFormation templates. Please feel free to modify the template to meet your organizational development needs. Please reach out to Compuware Customer Solutions for any assistance with Topaz, and please reach out to AWS Support for any assistance with AWS-related services.


  Type: String
  Default: Topaz-Workbench
  AllowedPattern: "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,100}"
  Description: This is the name for the AppStream Stack.
  #ConstraintRestriction: Name can only contain letters and numbers. No special characters except "-".

The Name: parameter is inherited by the AppStream Stack Name and the AppStream Fleet Name. The Default provided is Topaz-Workbench, but a best practice would be to set this key equal to your StackName. This is the top most form field displayed when adjusting the CloudFormation parameters in the AWS Management Console.

AllowedPattern: is set to restrict the user from providing a Name: that does not meet the requirements for either the Stack Name and Fleet Name AWS SDK CLI functions that will be utilized by the template. You can efficiently deploy a Fleet and Stack by avoiding special characters. If the input does not meet the AllowedPattern restrictions the build will fail, and the CloudFormation dashboard will prompt you to fix the error. Alphanumeric characters would be best to use here. Dashes ("-") are allowed.

Image Name

  #Type: AWS::AppStream::Image::Id
  Type: String
  Description: Copy the Topaz Image name string from the AppStream Image Builder.
  MinLength: 1
  AllowedPattern: "^[a-zA-Z0-9-._]*$" # Must only contain alphanumeric characters matching Topaz Workbench Image name. Can contain -.
  #ConstraintRestriction: Name can only contain letters and numbers. No special characters except "-".

The ImageName: parameter is used to inject your Topaz AppStream Image. You will need to copy your ImageName field from the AppStream dashboard in the AWS Management Console. Multiple images can be built with different Topaz Workbench feature sets. You have the ability to use different images in development and production environments. Image building allows you to deploy the latest features and plugins to users, groups, vendors or development lifecycles.

Stream Size

  Type: String
  Default: stream.standard.medium
   - stream.standard.medium
   - stream.standard.large
  Description: "Choose large if you have added more than just Topaz to your AppStream Image. M: ~.10/hr/user, L: ~.20/hr/user"

The StreamSize: parameter is used to control the EC2 resources that will be used to power the Topaz streaming IDE. View other sizing and pricing options available from AWS AppStream 2.0 at

Desired Streams

  Type: Number
  Default: 1
  Description: Minimum number of streams. AppStream has a 1 stream to 1 developer ratio.

The DesiredStreams: parameter is used to control your initial investment in the number of available streams when you first start your AppStream Fleet. This number can be adjusted by updating the Stack. An easier way to update the number is through the AWS Management Console once the CloudFormation template is deployed.

Scale Stream Max

  Type: Number
  Default: 5
  MinValue: 1
  MaxValue: 1000
  Description: Maximum number of streams. Set this to your average number of active daily developers.

ScaleStreamMax: is used to control your auto scaling initial capacity. The MinValue and MaxValue will be passed to the scale_appstream configset. This template uses multiple config keys and cfn-init will need to process these keys in a desired order.

Having an AWS Auto Scaling policy and AWS CloudWatch alarms embedded in this template allow you to be operationally efficient. The ScaleStreamMax parameter will start you with a simple policy that will support five (5) concurrent streams. The CloudWatch Autoscaling and Cloudwatch definition outlined later in this document will add two (2) streaming instances when total desired streaming capacity is 75% of the ScaleStreamMax. This template parameter is configured for a maximum of 1000 concurrent streams.

Note: If you used the Topaz on AWS network CloudFormation template provided in the Topaz On AWS solution than the resulting subnets deployed will only support 1019 unique IP addresses each. The additional addresses can be used for Topaz Workbench streams or other cloud instances running services of your choice. This scaling policy will have a hard time adjusting to a high request rate within a short time period. It is designed to add more streams above your stream estimated upper bound. For example, ten (10) developers logging on simultaneously will yield slower launch times for developers eight, nine, and ten. You will want to research and experiment to determine the lower and upper bounds for your scaling policy to be most efficient. Please see the Scaling Your Desktop Application Streams with Amazon AppStream 2.0 blog post by Deepak Sury, Principal Product Manager - Amazon AppStream 2.0 for more information on auto scaling and creating serverless schedules to control the size of your streaming Topaz Workbench Fleet.

Maximum User Duration

  Type: Number
  Default: 32400 #Maximum 16 Hours, Minimum 10 Minutes
  MinValue: 600
  MaxValue: 57600
  Description: "Default: 9 hr workday. The input can be in seconds between 600 and 57600."

MaxUserDuration: The maximum allowed time a user can be attached to a stream.

Disconnect Timeout

  Type: Number
  Default: 10800 #Maximum 16 Hours, Minimum 10 Minutes
  MinValue: 600
  MaxValue: 57600
  Description: The time after disconnection when a session is considered to have ended. If a user who was disconnected reconnects within this timeout interval, the user is connected back to their previous session. The input can be in seconds between 60 and 57600.

Fleet Description

  Type: String
  Default: Topaz Workbench Fleet
  MinLength: 1
  MaxLength: 100

Display Name

  Type: String
  Default: Topaz Workbench Fleet
  MinLength: 1
  MaxLength: 100
  Description: This is the name for the AppStream Fleet

Subnet One

  Type: AWS::EC2::Subnet::Id
  MinLength: 15
  MaxLength: 15
  AllowedPattern: "^[a-zA-Z0-9-]*$"
  Description: This subnet must have an active VPN connection to your mainframe-based services for Topaz Workbench to work properly.

If you used the Topaz on AWS network CloudFormation template, this will be tagged with TopazPrivateSubnetOne in the Outputs tab of the AWS CloudFormation dashboard.


Subnet Two

  Type: AWS::EC2::Subnet::Id
  MinLength: 15
  MaxLength: 15
  AllowedPattern: "^[a-zA-Z0-9-]*$"
  Description: Select an additional subnet for High Availability.

If you used the Topaz on AWS network CloudFormation template, this will be tagged with TopazPrivateSubnetTwo in the Outputs tab of the AWS CloudFormation dashboard.

Security Group

  Type: AWS::EC2::SecurityGroup::Id
  MinLength: 1
  MaxLength: 20
  AllowedPattern: "^[a-zA-Z0-9-]*$"
  Description: Provide the security group that you want to govern access to your streams. Search for "TopazSecurityGroup"

If you used the Topaz on AWS network CloudFormation template, this will be tagged with TopazSecurityGroup in the Outputs tab of the AWS CloudFormation dashboard.

Internet Access

Depending on your network security model, you will want to enable or disable access to the internet. By default, internet access is disabled for the streaming instance. This will keep the network isolated and only an extension of your on-premise data center.

  Type: String
  Default: false
   - "false"
   - "true"
  Description: Choose whether you want to enable internet access for each stream.

AWS EC2 Image Mappings

This section is not for your AppStream 2.0 image. The images listed below are maintained by AWS and contain up-to-date SDK and interfaces that will be used by CloudFormation to create the resources needed for a successful deployment. AWS CloudFormation is a great solution that has incorporated many AWS services. For example, the AppStream CLI SDK has extended features that that CloudFormation can take advantage of on behalf of a deployed EC2 instance. For the duration of the deployment, the template will create a temporary EC2 instance that leverages the AppStream 2.0 CLI SDK. Turning off this EC2 instance is recommended once your deployment is verified and operational.

  RegionMap:  #Only launch in regions where AppStream 2.0 is supported.
   us-east-1: #North Virginia
    "AMALINUX" : "ami-4fffc834" # AMALINUX OCTOBER 2017
   us-west-2: #Oregon
    "AMALINUX" : "ami-aa5ebdd2" # AMALINUX OCTOBER 2017
   eu-west-1: #Ireland
    "AMALINUX" : "ami-ebd02392" # AMALINUX OCTOBER 2017
   ap-northeast-1: #Tokyo
    "AMALINUX" : "ami-4af5022c" # AMALINUX OCTOBER 2017

The Mappings: block allows this template to scale into multiple regions where AppStream is available. The available regions can be derived from the Mappings block above. This template uses a temporary EC2 instance, which leverages the AppStream management options available in the AWS AppStream 2.0 CLI SDK that is pre-installed on AWS EC2 Amazon Linux instances by default. The instances are maintained by AWS and are available as public AMI (Amazon Machine Images).



Learn about AWS IAM in the AWS IAM Overview.

The AWS CloudFormation template for AppStream 2.0 requires an IAM role to access AWS services. The following policy is inherited by the EC2 instance at runtime and is used throughout deployment to orchestrate and align an AWS Well-Architected framework for Compuware Topaz Workbench to live within. Instead of passing IAM Keys to the instance, a profile will be assumed by the instance. In this case, the profile has full administrator access to AppStream and has the ability to create AWS Auto Scaling policies and AWS CloudWatch alarms. This IAM role name is created dynamically so the template can be re-used in the same region more than once and in multiple regions without having any overlap or conflicts with previous deployments. Learn more about IAM EC2 roles.

  Type: "AWS::IAM::Role"
    Version: "2012-10-17"
      Effect: "Allow"
        - ""
       - "sts:AssumeRole"
   Policies: #Modify IAM EC2 Role
     PolicyName: !Join ["", [!Ref "AWS::Region", "TopazAppStreamAutomationIAMRole"]]
      Version: "2012-10-17"
        Effect: "Allow"
        Action: "appstream:*"
        Resource: "*"
        Effect: "Allow"
         - "iam:GetRole"
         - "iam:PassRole"
        Resource: !Join ["", ["arn:aws:iam::", !Ref "AWS::AccountId", ":role/service-role/ApplicationAutoScalingForAmazonAppStreamAccess"]]
        Effect: "Allow"
        Action: #Policy actions for appstream configset
         - application-autoscaling:RegisterScalableTarget
         - application-autoscaling:PutScalingPolicy
         - cloudwatch:PutMetricAlarm
        Resource: "*"

  Type: "AWS::IAM::InstanceProfile"
     Ref: "TopazAppStreamAutomationIAMRole"


  Type: "AWS::EC2::Instance"
   ImageId: !FindInMap [RegionMap, !Ref "AWS::Region", AMALINUX] # Dynamic mapping to AMZLINUX in region
   InstanceType: t2.micro
   IamInstanceProfile: !Ref TopazAppStreamCloudformationProfile
   KeyName: topaz_automation
     !Sub |
       yum update -y aws-cfn-bootstrap # good practice - always do this.
       yum -y update
       pip install --upgrade awscli #update to latest aws cli sdk
       /opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource EC2 --configsets appstream --region ${AWS::Region}

This block defines the resources needed for an EC2 instance. This instance will be used temporarily to invoke the available functions in the AWS AppStream 2.0 CLI SDK. Currently, using the CLI with access to more AppStream API features offers more benefits than the limited native options in the CloudFormation API.

ImageId: references the EC2 Image Mappings block to retrieve the AMI-ID for the region into which this template is being deployed.

InstanceType: determines the size of the instance needed to perform these actions. The calls required to create Fleets and Stacks have minimal overhead and only the smallest instance is required. Place any additional commands in the UserData key, if you have other updates that you would like to make to this instance.

If your organization has a best practice around cloud-based Linux OS hardening, you may elect to use your own AMI. If so, the template will need to be updated with your private AMIs.

IamInstanceProfile: This property inherits the IAM role created in the IAM Resource block.

KeyName: Before using this template, create a Key Pair called topaz_automation. Once the key is created, you will be able to select it from the dropdown list of available keys in the region. If you are deploying this template into multiple regions, the same key name should be created in each region. When saving the key locally, make sure to append the region name or a unique identifier for quick access to it later. It is best practice to rotate your access keys. Read more on this topic on AWS.

      - "configure_cfn"
      - "create_appstream_templates"
      - "create_appstream"
      - "scale_appstream"
      - "create_cloudwatch_alarm"

Metadata:contains one (1) configset named appstream:. This configset contains four (4) sections that occur in the order that they interact with the EC2 instance, AppStream, Auto Scaling, and CloudWatch services. The sections below outline how each configset section contributes to the deployment of Topaz Workbench on AppStream.

       content: !Sub |
        action=/opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource EC2 --configsets appstream --region ${AWS::Region}
       content: !Sub |
       mode: "000400"
       owner: root
       group: root
     services: #Advanced: Set to 'true' if using template to update exisiting AppStream stacks or to manually invoke config sets via EC2 SSH access.
        enabled: "false"
        ensureRunning: "false"
         - "/etc/cfn/cfn-hup.conf"
         - "/etc/cfn/hooks.d/cfn-auto-reloader.conf"

First, configure_cfn sets the configuration of for cfn-hup. The cfn-hup helper is a daemon that detects changes in resource metadata and runs user-specified actions when a change is detected in the CloudFormation stack. This allows you to make configuration updates on your running Amazon EC2 instances through the UpdateStack API action.

This service is currently set to false as you will be shutting down, or removing the EC2 instance once the stack is deployed.

When you need to make changes to a stack's settings or change its resources, you can update the stack instead of creating a new one. For example, if you have a stack with an EC2 instance, you can update it to change the instance's AMI ID or to update the instance metadata. You can set the cfn-hup enabled and ensureRunning service values to true. This feature is very useful in development when experimenting with the template. This is discouraged in production as providing an update could reset current Fleet sizes back to template Fleet defaults and, in turn, disrupt end-user experience for your developers.

       content: !Sub |
          "Name": "${Name}-Fleet",
          "ImageName": "${ImageName}",
          "InstanceType": "${StreamSize}",
          "ComputeCapacity": {
            "DesiredInstances": ${DesiredStreams}
          "VpcConfig": {
            "SubnetIds": [
            "SecurityGroupIds": ["${SecurityGroup}"]
          "MaxUserDurationInSeconds": ${MaxUserDuration},
          "DisconnectTimeoutInSeconds": ${DisconnectTimeout},
          "Description": "${FleetDescription}",
          "DisplayName": "${DisplayName}",
          "EnableDefaultInternetAccess": ${DefaultInternetAccess}
       mode: "000644"
       owner: "root"
       group: "root"
       content: !Sub |
          "Name": "${Name}-Stack",
          "Description": "${Name} Stack created with Cloudformation",
          "DisplayName": "${Name} Stack"
       mode: "000644"
       owner: "root"
       group: "root"

The create_appstream_templates: configset section creates files in the /opt directory that will be used later by the EC2 CLI. These files are created dynamically to include the values you provide as Cloudformation parameters. While most of the parameters are passed into variables as-is, some are slightly modified by the template to align with the deployment and meet CloudFormation naming pattern restrictions. For example, ${Name} has -Fleet and -Stack appended where necessary. This helps identify Fleets and Stacks in the AWS Management Console and also serves as a critical component in ensuring the Fleet and Stack created in this template are properly associated with each other in a parent/child-like relationship. These universal naming conventions are used throughout the template to map other AWS services to the Fleet and Stack. Examples for Auto Scaling and CloudWatch are provided below. These files are created and saved as JSON.

      01_aws_sdk_config: #Update aws sdk config for localized region access
       cwd: "/opt"
       command: !Sub |
        aws configure set default.region ${AWS::Region} && aws configure set default.output json
       cwd: "/opt"
       command: aws appstream create-fleet --cli-input-json file://topaz_appstream_create_fleet.json
       cwd: "/opt"
       command: aws appstream create-stack --cli-input-json file://topaz_appstream_create_stack.json
      04_enable_homefolders: #Enable S3 Workspace storage
       cwd: "/opt"
       command: !Sub |
        aws appstream update-stack --name ${Name}-Stack --storage-connectors ConnectorType=HOMEFOLDERS
      05_associate_stream: #provide fleetname and stackname to associate
       cwd: "/opt"
       command: !Sub |
        aws appstream associate-fleet --fleet-name ${Name}-Fleet --stack-name ${Name}-Stack

In this section, we are taking advantage of commands. You can use the commands key to execute commands on the EC2 instance. The commands are processed in alphabetical order by name. Notice the 01, 02, and 03. You can also user a higher-level numbering convention like 100, 200 and 300 if you plan to add more automation to this template as it becomes easier to add commands in sequence. For example, 101 or 99.

01_aws_sdk_config: This command is used to configure the AWS SDK for the region where the EC2 instance was launched. For the following AppStream commands to work properly, the region needs to be set. JSON is currently set as the output type. This type is needed for Python parsing used later in the AppStream configset.

02_create_fleet: This command uses the JSON file created in the previous command to create an AppStream fleet based on the inputs supplied as AWS CloudFormation parameters. An AppStream 2.0 Fleet is a group of streaming instances from which user applications are executed and streamed.

03_create_stack: This command creates a Stack once the Fleet has been created. An AppStream 2.0 Stack consists of user access policies that control access to the Fleet associated with the Stack.

04_enable_homefolders: Enabling homefolders will activate a storage component that will persist as developer user settings and projects are created in Topaz Workbench. This allows a developer to leave a streaming session and return to Topaz Workbench where they previously left off. This is currently the only available option within AppStream for persistent storage of Topaz workspaces.

05_associate_stream: This command maps the Fleet and Stack created in steps 02_create_fleet and 03_create_stack of this config to be associated with one another.

       content: !Sub |
          "ServiceNamespace": "appstream",
          "ResourceId": "fleet/${Name}-Fleet",
          "ScalableDimension": "appstream:fleet:DesiredCapacity",
          "MinCapacity": 1,
          "MaxCapacity": ${ScaleStreamMax},
          "RoleARN": "arn:aws:iam::${AWS::AccountId}:role/service-role/ApplicationAutoScalingForAmazonAppStreamAccess"
       mode: "000644"
       owner: "root"
       group: "root"
       content: !Sub |
          "PolicyName": "${Name}-fleet-scale-out-policy",
          "ServiceNamespace": "appstream",
          "ResourceId": "fleet/${Name}-Fleet",
          "ScalableDimension": "appstream:fleet:DesiredCapacity",
          "PolicyType": "StepScaling",
          "StepScalingPolicyConfiguration": {
            "AdjustmentType": "ChangeInCapacity",
            "StepAdjustments": [
                "MetricIntervalLowerBound": 0,
                "ScalingAdjustment": 2
            "Cooldown": 300
       mode: "000644"
       owner: "root"
       group: "root"
      01_register_target: #Register fleet as autoscaling target
       cwd: "/opt"
       command: aws application-autoscaling register-scalable-target --cli-input-json file://topaz_appstream_autoscale.json
      02_extract_policy_arn: #Cloudformation Fleet Autoscale policy unsupported. Python extract substitute.
       cwd: "/opt"
       command: aws application-autoscaling put-scaling-policy --cli-input-json file://topaz_appstream_scale_out_policy.json | python -c 'import sys, json; print json.load(sys.stdin)["PolicyARN"]' | cat > /opt/AWS_AUTO_SCALE_ARN

Autoscaling and Cloudwatch

Once the Fleet and Stack are associated in the previous configset section, it is now time to set the default capacity, Auto Scaling and CloudWatch alarms to trigger scaling events when AppStream streams are in demand. These values will be passed in from the parameters supplied in the AWS CloudFormation dashboard.

First, two (2) files are created. appstream_autoscale.json for setting the default Desired Capacity when the Fleet is started. The default provided in this template is set to one (1). This is a good number to start with in development, but you will likely change this number to the minimum number of Topaz developers you expect per day once deployed to a production environment.

The second file, appstream_scale_out_policy.json defines the scaling policy you want to invoke when demand for Topaz Workbench crosses the utilization scaling threshold. In this case, two (2) new streaming instances will be deployed. There is also a Cooldown key provided. The Auto Scaling Cooldown period is a configurable setting for your Auto Scaling group that helps to ensure that Auto Scaling doesn't launch or terminate additional instances before the previous scaling activity takes effect.

The 01_register_target: creates a new scaling target for the Fleet, and 02_extract_policy_arn: is used to apply the scaling policy to the newly created target. This is where the ${Name} parameter plays a significant role.

The 02_extract_policy command also contains functionality not available in CloudFormation. In this command, the EC2 instance will pipe the JSON result of the new policy to a AWS_AUTO_SCALE_ARN file using Python. This value is not known at runtime, so we use the EC2 file system and native instance programmatic language to store a temporary variable that can be used in the 01_create_cloudwatch_alarms configset section of this template.

       cwd: "/opt"
       command: !Sub |
        aws cloudwatch put-metric-alarm --alarm-name ${Name}-fleet-scale-out-cloudwatch --alarm-description "Add 2 AppStream instances if Capacity Utilization >75%" --metric-name CapacityUtilization --namespace AWS/AppStream --statistic Average --period 300 --threshold 75 --comparison-operator GreaterThanThreshold --dimensions "Name=FleetName,Value=${Name}-Fleet" --evaluation-periods 1 --alarm-actions `cat /opt/AWS_AUTO_SCALE_ARN` --unit Percent

Once the auto scaling policy is created, a new AWS CloudWatch alarm will be created. AWS CloudWatch enables you to retrieve statistics as an ordered set of time-series data, known as metrics. You can use these metrics to verify that your system is performing as expected.

In this case, we are evaluating the AppStream Fleet capacity. If 75 percent of the Fleet is being utilized, then the Cloudwatch alarm will trigger the Auto Scaling policy from the previous step. This is where the PolicyARN created from the previous step allows the template to map the Cloudwatch alarm to the new policy. This is defined within the --alarm-actions parameter. Also, notice the use of ${Name}. This makes it very easy to locate the associated policies and CloudWatch alarms for the newly created Fleet in the AWS CloudWatch dashboard.

Storage Connector Notice

The AppStream 2.0 storage connector agent allows near real-time syncing between Compuware Topaz Workbench and AppStream 2.0 S3 based Home Folders. Enabling AppStream Home Folders is a requirement for Topaz on AWS if you intend for users to save Topaz Workbench workspaces. Workspaces contain critical configuration and user profile information that help enhance the Topaz Workbench end user experience from one AppStream session to the next. If Home Folders are disabled a user will be forced to configure personal settings for every session of Topaz Workbench.

As more work is completed by an end user the workspace size increases and yields a longer load time of the user Home Folder mount process.

It has been determined there is a race effect between the time Topaz Workbench is initialized and when the file system is mounted to the AWS environment. The following outlines a temporary patch to the AWS environment so it will briefly pause for a few moments when Topaz Workbench is launched by an end user.

The race effect described can cause previous LPAR connections, CICS region definitions, and saved work to not appear within Topaz Workbench. This is because Topaz Workbench takes ownership of the workspace file path before the AppStream storage agent completes the file sync process. The file system is considered empty and Topaz Workbench creates a new default workspace.

Read More..

Compuware Customer Success Portal

You can access online information for Compuware products via Customer Success portal at This portal provides access to critical information about your Compuware products. You can also review frequently asked questions, read or download documentation, access product fixes, or e-mail your questions or comments. The first time you access the site, you will be asked to register and obtain a password. Registration is free. Compuware also offers User Communities, online forums to collaborate, network, and exchange best practices with other Compuware solution users worldwide.

Compuware Support

We are here to help. Please don't hesitate to reach out to us using one of the following methods.


USA and Canada: 1-800-538-7822 or 1-313-227-5444.

All other countries: Contact your local Compuware office.

Please be sure to have the following information when you use Compuware's 24-hour telephone support:


Compuware Customer Success portal:

Note: Please report all high-priority issues by phone.


Customer Solutions Compuware Corporation One Campus Martius Detroit, MI 48226-5099

Corporate Web Site

To access Compuware's site on the Web, go to The Compuware site provides a variety of product and support information.

Amazon Web Services Support

Contact AWS Support for additional assistance or questions.