Convert existing Amazon WorkSpaces to the WorkSpaces Streaming Protocol without a rebuild

With the announcement of the modify Amazon WorkSpaces protocol API, you can convert existing WorkSpaces to the WorkSpaces Streaming Protocol (WSP) without a rebuild. Converting existing WorkSpaces lets you use the recent protocol performance and feature improvements, such as webcam support and smart card authentication.

Previously, changing a WorkSpaces’ protocol from PCoIP to WSP required a rebuild of the WorkSpace. This is highly disruptive to end users and administrators. With the ModifyWorkSpaces API, the conversion does not require rebuilding the WorkSpace. In this post, you learn how to convert an existing WorkSpace to WSP with the API.

Prerequisites

For this walkthrough, you should have the following prerequisites:

• Access to the AWS Management Console or Command Line Interface (AWS CLI) with a WorkSpaces Administrator Identity or equivalent permissions.
• Foundational knowledge of AWS CLI or CloudShell.
• Your WorkSpaces client supports WSP (Windows native client (version 5.4.0 or above), MacOS native client (version 5.5.0 or above), or Web Access).
• An existing PCoIP WorkSpace.
  • Note: If you launch a WSP WorkSpace, you are not able to use the API to convert to PCoIP. The API can only be used on WorkSpaces that were originally PCoIP.
• The IP address and port requirements for WSP are allow listed.
• Ensure your current bundle supports WSP. (As of January 2023, Graphics and Windows 7 bundles are not supported on WSP)
• For the best experience with video conferencing, use a Power bundle or higher.
• The WorkSpace must be in an Available state.
• Make sure your session GPOs have been configured correctly within Active Directory. Customers are able to install and manage Group Policy Administrative templates for PCoIP to control their WorkSpaces PCoIP Group policies. Customers can continue to administer their WSP WorkSpaces policies with new Group Policy Administrative Templates for WSP.

Walkthrough

For this walkthrough, I use CloudShell. If you have a configured AWS CLI version 2.8.13 or higher with the required permissions, use that in the same fashion.

1. Login to CloudShell.
2. Target a PCoIP WorkSpace ID to modify. If you do not know your WorkSpace ID, you can use the aws workspaces describe-workspaces command or find it in the WorkSpaces console.
3. Run modify-workspace-properties command to modify the running WorkSpace protocol to WSP. Replace the WorkSpace ID placeholder (ws-xxxxxxxxx) in the command below and then run the command in your CloudShell or AWS CLI environment.
   • • aws workspaces modify-workspace-properties --workspace-id ws-xxxxxxxxx --workspace-properties "Protocols=[WSP]"
     • Note: [WSP] or [PCOIP] in the command is case sensitive.
4. This API call only returns a response if something goes wrong. If you do not see a response, your targeted WorkSpace begins the modification process. The WorkSpace will go into the Rebooting state while it is modifying the protocol.

Validation

1. Run the aws workspaces describe-workspaces command to view all of the WorkSpace IDs and confirm the WorkSpaces Protocol displays WSP. Or, check the WorkSpaces console.
2. There are a few reboots during the process. Please allow for 20 minutes after the WorkSpace shows Available and is in a healthy state before connecting.
3. You can verify the WSP agent has been installed in Apps and Features once logged into the WorkSpace. You can also confirm the protocol within the WorkSpaces client by selecting Support > About My WorkSpace.
4. When using the API, your WorkSpaces’ bundle name does not change.

Automation

To modify the protocol of several WorkSpaces at once, use the API. Make sure users are not actively using the WorkSpaces as they will be disconnected once the command is issued. To automate this process, create a custom script using the AWS CLI, AWS Tools for PowerShell, or the AWS SDK.

Alternately, you use the open-sourced EUC Toolkit project to have an interactive GUI that initiates the same automation. It is recommended you first test in non-production environments, then convert your WorkSpaces in small batches. If you are planning a large migration, engage your AWS account team for assistance.

Clean-Up

Using this API does not create any resources for you to clean up. If you provisioned a new WorkSpace to follow this blog, you can terminate it to avoid reoccurring charges. If you need to revert the WorkSpaces’ protocol to PCoIP, you can run the same command as above, with “Protocols=[PCOIP]”.

Conclusion

In this post, you successfully modified a WorkSpaces’ protocol from PCoIP to WSP without needing to rebuild the WorkSpace. After you finish your WSP testing in a non-production environment, begin your migration plans to update your production users. WSP continues to evolve as a protocol. Modify your existing WorkSpaces today and give it a try!