Use the EUC Toolkit to manage Amazon AppStream 2.0 and Amazon WorkSpaces

Administrators can reduce self-managed VDI operational overhead by using End User Computing (EUC) managed services. Amazon AppStream 2.0 and Amazon WorkSpaces are fully managed, application, and desktop virtualization services. These services have APIs to programmatically manage and maintain the workload. The EUC Toolkit is an open-sourced tool to add additional functionality using the service-related public APIs. The toolkit is written in PowerShell and uses an XML GUI that can run on any Windows machine.

Overview

The EUC Toolkit offers a range of features to help manage EUC workloads at scale. The toolkit is open-sourced, so the code can be downloaded and modified as required. The initial release of the toolkit offers the following functionality:

Amazon WorkSpaces

• Search by any attribute:
  • First name, last name, computer name, WorkSpace ID, bundle ID, running mode, email, username, Region, and/or directory ID
• Bulk or single calls for start, stop, migrate, rebuild, restore, enable and disable admin maintenance (APIs optimized).
• Global WorkSpaces inventory visibility
• Export WorkSpaces report (CSV)
• Optional functionality:
  • Amazon CloudWatch metrics (service and OS level metrics)
  • AWS CloudTrail modification history
  • WorkSpaces access history
  • Windows Remote Assistance
  • Remote backup
  • Remote server-side log gathering

Amazon AppStream 2.0

• Query and display active sessions
• Filter active sessions by:
  • Stack, connected state, userId, session state, IP address, and/or Region
• View in-use IP of active sessions
• Terminate active sessions
• Export AppStream 2.0 report (CSV)
• Optional functionality:
  • Windows Remote Assistance

Overall Toolkit

• API logging
• Source permissions identifier (supports instance profiles)

Walkthrough

The following section will walk you through how to prepare and run the EUC Toolkit. Some optional features will require you to obtain third-party tooling. These features are outlined in the Optional section below. The steps are as follows:

• Download and configure the EUC Toolkit
• (Optional) Add additional functionality
• Run the EUC Toolkit

Prerequisites

For the toolkit to run properly, you need the following:

• Running Windows machine (Amazon Elastic Compute Cloud (Amazon EC2), WorkSpaces, AppStream 2.0)
• Active Directory permissions
  • Domain read credentials
    • To populate all attributes, the toolkit will invoke the Get-ADUser cmdlet. You will need to run the toolkit with a domain user that has rights to run this read operation on all domains in question. If these permissions aren’t available for the toolkit, the user’s first name, last name, and email won’t be present.
  • To use the Get-ADUser cmdlet, you must install Remote Server Administration Tools (RSAT). This can be performed with the following PowerShell command:

    • Install-WindowsFeature RSAT

  • Permissions to remote copy
    • When using the remote backup or gather logs functionality, the result is copied back to the host running the EUC Toolkit. For this copy to run correctly, the active EUC Toolkit user must have domain permissions to do so.
• AWS Tools for PowerShell EUC Modules
  • The toolkit requires cmdlets for WorkSpaces and AppStream 2.0 at a minimum. These cmdlets can be installed by running the following in PowerShell:

    • Install-Module -Name AWS.Tools.Installer -Force
      Install-AWSToolsModule AWS.Tools.WorkSpaces, AWS.Tools.AppStream

  • If you plan to use the WorkSpaces metrics functionality, you must include AWS.Tools.CloudTrail, AWS.Tools.CloudWatch, and AWS.Tools.CloudWatchLogs
• A local copy of the EUC Toolkit source code from GitHub.
• AWS Identity and Access Management (IAM) permissions
  • You must have IAM permissions to call the service APIs. It is a best practice to follow the principle of least privilege. The following policy provides access to APIs needed by to the toolkit. If you do not plan to use the WorkSpaces CloudWatch functionality, you may remove WorkSpacesCloudWatchImages and WorkSpacesCloudWatchMetrics from the policy.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EUCToolkitWorkSpaceAccess",
      "Action": [
        "workspaces:DescribeWorkspaceBundles",
        "workspaces:DescribeWorkspaceDirectories",
        "workspaces:DescribeWorkspaceSnapshots",
        "workspaces:DescribeWorkspaces",
        "workspaces:MigrateWorkspace",
        "workspaces:ModifyWorkspaceProperties",
        "workspaces:ModifyWorkspaceState",
        "workspaces:RebootWorkspaces",
        "workspaces:RebuildWorkspaces",
        "workspaces:RestoreWorkspace",
        "workspaces:StartWorkspaces",
        "workspaces:StopWorkspaces",
        "workspaces:TerminateWorkspaces"
      ],
      "Effect": "Allow",
      "Resource": "*"
    },
    {
      "Sid": "EUCToolkitAppStream2Access",
      "Action": [
        "appstream:DescribeSessions",
        "appstream:DescribeStacks",
        "appstream:ExpireSession",
        "appstream:ListAssociatedFleets"
      ],
      "Effect": "Allow",
      "Resource": "*"
    },
    {
      "Sid": "WorkSpacesCloudWatchImages",
      "Action": [
        "cloudwatch:GetMetricWidgetImage"
      ],
      "Effect": "Allow",
      "Resource": "*"
    },
    {
      "Sid": "WorkSpacesCloudWatchMetrics",
      "Action": [
        "logs:DescribeQueries",
        "logs:GetQueryResults",
        "logs:StartQuery"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

The table below summarizes the networking requirements:

Step 1: Download and configure the EUC Toolkit

Once you have met the prerequisites above, you can proceed with preparing your EUC Toolkit environment. Follow the steps below before continuing to the run the EUC Toolkit section.

1. Download the zipped EUC Toolkit repository from the GitHub repository.
2. Unzip the download to the location where you want to run the toolkit.
3. Open a PowerShell window and navigate to the directory containing the EUC Toolkit.
4. Set your AWS credentials for the toolkit to use when making service API calls. This can be accomplished by using the Set-AWSCredentials cmdlet. If you are using permissions from an instance profile, you may skip this step. If you are using AppStream 2.0 with an attached IAM role to host the toolkit, you can set your credential to use the attached role by running the following command:Set-AWSCredential -ProfileName appstream_machine_role
5. (Optional) If you are planning to populate Active Directory related fields, you can test Get-ADUser against your Active Directory environment to ensure it returns the required user attributes.

Step 2: Add optional functionality

This section outlines the steps needed to use all the features available in the EUC Toolkit. Several features require PsExec so the Toolkit can run commands on a remote host. To provide the remote backup functionality, the toolkit uses a combination of Disk2VHD and PsExec. For Remote Assistance, you will need to configure the targeted hosts to have the required components installed and a configuration applied. You can use all of these optional features by following the steps below.

1. Download PsExec onto the host running the EUC Toolkit. This utility is used to run commands on remote machines. If this is not provided to the toolkit, gather logs and remote backup will not work.
2. Once PsExec is downloaded, unzip the files and copy psexec.exe to the Assets folder within the EUC Toolkit’s parent folder. If you have PsExec stored elsewhere, set the path on the Administration tab of the toolkit.
3. Download Disk2VHD onto the host running the EUC Toolkit. This utility is used to create a VHD file from a targeted WorkSpaces user volume that can be saved and mounted. If this is not downloaded, the toolkit will not be able to create backups of the user volumes. If you have Disk2VHD stored elsewhere, set the path on the Administration tab of the toolkit.
4. Once Disk2VHD is downloaded, unzip the files and copy disk2vhd64.exe to the assets folder within the EUC Toolkit’s parent folder.
5. Remote Assistance is a Windows feature that allows administrators to prompt users to permit the admin to take over their session and remotely assist them with an issue. The feature must be installed on the EUC Toolkit host and the AppStream 2.0 and WorkSpaces instances. This should be installed to persist in your AppStream 2.0 and WorkSpaces image. To install the feature, run the following command in a PowerShell window with administrative rights: Install-WindowsFeature -Name Remote-Assistance
6. Once the Remote Assistance feature is installed, you will need to configure the targeted machines to allow the feature to prompt the user. This is performed by configuring a Group Policy Object (GPO) that can be applied to your AppStream 2.0 and WorkSpaces environment. To configure this GPO, follow the steps below.
   • Open Group Policy Management and configure the following:
     • Computer Configuration → Policies → Administrative Templates → System → Remote Assistance
     • Find the policy described as Configure Offer Remote Assistance. Once you have Enabled the policy, set the options to either “Allow helpers to only view the computer” or “Allow helpers to remotely control the computer”.
     • Choose Show and add the admin group or admin user to have access for Remote Assistance (ex: example.com\desktop admins).

Step 3: Run the EUC Toolkit

Once you have completed the steps above, you are ready to run the EUC Toolkit. To invoke this script, open a PowerShell window and navigate to the directory containing the EUC Toolkit. From the toolkit directory, run the following command:

.\EUCToolkit-Main.ps1

Conclusion

In this post, we showed how common administrative tasks can be automated using the EUC Toolkit. We walked through how to download and run the toolkit. We then followed the steps to add the optional functionality. The code is available on GitHub and can be further customized to address other challenges, such as running other remote commands on Amazon AppStream 2.0 and Amazon WorkSpaces. In addition, the functions in the EUCToolkit-Helper can be modified for other custom workflows.