Automatically Launching Cloud-based Linux Desktops with PowerShell and Amazon WorkSpaces


Amazon WorkSpaces provides a mechanism to rapidly deploy cloud-based desktop systems that can be used by software developers, call center representatives, knowledge workers, and nearly any other role. They’re great for short-term contractor roles as well, since they don’t require physical procurement of any new hardware.

In the rest of this article, we’ll explore how you can use the AWS Tools for PowerShell to automate deployment of AWS WorkSpaces.

Quick Intro to AWS Directory Services

Although it’s outside the scope of this article, in order to deploy AWS WorkSpaces, you’ll need to have an AWS Directory Services connector already set up to connect to your pre-existing Microsoft Active Directory domain controller. If you don’t have an Active Directory domain (ie. you’re a sandbox / lab environment), you can set up an Active Directory forest/domain on an Amazon EC2 instance running Windows Server.

As an alternative to the AD Connector, you can also deploy an AWS Managed Microsoft Active Directory instance or a Simple AD (Samba-based Active Directory) directory service, under AWS Directory Services. Keep in mind though, that either of these options will require you to spin up a separate, domain-joined Windows Server EC2 instance in order to manage user accounts. There are not currently any public AWS APIs that allow you to manage users in the managed directories provided by AWS Directory Service.

Regardless of which option you choose (Simple AD, Managed AD, or AD Connector), you will need your AWS Directory Service ID in order to deploy an AWS WorkSpace, as each WorkSpace must be associated with a directory.

Exploring AWS WorkSpaces Bundles

When you launch AWS WorkSpaces, you select from a list of pre-configured bundles (pre-built CPU / memory / disk configurations) provided by Amazon. You can use the AWS Tools for PowerShell to explore these bundles.

If you require customization of an operating system image, you can configure an AWS WorkSpace, take an image of it, and then create a custom bundle. A custom bundle consists of the desired image along with a pre-configured set of WorkSpace hardware options (CPU, memory, and disk). Custom bundles can then be used to directly launch new AWS WorkSpaces.

IMPORTANT: There is not currently any service API that allows you to create an image using automation. The only way to capture an image in AWS WorkSpaces is by using the AWS Management Console.

Let’s start by exploring the Amazon-provided bundles.

Get-WKSWorkspaceBundle -Owner Amazon

You’ll notice that the output is provided in a list format, so let’s get it into a tabular format, for easier viewing.

Get-WKSWorkspaceBundle -Owner Amazon | Format-Table

This looks better, but we can discard some of the bundle properties, to clean up the view.

Get-WKSWorkspaceBundle -Owner Amazon | Format-Table -Property `
  BundleId, Name, `
  @{ Name = 'ComputeType'; Expression = { $_.ComputeType.Name} }, `
  @{ Name = 'RootStorage'; Expression = { $_.RootStorage.Capacity} }, `
  @{ Name = 'UserStorage'; Expression = { $_.UserStorage.Capacity} }, `

This is a much cleaner view of the WorkSpace bundles. However, we probably only care about the most recently updated images. We can sort the bundles by the LastUpdatedTime property, and then use the Select-Object command to grab only the last 15 bundles.

Get-WKSWorkspaceBundle -Owner Amazon | Sort-Object -Property LastUpdatedTime | Select-Object -Last 15 | Format-Table -Property `
  BundleId, Name, `
  @{ Name = 'ComputeType'; Expression = { $_.ComputeType.Name} }, `
  @{ Name = 'RootStorage'; Expression = { $_.RootStorage.Capacity} }, `
  @{ Name = 'UserStorage'; Expression = { $_.UserStorage.Capacity} }, `

Filtering Results for Amazon Linux

AWS WorkSpaces supports both Windows and Linux as operating systems. If you’d like to filter your results to only Amazon Linux Workspaces, you can use the Where-Object command.

Get-WKSWorkspaceBundle -Owner Amazon | Where-Object -FilterScript { $PSItem.Name -match 'Linux' } | `
  Sort-Object -Property LastUpdatedTime | Format-Table -Property `
    BundleId, Name, `
    @{ Name = 'ComputeType'; Expression = { $_.ComputeType.Name} }, `
    @{ Name = 'RootStorage'; Expression = { $_.RootStorage.Capacity} }, `
    @{ Name = 'UserStorage'; Expression = { $_.UserStorage.Capacity} }, `

Launch WorkSpaces with PowerShell

Once you’ve selected a bundle to deploy, you’re ready to deploy an AWS WorkSpace. The New-WKSWorkspace command is a little different from many other AWS PowerShell commands. Before invoking the command, you need to construct a WorkspaceRequest .NET object, set some properties on it, and then pass that into the New-WKSWorkspace command’s -Workspace parameter.

$WorkSpace = [Amazon.WorkSpaces.Model.WorkspaceRequest]::new()
$WorkSpace.BundleId = '<YourPreferredBundleId>'
$WorkSpace.DirectoryId = '<YourDirectoryId>'
$WorkSpace.UserName = 'trevor'

$Result = New-WKSWorkspace -Workspace $WorkSpace

If you’d like to optionally configure auto-stop for your AWS WorkSpaces, you can specify the WorkspaceProperties property on the WorkspaceRequest object. Here’s what that looks like.

$WorkSpace.WorkspaceProperties = [Amazon.WorkSpaces.Model.WorkspaceProperties]::new()
$WorkSpace.WorkspaceProperties.RunningModeAutoStopTimeoutInMinutes = 60
$WorkSpace.WorkspaceProperties.RunningMode = [Amazon.WorkSpaces.RunningMode]::AUTO_STOP


Now that you understand the fundamentals of provisioning AWS WorkSpaces, you can now incorporate these concepts into your own automation scripts!

NOTE: The code samples in this article include the easily missed backtick character, which is the line continuation character in PowerShell. Be sure that you include this character, and that it is not followed by any whitespace, otherwise the commands will fail.

This article originally appeared on