Desktop and Application Streaming

Using Kinesis Agent for Microsoft Windows to store AppStream 2.0 Windows Event Logs

The recently released Amazon Kinesis Agent for Microsoft Windows version 1.1.202.1 introduced support for AppStream 2.0’s AWS Identity and Access Management Role assertion. Besides Amazon Kinesis Data Stream and Amazon Kinesis Data Firehose, the Kinesis Agent for Microsoft Windows supports uploading to Amazon CloudWatch Logs. Using this, with an AppStream 2.0 session start script, it is possible to store log data in an easily searchable form for troubleshooting or auditing.

Overview

In this blog I will walk you through the setup of an IAM Policy, an IAM Role, and the install and configure the Kinesis Agent for Microsoft Windows. Additionally, you will configure a session start script to pass user session variables to the system context, then start the Kinesis Agent for Microsoft Windows.

You will complete the following tasks:

  1. Create an IAM Policy and Role to allow the AppStream 2.0 streaming instance to put CloudWatch Logs Events.
  2. Install and configure the Kinesis Agent for Microsoft Windows on an AppStream 2.0 Image Builder.
  3. Create PowerShell script to get AppStream 2.0 user context variables and start Kinesis Agent for Microsoft Windows, and configure it as system session start script.
  4. Create a custom image from AppStream 2.0 Image Builder.
  5. Create a Stack and Fleet from the custom image.

Prerequisites

You should have the following prerequisites:

  • An AWS account
  • An existing CloudWatch Log Group
  • A VPC with internet access
  • An AppStream 2.0 Image Builder

You can read more about Using an IAM Role to Grant Permissions to Applications and Scripts Running on AppStream 2.0 Streaming Instances in the AppStream 2.0 Administration Guide.

Create the IAM policy and IAM role

Step 1

In this step, you will create the IAM Policy that provides permission to the CloudWatch Logs. Then you will attach it to an IAM Role that your AppStream 2.0 streaming instances can assume.

  1. Navigate to the IAM console.
  2. In the navigation pane, choose Policies, Create policy.
  3. Choose the JSON tab. For Policy document, copy and paste the following JSON policy.
  4. Replace <region-code>, <AWS-Account-ID>, and <Log-Group-Name> with the appropriate details for your existing CloudWatch Log Group.
  5. Choose Review policy.
  6. Enter a name of your choosing and choose Create policy.

Policy document example

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogStream",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents"
            ],
            "Resource": [
                "arn:aws:logs:<region-code>:<AWS-Account-ID>:log-group:<Log-Group-Name>",
                "arn:aws:logs:<region-code>:<AWS-Account-ID>:log-group:<Log-Group-Name>:log-stream:*"
            ]
        }
    ]
}

Step 2

Now that the IAM Policy has been created, you can create the IAM Role for AppStream 2.0 to assume with the policy you just created.

  1. Open the IAM console.
  2. In the navigation pane, choose Roles, Create Role.
  3. For Select type of trusted entity, keep AWS service selected.
  4. Choose AppStream 2.0, Next: Permissions.
  5. In the Filter policies search box, type name of the policy created in step 1, and select the check box next to the policy name.
  6. Choose Next: Tags. Although you can specify a tag for the policy, a tag is not required.
  7. Choose Next: Review.
  8. Enter a name for your Role to help you identify it, choose Create role.

Installing and configuring Kinesis Agent for Microsoft Windows

  1. Connect to your AppStream 2.0 Image Builder as the Administrator.
  2. Using the browser of your choice on the image builder, download the Kinesis Agent for Microsoft Windows version 1.1.202.1 or higher. Alternatively, transfer a pre-downloaded file to the image builder using My Files.
  3. Once complete, navigate to the file location on the image builder and run the installer, accepting all the defaults from the prompts.
  4. Open a text editor, and open the Kinesis Agent for Microsoft Windows configuration file.  C:\Program Files\Amazon\AWSKinesisTap\appsettings.json.
  5. Replace the contents of the file with the example configuration below.
  6. Replace <Log-Group-Name> with the name of your existing CloudWatch Log Group, and <region-code> with the Region of your CloudWatch Log Group.
  7. Save the file, and close the text editor.
  8. Next open the Windows Services console, either from the start menu, or by running services.msc.
  9. Stop the service “Amazon Kinesis Agent for Microsoft Windows,” and set its startup type to Manual.

For more information about the Kinesis Agent for Microsoft Windows, refer to the Kinesis Agent for Microsoft Windows Getting Started guide.

Example AppSettings.JSON file contents

{
  "Sources": [
    {
      "Id": "ApplicationLog",
      "SourceType": "WindowsEventLogSource",
      "LogName": "Application"
    },
    {
      "Id": "SecurityLog",
      "SourceType": "WindowsEventLogSource",
      "LogName": "Security"
    },
    {
      "Id": "SystemLog",
      "SourceType": "WindowsEventLogSource",
      "LogName": "System"
    }
  ],
  "Sinks": [
    {
      "Id": "myCloudWatchLogsSink-App",
      "SinkType": "CloudWatchLogs",
      "ProfileName": "appstream_machine_role",
      "Region": "<region-code>",
      "LogGroup": "<Log-Group-Name>",
      "LogStream": "{env:AppStream_UserName}-Logs-Application"
    },
    {
      "Id": "myCloudWatchLogsSink-Sec",
      "SinkType": "CloudWatchLogs",
      "ProfileName": "appstream_machine_role",
      "Region": "<region-code>",
      "LogGroup": "<Log-Group-Name>",
      "LogStream": "{env:AppStream_UserName}-Logs-Security"
    },
    {
      "Id": "myCloudWatchLogsSink-Sys",
      "SinkType": "CloudWatchLogs",
      "ProfileName": "appstream_machine_role",
      "Region": "<region-code>",
      "LogGroup": "<Log-Group-Name>",
      "LogStream": "{env:AppStream_UserName}-Logs-System"
    }
  ],
  "Pipes": [
    {
      "Id": "SecurityLogToCloudWatchLogs",
      "SourceRef": "SecurityLog",
      "SinkRef": "myCloudWatchLogsSink-Sec"
    },
    {
      "Id": "ApplicationLogToCloudWatchLogs",
      "SourceRef": "ApplicationLog",
      "SinkRef": "myCloudWatchLogsSink-App"
    },
    {
      "Id": "SystemLogToCloudWatchLogs",
      "SourceRef": "SystemLog",
      "SinkRef": "myCloudWatchLogsSink-Sys"
    }
  ],
  "SelfUpdate": 0 //minutes
} 

Configure session start script

  1. Still connected to your AppStream 2.0 Image Builder as the Administrator.
  2. Create a folder somewhere on the root drive of the image builder for storing the PowerShell script, for example Scripts on C:\ drive.
  3. Open a text editor of your choice, and copy the script below, then save the script to the previously created folder as a .ps1 file, for example script.ps1.

PowerShell script

#Add PS drive for HKEY_USERS to access User Context environment variables
New-PSDrive -PSProvider Registry -Name HKU -Root HKEY_USERS
#Get logged in username
$ConsoleUser = (Get-WmiObject win32_computersystem).username.split("\\")[1]
#Setup filter string for getting logged in user SID
$filterstring = "name = '" + $ConsoleUser + "'"
#Get logged in user SID
$ConsoleUserSID = (Get-WmiObject win32_useraccount –Filter $filterstring).SID
#Get user context environment variable AppStream_UserName
$AppStream_UserName = (get-ItemProperty -Path HKU:\$ConsoleUserSID\Environment -Name AppStream_UserName -ErrorAction SilentlyContinue).AppStream_UserName
#Set system context environment variable AppStream_UserName
[System.Environment]::SetEnvironmentVariable('AppStream_UserName',$AppStream_UserName,[System.EnvironmentVariableTarget]::Machine)
#Start Kinesis Agent for Microsoft Windows
start-service AWSKinesisTap
  1. Open the file C:\AppStream\SessionScripts\config.json in your preferred text editor, and modify following attributes for the SessionStart executable for the system context. Replace the <path-to> and <script-file.ps1> with the appropriate values for the script file previously created, for example Script and script.ps1.
"filename": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
"arguments": "-File \"C:\\<path-to>\\<script-file.ps1>\"",
  1. Save the file, and close the text editor.

For more information about using AppStream 2.0 session scripts, refer to Use Session Scripts to Manage Your AppStream 2.0 Users’ Streaming Experience.

Create AppStream 2.0 custom image, fleet, and stack

  1. Create a custom image through Image Assistant on the image builder. Tutorial: Create a Custom AppStream 2.0 Image by Using the AppStream 2.0 Console.
  2. Once the custom image is available, create a stack and a fleet. While creating the Fleet, select the custom image you just created. Ensure that the Fleet has access the CloudWatch service, and assign the IAM role created earlier to the Fleet.  Tutorial: Create an AppStream 2.0 Fleet and Stack.
  3. Finally, to test, once a user connects to a Fleet instance, the agent will start uploading logs under the user name to the configured destination.

Log example

CloudWatch Log Stream showing captured Windows Event logs by user name

CloudWatch Logs Console Screenshot

Figure 1 CloudWatch Logs example

 Cleaning up

To avoid incurring future charges, stop and delete unused AppStream 2.0 resources such as image builders, fleets and stacks, and unneeded CloudWatch Log Streams.

Conclusion

In this post, you walked through one of the options to push Windows Event Logs from AppStream 2.0 streaming instances to CloudWatch Logs. Next you can continue learning more about Analyzing Log Data with CloudWatch Logs Insights.