AWS Cloud Operations Blog

Software Deployment to Amazon WorkSpaces Using AWS Systems Manager

Amazon WorkSpaces is a fully managed virtual desktop environment that runs on AWS. It provides users with desktop cloud-based Microsoft Windows and Linux solutions that can be customized and configured to run seamlessly with your organization.

In this blog post, I show you how to install software onto a running WorkSpace using AWS Systems Manager, a service that provides an operational interface to manage, control, and automate tasks across AWS resources in the AWS Cloud and on-premises environments. I also go through the steps to remotely manage a WorkSpace instance by creating an activation that makes it possible to centrally manage EC2 instances and WorkSpaces from one location. I also show you how to install software using a Systems Manager Run Command operation.

Sukumar Bodapati, lead cloud engineer at OCC had this to say.

“Here at OCC we were looking to replace our current home grown Linux desktops with AWS workspace Linux Desktops. We were looking for an easier way to automate our operational tasks for maintaining our Workspaces desktops. After looking at and exploring our options, we decided to try AWS Systems Manager to remotely manage a workspace. We’re also using Systems Manager to review if all the workspaces are compliant with the baselines we have defined, and act on those that are non-compliant.”

The tutorial is designed to demonstrate some of the capabilities of AWS Systems Manager with WorkSpaces. It involves the guided steps to set up a running WorkSpace that is managed by SSM to silently install Notepad++.

The architecture involves an Amazon Virtual Private Cloud environment that is used to host the AWS Directory Service for user authentication and the Amazon WorkSpaces service. The communication between SSM and WorkSpaces is bidirectional through the private virtual interface. This allows private communications from an isolated Amazon-managed VPC to the SSM service.

Amazon Cloud Directory hosts end-user permissions to access a WorkSpace. Bidirectional communication from the SSM agent to AWS Systems Manager is directed through a private virtual interface to allow encrypted communications with SSM and the Run command service.

Figure 1: A VPC hosting Amazon Cloud Directory and Amazon WorkSpaces for user authentication

Prerequisites

Before you begin, you must have the following:

  • An AWS account to create or administer a WorkSpace.
  • The ability to download and access Amazon WorkSpaces from Windows, macOS, or Linux (Ubuntu) computers, Chromebooks, iPads, Fire tablets, Android tablets, and the Chrome and Firefox web browsers. For more information, see Amazon WorkSpaces Bundles.
  • Because Amazon WorkSpaces is not available in every AWS Region, select an AWS Region where the service is supported.

Build steps

  1. Sign in to the AWS Management Console at https://aws.amazon.com/console/.

WorkSpaces is displayed in the AWS Management Console under Desktop and App Streaming.

Figure 2: Amazon WorkSpaces entry in the AWS Management Console

2. Choose Amazon WorkSpaces, and then click Get Started Now in your AWS Region.

The workflow under the Get Started Now button in the AWS Management Console is to first select a bundle and set up users. The second step is to set up password and download client. The third step is to start using the service.

Figure 3: Amazon WorkSpaces console

3. On the Get Started with Amazon WorkSpaces page, choose Quick Setup. This is the right choice for working with a small subset of users.

Get Started with Amazon WorkSpaces page shows quick setup and advanced setup options.

Figure 4: Quick Setup and Advanced Setup options

4. Under Bundles, select Standard with Windows 10 Free tier eligible.

Console page shows the selected WorkSpace bundle option is Standard with Windows 10 Free tier eligible.

Figure 5: Bundles section of the console

5. Under Enter User Details, enter the user name, email address, and other details, and then choose Launch WorkSpaces.

A user named John Doe with an email address of johnd@example.com has been added under Enter User Details.

Figure 6: Enter User Details section of the console

The console displays a message that the WorkSpaces are being launched. The console also provides next steps that say an email will be sent to the added users requesting that they create a password, download the client, and sign in.

Figure 7: Next steps displayed in the console

 

6. The process takes approximately 20 minutes to complete. A confirmation email will be sent to the user’s email address that was entered in step 5. The email includes instructions for completing the profile setup, downloading additional client devices if needed, and applying the registration code.

 

An email displays a message for the end user to complete the user profile, download the WorkSpaces client, and launch the client with the provided registration code. The user can then sign in with the newly created password and provided user name.

Figure 8: Example email sent to new WorkSpace user

 

7. Click the link in the email, enter a password, and then choose Update User.

 

The console displays a user password registration window. The end user sets their WorkSpaces credentials by providing a new password and then choosing the Update User button.

Figure 9: Set your Amazon WorkSpaces credentials

 

8. After you set your credentials, you are redirected to https://clients.amazonworkspaces.com where you can check the connection status, download client devices, or use the web access login (disabled by default).

Now I show you how to use the AWS Systems Manager console to create an activation that makes it possible to centrally manage EC2 instances and WorkSpaces from one location.

AWS Systems Manager

Systems Manager provides a unified user interface so you can view operational data from multiple AWS services and allows you to automate operational tasks across your AWS resources. With Systems Manager, you can group resources, like EC2 instances, S3 buckets, or Amazon RDS instances. Systems Manager simplifies resource and application management. It also shortens the time to detect and resolve operational problems, which in turn makes it easier to operate and manage your infrastructure securely at scale.

  1. In the Systems Manager console, under Instances and Nodes, choose Hybrid Activations, and then choose Create an Activation.
  2. Under Activation setting, provide an optional description, the number of instances to manage, the IAM role used to enable communication between SSM Agent and the managed instances, and an optional default instance name. After you’ve entered these settings, choose Create Activation.

The console displays an Activation setting page with fields for providing an optional activation description, total number of servers to register, the IAM role to use, an activation expiry date, and an optional name for the managed instance.

Figure 10: Activation setting section of the Systems Manager console

 

3. When you receive a success notification, be sure to copy the activation code and activation ID. You need them in the next step.

 

The success notification displays the activation code and activation ID you need to install SSM Agent and manage your instance using Run Command.

Figure 11: Message displayed upon successful creation of an activation

 

4. Open the Amazon WorkSpaces console. In the dropdown field, paste the activation code and launch your WorkSpace client application you downloaded from https://clients.amazonworkspaces.com. Register it.

 

The Amazon WorkSpaces console displays a field for entering the registration code provided to you by your administrator.

Figure 12: Amazon WorkSpaces field for entering the registration code

Activate the SSM Agent on a WorkSpace server

You need to specify the code and ID you copied in step 6 for the following steps.

  1. Open and sign in to your WorkSpaces application.
  2. Open PowerShell and run as an administrator.
  3. Copy and paste the following commands into Notepad, but replace the highlighted parameters with the activation code, activation ID, and AWS Region.
$code = "activation-code"
$id = "activation-id"
$region = "region"
$dir = $env:TEMP + "\ssm"
New-Item -ItemType directory -Path $dir -Force
cd $dir
(New-Object System.Net.WebClient).DownloadFile("https://amazon-ssm-$region.s3.amazonaws.com/latest/windows_amd64/AmazonSSMAgentSetup.exe", $dir + "\AmazonSSMAgentSetup.exe")
Start-Process .\AmazonSSMAgentSetup.exe -ArgumentList @("/q", "/log", "install.log", "CODE=$code", "ID=$id", "REGION=$region") -Wait
Get-Content ($env:ProgramData + "\Amazon\SSM\InstanceData\registration")
Get-Service -Name "AmazonSSMAgent"

 

4. Press Enter to set up AWS Systems Manager for hybrid environments.

 

The command does the following:

  • Registers the WorkSpace with the SSM service.
  • Returns a response to the request similar to the following:
Directory: D:\Users\testuser\AppData\Local\Temp

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----        10/30/2020   4:30 PM                ssm
{"ManagedInstanceID":"mi-0b5541xxxxxxxxx","Region":"us-west-2"}

Status: Running
Name: AmazonSSMAgent
DisplayName: Amazon SSM Agent

Linux hybrid activation:

  1. Open and sign in to your WorkSpaces application.
  2. Open a Linux terminal and run as an administrator.
  3. Copy and paste the following commands into the terminal, but replace the highlighted parameters with the activation code, activation ID, and AWS Region.

 

mkdir /tmp/ssm
curl https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm -o /tmp/ssm/amazon-ssm-agent.rpm
sudo yum install -y /tmp/ssm/amazon-ssm-agent.rpm
sudo systemctl stop amazon-ssm-agent
sudo amazon-ssm-agent -register -code "activation-code" -id "activation-id" -region "region"
sudo systemctl start amazon-ssm-agent

 

4. Press Enter to install SSM Agent for a hybrid environment.

The command does the following:

  • Registers the WorkSpace with the SSM Agent.
  • Returns a response to the request similar to the following:

 

Transaction Summary
================================================================================
Upgrade 1 Package

Total size: 120 M
Downloading packages:
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
  Updating: amazon-ssm-agent-2.3.1644.0-1.x86_64                         1/2 
  Cleanup: amazon-ssm-agent-2.3.1319.0-1.amzn2.x86_64                   2/2 
Failed to execute operation: File exists
  Verifying: amazon-ssm-agent-2.3.1644.0-1.x86_64                         1/2 
  Verifying: amazon-ssm-agent-2.3.1319.0-1.amzn2.x86_64                   2/2 

Updated:
  amazon-ssm-agent.x86_64 0:2.3.1644.0-1                                        

Complete!

 

The WorkSpace is now a managed instance. It is displayed with the prefix “mi” in Systems Manager.

Use Systems Manager Run Command to install an application

AWS Systems Manager provides you safe, secure remote management of your instances at scale without signing in to your servers, replacing the need for bastion hosts, SSH, or remote PowerShell. It provides a simple way of automating common administrative tasks across groups of instances such as registry edits, user management, and software and patch installations. Through integration with AWS Identity and Access Management (IAM), you can apply granular permissions to control the actions users can perform on instances. All actions taken with Systems Manager are recorded by AWS CloudTrail, allowing you to audit changes throughout your environment.

From now on, you can use Systems Manager to configure Windows updates, install PowerShell Modules, install applications, join directory service domains, install updates, and patch baselines. In summary, there is full administrative control of the WorkSpace.

In this section, you install Notepad++ if it is not already installed on your WorkSpace. Be sure to stay signed in to your WorkSpace to confirm the installation.

  1. Open AWS Systems Manager console and select Run a Command.
  2. Select the AWS-RunPowerShellScript document.
  3. Under Commands, enter the following commands:

 

function Install-Npp ($source = ($env:TEMP + "\SW"))
{    
    If (!(Test-Path -Path $source -PathType Container)) {New-Item -Path $source -ItemType Directory | Out-Null}
    
    $packages = @(
    @{title='Notepad++ 7.8.6';url='https://github.com/notepad-plus-plus/notepad-plus-plus/releases/download/v7.8.6/npp.7.8.6.Installer.exe';Arguments=' /Q /S';Destination=$source}
    )

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    
    foreach ($package in $packages) {
            $packageName = $package.title
            $fileName = Split-Path $package.url -Leaf
            $destinationPath = $package.Destination + "\" + $fileName
    
    If (!(Test-Path -Path $destinationPath -PathType Leaf)) {
    
        Write-Host "Downloading $packageName"
        $webClient = New-Object System.Net.WebClient
        $webClient.DownloadFile($package.url,$destinationPath)
        }
        }
    
    foreach ($package in $packages) {
        $packageName = $package.title
        $fileName = Split-Path $package.url -Leaf
        $destinationPath = $package.Destination + "\" + $fileName
        $Arguments = $package.Arguments
        Write-Output "Installing $packageName"
    
    
    Invoke-Expression -Command "$destinationPath $Arguments"
    }
}
Install-Npp

 

These commands issue a silent installation of Notepad++ on the managed WorkSpace without interruption.

 

Under the Targets section in the AWS Systems Manager console, there are options to specify instance tags, choose instances manually, and choose a resource group. The option to choose instances manually is selected.

Figure 13: Targets and Instances sections of the console

 

4. Leave the Working Directory and Execution Timeout fields at their defaults, and then select Choose instances manually.

5. Leave as the other fields at their defaults, and then choose Run.

 

In the AWS Systems Manager console, the status of the issued commands from Systems Manager to the activated WorkSpace is displayed as In Progress.

Figure 14: Command status and targets and outputs in the console

 

6. On your WorkSpace, verify that Notepad++ is now installed.

 

Notepad++ appears in a search on the WorkSpace.

Figure 15: Notepad++ desktop app icon

The user can now control the WorkSpace environment using AWS Systems Manager, which simplifies automated command executions from a single user interface.

System Manager and WorkSpaces running mode considerations

When you set up WorkSpaces, you can specify the running mode in order to determine the availability of the WorkSpaces. These modes include AlwaysOn, which is ideal for users who use their WorkSpace full time or AutoStop, which disconnects after a specified period of time. The state of the applications and data is saved. AutoStop is a perfect choice for users who choose to pay by the hour.

For more information about running modes, see Manage the WorkSpace Running Mode in the Amazon WorkSpaces Administration Guide.

A managed instance is any EC2 instance or on-premises server or virtual machine (VM) in your hybrid environment that has been configured for Systems Manager. When WorkSpaces is activated as a managed instance with Systems Manager, you can control and manage the instance when the connection is online and WorkSpaces is in use.

Status of activated online SSM Agent on a WorkSpace machine is displayed as Online.

Figure 16: Status of activated online SSM Agent

 

When WorkSpaces is offline, you no longer have access to the managed instance (WorkSpace) until the connection is live again.

Status of an offline SSM Agent on a WorkSpace machine is displayed as Connection Lost.

Figure 17: Status of offline SSM Agent

 

The running mode you choose during the environment setup dictates the type of administrative access Systems Manager has on the WorkSpaces environment. If 24/7 access is required, review the AlwaysOn running mode option. If limited use is required, review the AutoStop running mode option times that suit your end user needs. For information about pricing, see Amazon WorkSpaces Pricing.

Conclusion

The WorkSpaces and Systems Manager solution described in this post helps you overcome common technical challenges associated with managing multiple virtual desktop environments—patching, asset management, and monitoring just to name a few. The advantages of having a unified user interface to manage multiple AWS services and to automate instructional tasks cannot be understated.

In this post, I explained what is required for Systems Manager to centrally manage WorkSpaces and showed how to accomplish activating SSM Agent and issuing run commands to managed WorkSpace hosts to install applications.

For more information about WorkSpaces and Systems Manager, see the following resources:

About the authors

Keith Andruch is an AWS Principal Architect based in Toronto, Canada. He has deep expertise in enterprise transformations, cloud migrations, automation, and designing cloud-based solutions on Amazon Web Services.

 

 

 

Sukumar Bodapati is a lead cloud engineer in the Platform Automation team at OCC where he uses his development, cloud, and infrastructure-as-code expertise to deliver cloud-native solutions that enable developer agility and power resilient business systems.