Desktop and Application Streaming

Best practices for successful BYOL image creation for Amazon WorkSpaces

Amazon WorkSpaces Family solutions provide the right virtual desktop solution for varied worker types, from any location. Amazon WorkSpaces is a flexible virtual desktop infrastructure (VDI) solution that lets you quickly and easily deploy cloud-based desktops. Amazon WorkSpaces Core is designed to work with third-party VDI solutions, allowing them to utilize WorkSpaces fully managed virtual desktop infrastructure. Both services provide license included Microsoft Windows Server based images, and customers have the choice to bring your own license (BYOL) for Windows desktop OS. These options allow you to create customized desktop environments that fits your organization’s needs regardless of OS type or licensing model.

To be compliant with the Microsoft licensing terms for BYOL, you must bring your own media for the Windows desktop operating system. The BYOL WorkSpaces image creation process begins with importing a clean image of the base operating system you wish to deploy. To ensure a successful BYOL image import, follow the best practices for each stage of the image creation procedure highlighted in this blog. You will only need to import each version of the OS you plan to use once. After that, you can reuse this vanilla Windows 10 or Windows 11 image within the WorkSpaces service to create multiple custom WorkSpaces images.

In this blog post, you will learn recommendations within the four main stages of the BYOL image import process to help ensure success. For each stage, there is a bulleted list of recommendations followed by additional details. This blog assumes that you are familiar with the WorkSpaces BYOL image creation process. Before proceeding, please have read and understood the Bring Your Own Windows desktop licenses section of the WorkSpaces administration guide. The purpose of this article is to help you avoid common issues customers encounter when following the WorkSpaces BYOL image creation process.

Stage 1 – Local Image Preparation

You will start by preparing a clean Windows 10 or Windows 11 virtual machine (VM) image in a local hypervisor. Ensuring the image is as vanilla as possible is crucial to avoid compatibility issues with the WorkSpaces BYOL image import process. Before you being, verify that you meet all the requirements for Bring Your Own Windows desktop licenses and are using a supported version of Windows.

Here are some recommendations during this phase:

  • Use a local VM without internet connectivity.
  • Do not perform an OS upgrade or apply any Windows Updates.
  • Do not install any additional software, this includes drivers or hypervisor tools.
  • Do not join the VM to an Active Directory domain.
  • Use a 70GB virtual hard disk, any larger virtual hard disks will fail the BYOL import.
  • Run the BYOL Checker utility prior to export and fix all warnings.
  • For Windows 10, use a legacy BIOS without Trusted Platform Module (TPM) enabled.
  • For Windows 11, use a UEFI-based firmware with TPM enabled.

To ensure a smooth import, it is essential to keep the local VM operating system as clean as possible. AWS recommends using a local VM without internet connectivity to prevent accidental operating system upgrades during the image preparation phase. You cannot import a version of Windows that has been upgraded from a previous version.

During this stage, do not join the VM to a domain or install any additional software or drivers. This includes the agents or tools used by your local hypervisor. They may introduce unwanted configurations or dependencies that could cause issues during the WorkSpaces image creation process. Installing additional software and agents will be performed after the image import process is complete.

Before exporting the local VM image, remove any modern Windows apps bundled with the OS. Use the Remove-AppxPackage PowerShell cmdlet to remove all of the AppX packages.

The BYOL import process requires a VM with a single volume with a maximum size of 70 GB and at least 20 GB free. Insufficient disk space leads to issues while importing and preparing the image for the WorkSpaces service.

Run the BYOL checker tool provided by Amazon WorkSpaces. This tool prepares the machine for the import process and helps identify and resolve potential compatibility issues. Once all tests in the checker pass, you see a button to Run Sysprep on the VM. Do not run this at this stage. Close the BYOL checker, shutdown the VM, and export an image. Once complete, start the VM, run the BYOL checker and this time choose Run Sysprep. If successful, the image you exported is ready for the next stage. The purpose of running Sysprep at this stage is to catch any issues that will break the later stages of this process. The image you upload to S3 in the following step must not be Sysprepped.

Refer to Steps 3 and 4 in the BYOL section of the WorkSpaces administration guide for additional details.

Stage 2 – Image Import into Amazon EC2

Once you have exported the local VM image, the next step is to upload the image into Amazon Simple Storage Service (S3) and import it into Amazon Elastic Compute Cloud (Amazon EC2).

Here are some recommendations during this phase:

  • For Windows 11, ensure you include the --boot-mode uefi parameter when running the EC2 import-image command.

Windows 11 requires the Unified Extensible Firmware Interface (UEFI) boot mode, Trusted Platform Module (TPM) 2.0, and Secure Boot. Setting the --boot-mode uefi parameter ensures the image imports with the supported configuration. Refer to Step 5 in the BYOL section of the WorkSpaces administration guide and this blog for additional details.

Stage 3 – Create the BYOL base image for WorkSpaces

After the EC2 image import process is successful, you will use the EC2 Amazon Machine Image (AMI) to create your BYOL base image for Amazon WorkSpaces.

Here are some recommendations during this phase:

  • For Amazon WorkSpaces, use the WorkSpaces console or APIs to import the image.
  • For Amazon WorkSpaces Core, use the WorkSpaces API to import the image with the --ingestion-process parameter or using the VDI partner’s import process.
  • Utilize a temporary EC2 instance to troubleshoot ingestion issues.

If you are using Amazon WorkSpaces, follow the procedure in Step 6: Create a BYOL image using the WorkSpaces console in the administration guide. This will create a base BYOL image for WorkSpaces from the EC2 AMI. This step is completed in the WorkSpaces console, or using the import image API.

If you are using Amazon WorkSpaces Core, follow your partner VDI solution’s guidance. Some VDI vendors handle importing the AMI from EC2 into WorkSpaces Core for you. Others require you to import it yourself. The WorkSpaces console does not support WorkSpaces Core image imports. Images for WorkSpaces Core are imported and flagged as bring your own protocol (BYOP) using the AWS Command Line Interface (CLI).

Here is an example of using the CLI to import a WorkSpaces image from an EC2 AMI for use with WorkSpaces Core. You must include the ingestion process parameter and value for your image type.

aws workspaces import-workspace-image --ec2-image-id ami-xxxxxxxxxx --ingestion-process BYOL_REGULAR_BYOP --image-name win10-ent-img01 --image-description “Windows 10 Enterprise” --region aws-region-id

Occasionally the import from EC2 into WorkSpaces fails and the image appears in the Error state within the WorkSpaces console. If the failure is for a known issue, the reason is displayed on the details page for the image. If the failure is due to an unknown cause, contact AWS Support for a deeper review of the import logs.

While troubleshooting, it is helpful to deploy an EC2 instance from the AMI. Once running, connect to the instance and rerun the BYOL Checker. Resolve any findings and create a new AMI from the instance, then retry the WorkSpaces ingestion process with this new AMI.

Stage 4 – WorkSpaces Image Customization

Once you have created a BYOL image for Amazon WorkSpaces, you will deploy that base image to WorkSpace, and apply the final image customizations. This fully customized image will be used to deploy virtual desktops to your end-users.

Here are some recommendations during this phase:

  • Use a dedicated AD Connector for image creation.
  • Use a dedicated OU in Active Directory for image creation.
  • Use a service or dedicated user AD account for image creation.
  • Exclude the management network interface (ETH0) from any security or networking tools.
  • Do not modify the Windows default system unattend.xml files.
  • Run the WorkSpaces Image Checker prior to creating the image and fix all warnings.

To keep the image as clean as possible and avoid image capture issues, use a dedicated AD Connector and Organizational Unit (OU). This OU should have no Group Policy Objects (GPOs) linked and policy inheritance blocked.

Use a dedicated directory account for image creation and customization to prevent issues arising from user-specific configurations or settings. For software agents and applications that require generalization which is not handled by Sysprep, ensure you handle that prior to image capture.

Each WorkSpace has two network interfaces attached to it. The first interface (ETH0) is how the WorkSpaces service manages and communicates with the instance. Avoid modifying the routing on this interface and exclude it from antivirus or security tools, as this will cause connectivity and management issues. Refer to the administration guide for additional information on the management interface ports.

Do not modify the Windows default system unattend file during the image customization process (%WINDIR%\panther and %WINDIR%\panther\unattend). Changes to these result in unexpected behavior after deploying additional WorkSpaces from your image. Note that tools such as the Microsoft Deployment Toolkit (MDT) or other deployment technologies may modify this file and result in image creation errors.

Run the Image Checker to confirm that your Windows WorkSpace meets the requirements for image creation. Similar to the BYOL Checker, this tool performs a series of tests to detect common issues that break the image creation process. It provides guidance on how to resolve any findings. If any issues are found, resolve them and rerun the Image Checker. Do not proceed with creating your WorkSpaces image until all tests pass and you see the Validation Successful message.

See the WorkSpaces administration guide for additional recommendations and best practices for creating a custom WorkSpaces image.

Conclusion

Adhering to these best practices will increase the rate of a successful BYOL image import on Amazon WorkSpaces. By following the best practices for each stage—local image preparation, importing into Amazon EC2, WorkSpaces base image import, and final customization—you ensure a smooth process. Following these guidelines will save you time and effort while ensuring a smooth deployment experience. For additional information on the BYOL image process, please refer to the WorkSpaces Administration Guide on Bring Your Own Windows licenses. If you find watching a video on the BYOL process helpful, then please see the AWS EUC videos on the official AWS YouTube channel.

Justin Grego is a Senior End User Computing Specialist Solutions Architect. As part of the EUC Service Aligned SA Team, he helps enable both customers and fellow SAs get up to speed on and be successful with new AWS EUC features and services.