Amazon WorkSpaces Personal Playbook

41 minute read

Content level: Advanced

The purpose of this article is to offer general guidance on how to troubleshoot the common issues related to Amazon WorkSpaces and its support scope. In this article we cover troubleshooting issues related to, WorkSpaces login and access issue, SAML authentication, custom image creation failure and workSpaces creation issues.

1. Amazon WorkSpaces Playbook

2. WorkSpaces Personal and WorkSpaces Pools

3. Scope of AWS Premium Support

4. Case Severity

5. Troubleshooting Common WorkSpaces Issues

5.1: Unable to connect WorkSpaces Personal using WorkSpaces client

My users can't connect to a WorkSpaces

I can't use SAML 2.0 authentication to log in to my Amazon WorkSpaces

Directory Unavailable

Unable to register. This device is not authorized to access the WorkSpaces

5.2: Unable to create custom image

Failure to create AWS WorkSpace Image

Windows WorkSpaces image creation fails

Linux WorkSpaces image creation fails

WorkSpaces BYOL image

5.3: Unable to create WorkSpaces Personal

common reasons and troubleshooting steps for WorkSpaces creation failures

Domain Join issue

6. Additional Information

7. Conclusion

8. Related Resources

Amazon WorkSpaces Playbook

In this playbook we cover troubleshooting issues related to, WorkSpaces login and access issue, SAML authentication issues, customer image creation failure issues and unable to create WorkSpaces issues. It also explains how to open cases with AWS technical support and what details to provide for a faster and better support from AWS.

Amazon WorkSpaces enables you to provision virtual, cloud-based Microsoft Windows, Amazon Linux 2, Ubuntu Linux, or Red Hat Enterprise Linux desktops for your users, known as WorkSpaces. WorkSpaces eliminates the need to procure and deploy hardware or install complex software. You can quickly add or remove users as your needs change. Users can access their virtual desktops from multiple devices or web browsers.

WorkSpaces Personal and WorkSpaces Pools

Amazon WorkSpaces allows you to create the following 2 types of WorkSpaces, depending on your organization and user needs.

WorkSpaces Personal - WorkSpaces Personal offer persistent virtual desktops, tailored for users who need a highly-personalized desktop provisioned for their exclusive use, similar to a physical desktop computer assigned to an individual. For more information, see Create a WorkSpace in WorkSpaces Personal.

Each WorkSpace is associated with a virtual private cloud (VPC), and a directory to store and manage information for your WorkSpaces and users. For more information, see Configure a VPC for WorkSpaces Personal.

WorkSpaces uses a directory to store and manage information for your WorkSpaces and users. You can use one of the following options:

AD Connector — Use your existing on-premises Microsoft Active Directory. Users can sign into their WorkSpaces using their on-premises credentials and access on-premises resources from their WorkSpaces.

AWS Managed Microsoft AD — Create a Microsoft Active Directory hosted on AWS.

Simple AD — Create a directory that is compatible with Microsoft Active Directory, powered by Samba 4, and hosted on AWS.

Cross trust — Create a trust relationship between your AWS Managed Microsoft AD directory and your on-premises domain.

Microsoft Entra ID — Create a directory that uses Microsoft Entra ID as its identity source (through IAM Identity Center). Personal WorkSpaces in the directory are joined using Microsoft Entra's native authentication and are enrolled into Microsoft Intune through Microsoft Windows Autopilot user-driven mode. Directories using Microsoft Entra ID only support Windows 10 and 11 Bring Your Own Licenses WorkSpaces.

Custom — Create a directory that use an identity provider of your choice (through IAM Identity Center). WorkSpaces in the directory are managed using the device management solution of your choice such as JumpCloud. Directories using custom identity providers only support Windows 10 and 11 Bring Your Own Licenses WorkSpaces.

WorkSpaces Pool - WorkSpaces Pool offer non-persistent virtual desktops, tailored for users who need access to highly-curated desktop environments hosted on ephemeral infrastructure. For more information, see Administer WorkSpaces Pools.

Scope of AWS Premium Support

AWS Support offers assistance on technical issues and additional guidance to customers to operate their infrastructures in the AWS cloud. AWS Support provides a mix of tools and technology, people, and programs designed to proactively help you optimize performance, lower costs, innovate faster, and focus on solving some of the toughest challenges that hold you back in your cloud journey. There are four types of support plans available: Developer, Business, Enterprise On-Ramp, and Enterprise.

For more details, see Compare AWS Support Plans , AWS Support Plan Pricing and Creating support cases, case management.

Case Severity

Enter image description here

Troubleshooting Common WorkSpaces Issues:

When troubleshooting WorkSpaces issues, it is necessary to gather the log bundle from the affected WorkSpace and the host where the WorkSpaces client is installed. To help troubleshoot issues that your users might experience, you can enable advanced logging on any Amazon WorkSpaces client and advanced logging generates log files that contain diagnostic information and debugging-level details, including verbose performance data.

There are two fundamental categories of logs:

Server-side logs: The WorkSpace is the server in this scenario, so these are logs that live on the WorkSpace itself.
Client-side logs: Logs on the device that the end user is using to connect to the WorkSpace.
Only Windows, Linux and macOS clients write logs locally.
Zero clients and iOS clients do not log.
Android logs are encrypted on the local storage and uploaded automatically to the WorkSpaces client engineering team. Only that team can review the logs for Android devices.

For more information, refer Collecting a WorkSpaces support log bundle for debugging.

5.1: Unable to connect WorkSpaces Personal using WorkSpaces client

The WorkSpaces client depends on special services and network settings. When the client fails to load the WorkSpaces, it's typically because a service or setting is incorrectly configured or unavailable.

The following information describes common errors, the cause of these errors, and troubleshooting guidance to resolve the errors.

My users can't connect to a WorkSpaces

My users receive the following error when they try to connect to their Windows WorkSpaces:

"An error occurred while launching your WorkSpaces. Please try again."

This error typically indicate that the any of the following services namely, SkyLightWorkSpacesConfigService, PCoIP Standard Agent for Windows , WSP Adapter for DCV and DCV Server service is not responding to the health checks.

Note:

Windows WorkSpaces: First, reboot the WorkSpace from the WorkSpaces console. If a reboot doesn't resolve the issue, then use Remote Desktop Protocol (RDP) to connect to the WorkSpace. If you can connect to the WorkSpace with RDP, then proceed to the next troubleshooting section.

If you can’t connect to the WorkSpace with RDP, then troubleshoot connection issues between RDP and the Amazon Elastic Cloud Compute (Amazon EC2) instance. After you troubleshoot instance issues, if you still can’t connect to the WorkSpace with RDP, then complete the following steps:

Restore the WorkSpace to roll back to the latest snapshot.
If the WorkSpace is still unhealthy, then rebuild the WorkSpace.

Linux WorkSpaces: Reboot the WorkSpace. If a reboot doesn't resolve the issue, then use SSH to connect to the WorkSpace. SSH is disabled by default on Ubuntu and RHEL WorkSpaces. If you can SSH to the WorkSpace, then proceed to the next troubleshooting section. If you can’t connect to WorkSpace with SSH, then see the Restore or rebuild the WorkSpace section.

1.1 To resolve the accessibility issue, check the status of the WorkSpace on the WorkSpaces console. If it shows Rebooting or Starting for a long time and then eventually WorkSpace status will change to Unhealthy. If the WorkSpace status shows unhealthy, then RDP to WorkSpace or SSH to Linux based WorkSpace to verify the following settings for the below services:

SkylightWorkSpacesConfigService
PCoIP Standard Agent for Windows
STXHD Hosted Application Service
DCV Server
WSP Adapter for DCV

They're running.
They're set to start automatically.
They can communicate over the management interface (eth0).
They aren't blocked by any third-party antivirus software.
The OS firewall or group policy settings are not blocking communication on the management interface.

Windows based WorkSpaces

To verify that the above services meet the preceding requirements, follow these steps:

Connect to the WorkSpaces with RDP.
Go to run and type ‘services.msc’
Validate that following services are running and Startup Type is set to Automatic.

For PCoIP based WorkSpaces

   SkyLightWorkSpacesConfigService
   PCoIP Standard Agent for Windows
   STXHD Hosted Application Service

For WSP based WorkSpaces.

   SkyLightWorkSpacesConfigService
   DCV Server
   WSP Adapter for DCV

Start the service if they are in stopped state.

Linux based WorkSpaces

To verify that the required WorkSpaces services are started at the OS level, complete the following steps:

Connect to the WorkSpaces using SSH. Please note SSH is disabled by default.
Open Terminal.
Check the status of the required agents in the WorkSpaces.

For Amazon Linux WorkSpaces, run the following commands:

sudo systemctl status pcoip.service
sudo systemctl status skylight-agent.service

For an Ubuntu or RHEL WorkSpaces, run the following commands:

sudo systemctl status skylight-agent.service. 
sudo systemctl status wspdcvhostadapter.service
sudo systemctl status dcvserver.service

If the status is Stopped, then to start the service, run the following command:

sudo systemctl start service-name

Note: Replace service-name with the stopped service name.

1.2 If any of the above services are missing for the respective WorkSpaces, see the below steps:

Reboot the WorkSpaces from the Amazon WorkSpaces console to reinstall it automatically.
Once WorkSpaces become available, RDP/SSH to the WorkSpaces and validate if the missing services got installed on the WorkSpaces.

1.3 You might also receive this error on the Amazon WorkSpaces client after a long delay if the WorkSpaces security group was modified to restrict outbound traffic. Restricting outbound traffic prevents Windows from communicating with your domain controllers for authentication and other domain related requests.

1.4 Verify that your security groups allow your WorkSpaces to communicate with your directory controllers on all required ports over the primary network interface.

Check the network adapters

Complete the following steps:

1.5 Verify that both the management and customer interfaces are running. To show the management and customer interfaces, run the following command:

For Windows: netsh interface show interface
For Linux: sudo ip link show

To identify the management and customer IP addresses, run the following command:

For Windows: ipconfig /all 
For Linux: sudo ifconfig

If an interface isn't running, then activate the interface.

For Windows, run the following command: netsh interface set interface "<ethernet-name>" enable
For Linux, run the following command: sudo ifconfig ethernet-name up

Note: Replace ethernet-name with your ethernet name.

Important: If ETH1 is disabled, then you must rebuild the WorkSpaces.

1.6 Another cause of this error is related to the User Rights Assignment Group Policy. If the following group policy is incorrectly configured, it prevents users from being able to access their Windows WorkSpaces:

Computer Configuration\Windows Settings\Security Settings\Local Policies\User Rights Assignment

Incorrect policy:
- Policy: Access this computer from the network
- Setting: Domain name\Domain Computers
Correct policy:
- Policy: Access this computer from the network
- Setting: Domain name\Domain Users

Note: This policy setting should be applied to Domain Users instead of Domain Computers.

1.7 If antivirus software is installed on the WorkSpaces, make sure it does not interfere with the required service components installed in the following locations for respective operating systems:

For Windowsbased WorkSpaces refer to Required service components for Windows

ForLinux based WorkSpaces refer to Required service components for Linux

For Ubuntu based WorkSpaces refer to Required service components for Ubuntu

For Red Hat Enterprise Linuxbased WorkSpaces refer to Required service components for Red Hat Enterprise Linux

1.8 This error would also happen if you change the username of an Active Directory user, due to this, the usernames in WorkSpaces and Active Directory don't match and authentication fails. If you changed the sAMAccountName value, then return it to the original username.

1.9 This error would also happen if you deleted the Active Directory user and created a new user with same sAMAccountName, then you must create a new WorkSpace for that user.

1.10 This error would also happen if the active directory user object has been deleted from the domain. A solution to that issue would be restore the AD user before the tombstone lifetime which is by default 180 days for AWS Managed Microsoft AD, basically it keeps items in the AD Recycle Bin for 180 days before they become a Recycled-Object.

For more information about AD recycle bin and restoring AD objects, see Microsoft articles AD Recycle Bin and Restore-ADObject.

Please note, restore AD object option is not available with the Simple AD Directory as active directory administrative center and PowerShell are not supported . In such case, you would need to create a new WorkSpaces for the user.

Refer the article for more information for troubleshooting authentication issues while accessing the WorkSpace Personal using WorkSpaces client.

1.11 This error can also occur when WorkSpaces is in unhealthy state. The WorkSpaces service periodically checks the health of a WorkSpaces by sending the WorkSpaces a status request. A WorkSpaces is marked as unhealthy if the WorkSpaces service doesn't receive a response in a timely manner. For more information about troubleshooting unhealthy WorkSpaces, see How do I troubleshoot a Linux WorkSpace that's in the Unhealthy state and How do I troubleshoot a Windows WorkSpace that's marked as unhealthy. Additionally, You can also use AWSSupport-RecoverWorkSpace AWS Systems Manager automation runbook to recover an unhealthy WorkSpace.

I can't use SAML 2.0 authentication to log in to my Amazon WorkSpaces.

2.1 This error typically occurs due to misconfiguration with the SAML assertion for your federation.

2.2 Before you troubleshoot SAML 2.0 authentication issues, make sure that the aren’t any Service Control Policies (SCPs) blocking the WorkSpaces:Stream API. For information about how to troubleshoot SCP issues, see Access denied error message examples.

2.3 To troubleshoot SAML 2.0 authentication issues, refer the error & review the relevant troubleshooting steps for error that you encounter:

My users receive the message, "Something went wrong: An error occurred while launching your WorkSpaces" when they attempt to sign in to the WorkSpaces client application after federating to the IdP

My users receive the message, "Unable to validate tags” when they attempt to sign in to the WorkSpaces client application after federating to the IdP.

My users are getting disconnected from their WorkSpace session every 60 minutes

Error: Your request included an invalid SAML response. To logout, click here.

Error: Not authorized to perform sts:AssumeRoleWithSAML (service: AWSSecurityTokenService; status code: 403; error code: AccessDenied).

If you complete the preceding troubleshooting steps and still encounter authentication issues, then complete the following steps.

Review the SAML 2.0 assertions for your federation.
Check your SAML 2.0 response from the browser, see View a SAML response in your browser.
Analyze your SAML 2.0 response and refer the document Setting Up SAML for more information.
Correct IAM role with required policies and trust permissions as mentioned in the Setting up SAML 2.0

For more information about troubleshooting SAML federation with IAM, see Troubleshoot SAML federation with IAM and Troubleshoot SAML Authentication Issues.

Directory Unavailable

When I use the Amazon WorkSpaces client to log in, I receive the following error message: "Directory Unavailable: Your directory could not be reached at this time. Please contact your Administrator for more details."

Directory Unavailable error typically occurs due to following common causes:

First, verify that your WorkSpaces directory is in the Active state, if AWS Directory is Inoperable, Impaired or failed state you would observe the Directory Unavailable errors with the WorkSpaces client.
MFA configuration issues can cause Directory Unavailable errors when the directory is available.
To troubleshoot this error, confirm that your RADIUS server is running. Also, review the logs to confirm that authentication traffic is being sent to its destination.
A Directory Unavailable error can occur when your configured RADIUS server isn't running. This error can also occur when network modifications don't allow the RADIUS server to communicate with your domain controllers that use WorkSpaces.
If you use an AD Connector, then your AD Connector's networking configuration must allow outbound access to your domain controllers and your RADIUS server. Use Amazon Virtual Private Cloud (Amazon VPC) Flow Logs to confirm that all necessary traffic is sent to its destination.
To confirm that you can log in without MFA turned on, temporarily turn off MFA on the registered directory. If you can log in after you turn off MFA, then the issue is related to the RADIUS server configuration.

Unable to register. This device is not authorized to access the WorkSpaces.

The below are the possible causes which can cause this issue.

IP access control groups are configured on your WorkSpaces directory, but the client’s public IP address isn't on an allow list.
Trusted device-based access is turned on in the directory, and the certificate is missing on the client device, isn't valid, or isn't meeting security requirements.
Device access is turned off in the WorkSpaces directory.

4.1 Check the settings in your directory. If the IP access control group is turned on, then confirm that the public IP address the user is connecting from allows access to the WorkSpaces.

4.2 If the trusted device setting is turned on under Access Control Options and displays Valid, then make sure that you have the correct leaf, intermediate (optional), and root certificates installed on the client machine.

4.3 Make sure that the client device that you're accessing the WorkSpaces from is allowed under Access Control Options. By default, WorkSpaces Web Access and Linux clients are turned off.

5.2: Unable to create custom image

A custom image contains only the OS, software, and settings for the WorkSpace.

After you create a custom image, you can build a custom bundle that combines the custom image and the underlying compute and storage configuration that you select. You can then specify this custom bundle when you launch new WorkSpaces to ensure that the new WorkSpaces have the same consistent configuration (hardware and software).

For more information, refer the article How do I create a WorkSpaces image.

Failure to create AWS WorkSpace Image

Note:

Image creation on encrypted workspace is currently not supported.
For Windows workspaces, run the image checker and ensure that there are no failures before proceeding with image creation. See Run the Image Checker. If Image Checker fails, see the Tips for resolving issues detected by the Image Checker section.
New line (/) character in image description is not supported.
The image description must be a single line. WorkSpaces doesn’t support multi-line image descriptions for image creation.
To create the bundle with same name , you need to ensure to wait at least 2 hours after deleting a bundle before creating a new bundle with the same name.

Review the following common causes and steps to troubleshoot WorkSpaces image creation issues.

1. Quota reached for WorkSpace images in a Region

There's a default limit of 40 WorkSpace images in each AWS Region. If you reached this limit, then new attempts to create an image fail. For information about how to request a limit increase, see Amazon WorkSpaces quotas. You observe below error on the AWS Workspace console if your image limit is exhausted.

Console Error:

Limit Exceeded error:
"You have reached your WorkSpace Image limit. 
Please contact the AWS Support Team on the community forums 
and via AWS Premium Support at: https://us-east-1.console.aws.amazon.com/support/home."

You can also verify the error from the CloudTrail event logs for API CreateWorkspaceImage.

CloudTrail Error:

"errorMessage": "You have reached the maximum number of WorkSpace images that can be created in the destination Region for this AWS account. Delete unused images in the destination Region, and try again.

2. Encrypted WorkSpace:

Image creation from an encrypted WorkSpace is currently not supported for both Windows and Linux Workspaces. If you try to create an Image of an encrypted workspaces, You would see the below error on the console.

Console Error:

Operation is not supported. The selected WorkSpace may have one or more of its volumes encrypted, it may have managed applications, or the operating system may no longer be supported. Please select a WorkSpace with no volumes encrypted, no managed applications, or a WorkSpace with a supported operating system to create the image.

You see the below error in CloudTrail while creating an Image from an encrypted WorkSpace.

CloudTrail Error:

"errorCode": "OperationNotSupportedException"
"errorMessage": "The operation couldn't be performed on the specified WorkSpace. Confirm that the WorkSpace is not encrypted and try again."

Windows WorkSpaces image creation fails

3.Troubleshooting common issues related to Image creation:

Below are some possible common issues which can cause an image creation to fail.

Creation failed due to multiple user profiles.
User Profile path is incorrect
User Profile size is huge
Profile path for any of the folders name is greater than 256 characters
Services running under domain account
Insufficient free space in C:
Outdated EC2Launch v1 and EC2Launch v2 version
Duplicate RDP certificates
WinRM is disabled
PowerShell execution is blocked on workspace

Note: For Windows workspaces, run the image checker and ensure that there are no failures before proceeding with image creation. See Run the Image Checker. If Image Checker fails, see the Tips for resolving issues detected by the Image Checker

If image creation still fails in your Windows WorkSpace, then take one or more of the following actions.

3.1 Check your configuration

If you’re running an antivirus or security agent on your WorkSpace, then turn it off during image creation. If your application service (services.msc) uses a domain account, then change the service account to Local System, Local Service, or Network Service.

3.2 Check that the PowerShell execution policy in the WorkSpace allows RemoteSigned scripts. To verify the value, run the following PowerShell command:

Get-ExecutionPolicy

If the output isn’t Unrestricted or RemoteSigned, then run the following command:

Set-ExecutionPolicy –ExecutionPolicy RemoteSigned

The preceding setting lets you run scripts on WorkSpaces, and is required to create an image.

3.3 Check that you have the following required components in the WorkSpace:

Windows PowerShell version 3.0 or later
Remote Desktop Services
AWS PV drivers
Windows Remote Management (WinRM)
Teradici PCoIP agents or WSP agents and drivers
STXHD agents and drivers
AWS and WorkSpaces certificates
Skylight Agent

3.4 The WorkSpace that you create an image from must not be assigned to a user within a Domain Guests group. To verify if there are any domain accounts, run the following command:

Get-WmiObject -Class Win32_Service | Where-Object { $_.StartName -like "*$env:USERDOMAIN*" }

3.5 Make sure workspace have enough free space

Keep your user profile size under 10 GB. Verify that the WorkSpace has only the user profile data that's required as part of the image. Also, verify that C:\ has free space equal to at least the user profile size plus 2 GB. For example, if the user profile size is 10 GB, then C:\ must have at least 12 GB of free space.

3.6 Check for pending updates

To prevent interruptions in the image creation process due to Windows updates, check that WorkSpaces has the latest patches. WorkSpaces image creation can fail if Windows updates are missing or if the WorkSpace isn't updated with the latest patches.

Also, check if there's a pending reboot for Windows Update. The image creation process fails when a reboot is pending.

3.7 Make sure there is only one user profile present in the workspace. .

To Find SID of All Users , you can run below PowerShell command and note the **SID **of the workspace username.


Get-WmiObject win32_useraccount | Select domain,name,sid

Next, you can run below PowerShell command to list the user profiles that don’t not match the actual workspace user profile path and isn't C:\Users\setup or a SYSTEM user

$profile=(Get-WmiObject -Class Win32_UserProfile -ComputerName Localhost -Filter "SID='ENTER USER SID HERE'").LocalPath
(Get-WmiObject win32_userprofile | Where-Object { $_.Sid -match "S-1-5-\d{2}-" -and ` $_.LocalPath -ne "$profile" -and $_.LocalPath -ne "C:\Users\setup" -and $_.Sid -notLike "*-500"}).LocalPath

3.8 During imaging, user profile gets copied and it may fail if the path for any of the folders within the user profile is longer than 260 characters.

3.9 For Windows WorkSpaces, don't configure any Group Policy Objects (GPOs) before image creation. For Windows WorkSpaces, do not customize the default user profile (C:\Users\Default) before creating an image. GPOs can be easily modified or rolled back, and are therefore less prone to error than customizations made to the default user profile.

3.10 Ensure you update the EC2Launch, and EC2Launch V2 agents to the latest versions periodically before creating an image. For more information, see Update EC2Launch and EC2Launch V2.

3.11 Ensure you update networking dependency drivers like ENA, NVMe, and PV drivers on your WorkSpaces. You should do this at least once every 6 months. For more information, see Install or upgrade Elastic Network Adapter (ENA) driver, AWS NVMe drivers for Windows instances, and Upgrade PV drivers on Windows instances.

3.12 The another cause for image creation failure could be the below group policy . This policy is responsible for creating Remote desktop certificates which breaks the WorkSpaces image creation process. For image creation, this value should be in disabled state.


Path : Computer Configuration\Administrative Templates\Windows Components/Remote Desktop Services/Remote Desktop Session Host/Security
Policy Setting: Server authentication certificate template

To verify if there any another certificates created by group policy, you can run below PowerShell command to ensure that value for both the command have same thumbprint value.

(Get-CimInstance -Namespace "root\CIMV2\TerminalServices" -ClassName Win32_TSGeneralSetting -Filter "TerminalName='RDP-Tcp'").SSLCertificateSHA1Hash
Get-ChildItem 'Cert:\LocalMachine\Remote Desktop'

If the thumbprint value for both the commands are showing different, then it mostly be a group policy which is creating the remote desktop certificates . To resolve this, ensure the above group policy is excluded from the source workspaces from which is you are creating an image.

3.13 If you still can't create a WorkSpaces image, then check the following troubleshooting steps:

If your WorkSpace has a firewall turned on, then verify that the firewall isn't blocking any necessary ports. WorkSpaces requires certain ports to download scripts used for image creation. The firewall must allow listed traffic on the management network interface. Also, verify that the operating system (OS) Firewall or a third-party firewall have rules to allow the required ports.
Reboot the WorkSpace to check that all AWS components are running updated versions.
To verify that the WSMan service is started and configured for automatic startup, run the Test-WSMan command.
Verify that the applications installed are Sysprep compatible.
Metadata (http://169.254.269.254) should be accessible in the workspace. Make sure the access is not blocked. Outbound TCP on port 80, as defined in Management interface IP ranges, to IP address 169.254.169.254 for access to the EC2 metadata service. Any HTTP proxy assigned to your WorkSpaces must also exclude 169.254.169.254.

Linux WorkSpaces image creation fails

4. If Linux workspace image creation fails, then complete the following steps:

4.1 Image creation on encrypted workspace is currently not supported.

4.2 Check that the status of the WorkSpace is Available and its modification state is None.

4.3 You must install all applications included in the image outside of the user volume (the /home directory). For more information, see What's included with Linux WorkSpace custom images.

4.4 Check that the root volume (/) is less than 97% full.

4.5 Check that you have the following required image components:

Cloud-init
For a PCoIP WorkSpace: Teradici PCoIP agents and drivers 
For a WorkSpaces Streaming Protocol (WSP) WorkSpace: WSP DCV Host Adapter and Nice DCV server
Skylight Agent

4.6 If you want to use smart cards on Linux WorkSpaces with WorkSpaces Streaming Protocol (WSP) enabled, see Use smart cards for authentication in WorkSpaces Personal for the customizations that you must make to your Linux WorkSpace before creating your image.

4.7 For Linux WorkSpaces, see also the "Best Practices to Prepare Your Amazon WorkSpaces for Linux Images“ whitepaper.

4.8 Metadata (http://169.254.269.254) should be accessible in the workspace. Make sure the access is not blocked. Connectivity can be tested via command curl -v http://169.254.169.254 .

WorkSpaces BYOL image

If your licensing agreement with Microsoft allows it, you can bring and deploy your Windows 10 or 11 desktop on your WorkSpaces. To do this, you must enable Bring Your Own License (BYOL) and provide a Windows 10 or 11 license that meets the requirements. For more information refer the document for BYOL image creation.

Windows versions supported for BYOL Your VM must run one of the following Windows versions:

Windows 10 Version 22H2 (November 2022 Update)
Windows 10 Enterprise LTSC 2019 (1809)
Windows 10 Enterprise LTSC 2021 (21H2)
Windows 11 Enterprise 23H2 (October 2023 release)
Windows 11 Enterprise 22H2 (October 2022 release)

All supported OS versions support all of the compute types available in the AWS Region where you're using WorkSpaces. Versions of Windows that are no longer supported by Microsoft are not guaranteed to work and are not supported by AWS Support.

Note:

You can’t create WorkSpaces images on Windows 10 systems that you upgraded from one version of Windows 10 to a newer version of Windows 10. This includes the Windows 10 feature and version upgrades. However, Windows cumulative or security updates are supported by the WorkSpaces image-creation process.
You can’t use Bring Your Own License model (BYOL) for Linux WorkSpaces.
Windows 10 N and Windows 11 N versions are not supported for BYOL at this time.

Troubleshooting common issues related to BYOL Image creation:

1. Check your configurations

Make sure that your virtual machine (VM) runs a supported Windows version.

Connect to the VM in the on-premises environment. To verify that your image meets all requirements, download and run the BYOL Checker PowerShell script. The script provides a detailed report of issues that you must correct before image creation and generates two log files: BYOLPrevalidationlogYYYY-MM-DD_HHmmss.txt and ImageInfo.text. You can find these files in the directory that contains the BYOL Checker script files. To troubleshoot common BYOL image creation errors, see List of error messages and error fixes.

Important: All BYOL Checker script tests must pass for the WorkSpaces image validation to succeed.

The source machine must have English (United States) as the primary language for the Windows operating system. To check the current language, run the following PowerShell command:

Get-WinSystemLocale

If your imported BYOL image has a firewall, then use the VM to check that the firewall isn't blocking any required ports.

Before you import the VM into Amazon Elastic Compute Cloud (Amazon EC2), check that your configuration adheres to the VM import and export requirements. Make sure that the disk that you use to import the VM isn't encrypted. Also, make sure that your VM volume size adheres to the BYOL size restrictions. If you plan to use Microsoft Office for your BYOL image, then you must adhere to additional requirements for your VM.

2. Check that your VM is compatible with Sysprep

All applications installed on your source VM must be compatible with Sysprep. If Sysprep fails and you receive the "One or more AppX package are in a staged state" error, then image creation fails. To list all installed AppX packages, run the following PowerShell command:

Get-AppxPackage -AllUsers | Format-List -Property PackageFullName,PackageUserInformation

All users must have Modern AppX Packages uninstalled. For more information , see Sysprep fails after you remove or update Microsoft Store apps that include built-in Windows images on the Microsoft website.

To remove the AppX Packages, complete the following steps:

In the Windows search box, enter PowerShell. Choose Run as Administrator. For Do you want to allow this app to make changes to your device?, choose Yes. To list all staged AppX packages, run the following PowerShell commands. Note: Press **Enter ** after you enter each command.

$workSpaceUserName = $env:username

$allAppxPackages = Get-AppxPackage -AllUsers

$packages = $allAppxPackages |    Where-Object { `                                (($_.PackageUserInformation -like "*S-1-5-18*" -and !($_.PackageUserInformation -like "*$workSpaceUserName*")) -and `
                                ($_.PackageUserInformation -like "*Staged*" -or $_.PackageUserInformation -like "*Installed*")) -or `
                                ((!($_.PackageUserInformation -like "*S-1-5-18*") -and $_.PackageUserInformation -like "*$workSpaceUserName*") -and `
                                $_.PackageUserInformation -like "*Staged*")
                                }

To remove all staged AppX packages, enter the following command, and then press Enter:

$packages | Remove-AppxPackage -ErrorAction SilentlyContinue

To verify your checks, run the BYOL Checker on the source VM. If the verification fails, then to remove all AppX packages, enter the following commands. Note: Press Enterafter you enter each command.

Get-AppxProvisionedPackage -Online | Remove-AppxProvisionedPackage -Online -ErrorAction SilentlyContinue

Get-AppxPackage -AllUsers | Remove-AppxPackage -ErrorAction SilentlyContinue

3. Check your IAM permissions

After you create the image, make sure that you have the necessary AWS Identity and Access Management (IAM) permissions to import the image. Make sure that the launch permissions on the Amazon EC2 image aren't restricted. The image must be shareable throughout the BYOL image creation process.

4. Check the ingestion process (AWS CLI only)

If image creation fails when you use the AWS Command Line Interface (AWS CLI) to create an image, then verify the image ingestion process. The ingestion process must match the protocol that you use for WorkSpaces.

Note: If you receive errors when you run AWS CLI commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.<br>

5.3: Unable to create WorkSpaces Personal

The creation of a WorkSpaces personal using either Amazon-provided images or custom images can fail due to multiple reasons.

For Amazon Linux WorkSpaces, there are some known limitations for user names are:

Can contain a maximum of 20 characters
Can contain letters, spaces, and numbers that are representable in UTF-8
Can include the following special characters: _.-#
Cannot begin with a dash symbol (-) or at symbol (@) as the first character of the user name.
Ubuntu WorkSpaces are only configure with WSP Protocol
Red Hat Enterprise Linux 8 are only configure with WSP Protocol.
Amazon Linux 2 are only configure with PCOIP Protocol.
These limitations do not apply to Windows WorkSpaces personal. Windows WorkSpaces personal support the (@) and (-) symbols for all characters in the user name.

common reasons and troubleshooting steps for WorkSpaces creation failures:

1. Insufficient permissions

The IAM policy doesn’t exist or is not valid. By default, AWS Identity and Access Management (IAM) identities (users, groups, and roles)don't have permissions for WorkSpaces resources and operations. For more information, see Identity and access management for WorkSpaces.

You can also verify the error from the CloudTrail event logs for API CreateWorkspaces

CloudTrail Error:

"errorMessage": "An error occurred (AccessDeniedException) when calling the CreateWorkspaces operation"

2. WorkSpaces with encrypted volumes permissions

You can use AWS Key Management Service (AWS KMS) keys to encrypt the storage volume of a WorkSpaces. If the WorkSpaces creation fails, then you might not have the required permissions for AWS KMS.

Verify that your IAM role has the required permissions and that you meet the prerequisites to use an AWS KMS key to encrypt your WorkSpaces. For more information, see Encrypted WorkSpaces in WorkSpaces Personal.

You can also verify the error from the CloudTrail event logs for API CreateWorkspaces

CloudTrail Error:

"errorMessage": "An error occurred (AccessDeniedException) user arn is not authorized to perform kms:ListAliases"

3. WorkSpaces quotas

You might have reached the quota to create WorkSpaces in a specific AWS Region on your account. For more information about quotas and how to request an increase, see Amazon WorkSpaces quotas.

4. Antivirus software

Antivirus software might cause failures if you created a WorkSpaces from a custom image. Deactivate or Verify that endpoint protection software, such as antivirus or anti-malware software, explicitly allows the WorkSpaces service components. Then, try to create a new personal WorkSpaces.

On Windows WorkSpaces, the service components are installed in the following locations. Do not delete, change, block, or quarantine these objects. If you do so, the WorkSpace will not function correctly.

On Amazon Linux WorkSpaces, the service components are installed in the following locations.

On Ubuntu WorkSpaces, the service components are installed in the following locations.

On Red Hat Enterprise Linux WorkSpaces, the service components are installed in the following locations. Do not delete, change, block, or quarantine these objects. If you do so, the WorkSpace will not function correctly

5. Incorrect AD Connector service account password

If you use a AD Connector for AWS Directory Service, then verify the AD Connector service account password once and ensure that service account is not expired. If there is any changes in service account credential then it must to update AD Connector service account credentials in Directory Service. Then, try to create a new personal WorkSpaces.

6. Check the AD Connector service account permissions

To join a WorkSpace to a domain, you must set up domain credentials with delegated permissions. If your organization uses AD Connector, then it's a best practice to use a service account to communicate with your Active Directory. To verify your AD Connector configuration, complete the following steps:

Verify that the service account is activated in the Active Directory. Verify that the service account password isn't expired. Verify the delegated privileges for the service account in the WorkSpaces organizational unit (OU) are accurate. Verify that the OU name in the WorkSpaces directory is accurate.

By default, an authenticated user can join up to 10 computers to the domain. If you exceed this quota, then you experience domain join issues. For information about how to change the quota, see Default limit to number of workstations a user can join to the domain on the Microsoft website.

7. Incorrect DNS IP addresses set on AD Connector

If your Active Directory DNS IP addresses have changed, then update the DNS addresses for your AD Connector. After you have updated the DNS addresses, try to create a new personal WorkSpaces.

Note: If you need to update the DNS server IP addresses for your Active Directory after launching your WorkSpaces, you must also update your WorkSpaces with the new DNS server settings. See update DNS servers for WorkSpaces Personal.

8. Directory Services security groups are modified

When you create and register a directory with WorkSpaces, the Directory Service creates the directoryID_controllers security group and the WorkSpaces service creates directoryID_workspacesMembers security group. If the rules on either of these security group don’t allow WorkSpaces to communicate with the Domain Controllers, then you can’t create a new WorkSpace. To resolve this issue, make sure that the security groups have the default rules. For AD Connector, the directory security groups allow all outbound traffic by default. For information about other Active Directories, see What gets created with your AWS Managed Microsoft AD.

Important: Make sure that the directoryID_workspacesMembers security group hasn’t been modified. By default, the WorkSpaces security group allows all outbound traffic.

For a self-managed Microsoft Active Directory, verify that the on-premises firewall doesn’t block traffic from WorkSpaces subnets to the Domain Controllers on the required ports.

9. User profile already exists in the C:\ drive

Workspace creation fails when the following are true:

The user's profile already exists in the C:\Users directory.
You launch a Remote Desktop Protocol (RDP) session to the user's WorkSpace, and create a custom image from the WorkSpace.

For example, you launch an RDP session to a WorkSpace from user1. Then, you use the WorkSpace to create a custom image, and you name the image Image_1. The WorkSpace creation from Image_1 fails because a user profile for user1 already exists in the Workspace C:\Usersdirectory where you created Image_1.

To resolve this issue, complete the following steps to delete additional user profiles in C:\Users:

Note: Be sure to also remove the security identifiers and keys of the additional users in the registry.

Access the WorkSpace that you used to create the image for the custom bundle.

Note: If the WorkSpace no longer exists, then access a WorkSpace that successfully launched from the custom bundle.

Open the Startmenu, and then expand Windows System.
Open the context (right-click) menu for This PC, and then choose Properties.
In the navigation pane, choose Advanced system settings.
On the Advanced tab, for User Profiles, choose Settings.
Select the user profile, and then choose Delete. Important: Remove only the users that belong to your domain (domain\UserName).
Navigate to the C:\Users folder to confirm that the user folders are removed. Keep the Administrator and Public folders. Note: The C: drive is hidden by default. Open File Explorer, and then enter C: in the address bar to display the folders.
Verify that the user's security identifier (SID) is removed from the registry. Open the Start menu, and then enter cmd to open a command prompt.
Run the following command:

wmic useraccount get name,sid

Note the SIDfor the removed user.
Open the Start menu, and then enter regedit to open the Registry Editor.
Look for the SID in the following registry location: HKLM:\Software\Microsoft\Windows NT\CurrentVersion\ProfileList. If you don't see a key with the removed user's SID, then no further action is needed. If you find a key with the SID, then proceed to the next step.
Remove the key, and then look for the SID in the following registry location: HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileGuid. If you don't see a key with the removed user's SID, then no further action is needed. If you find a key with the SID, then remove the key.

10. Wrong bundle or directory selected

When you launch an Amazon WorkSpaces Bring Your Own License (BYOL) in WorkSpaces Personal, you must choose a custom bundle. You must also register a dedicated directory for WorkSpaces.

If you already registered a directory, you can set up a new AWS Directory Service for Microsoft Active Directory or AD Connector directory. You can also deregister a directory and reregister it for dedicated WorkSpaces. For more information, see Register an existing AWS Directory Service directory with WorkSpaces Personal.

11. Domain join errors

Domain Join issue

Note: If you use forest trust, then you receive a domain join error if the user is in one Active Directory and the WorkSpace is in another directory. It’s a best practice to use two-way trust for Amazon Linux, Ubuntu, and Red Hat Enterprise Linux WorkSpaces. Red Hat Enterprise Linux and Ubuntu WorkSpaces use System Security Services Daemon (SSSD) for Active Directory integration. Because SSSD doesn’t support forest trust, you must configure external trust instead.

Check the communication with the Domain Controllers

Make sure the WorkSpace can communicate with the Active Directory Domain Controllers through any virtual private cloud (VPC) resource. These resources include security groups, network access control lists (network ACLs), and route tables. Also, verify that the WorkSpace can communicate with your Domain Controllers on the required ports to communicate with directory controllers.

WorkSpaces use the Elastic Network Interface (ENI) in the VPC to communicate with Domain Controllers on the required ports during domain join and login.

Important: Make sure that the directoryID_workspacesMembers security group hasn’t been modified. By default, the WorkSpaces security group allows all outbound traffic.

For a self-managed Microsoft Active Directory, verify that the on-premises firewall doesn’t block traffic from WorkSpaces subnets to the Domain Controllers on the required ports.

Verify that the required ports are open in a Windows WorkSpace

Complete the following steps:

Launch an Amazon Elastic Compute Cloud (Amazon EC2) instance in each WorkSpace subnets and attach the directoryID_workspacesMembers security group.
Use RDP to connect to the instance.
To turn off the operating system (OS) firewall and set the static DNS, run the following PowerShell command:

Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled False
Set-DnsClientServerAddress -InterfaceIndex ((Get-NetAdapter).ifIndex) -ServerAddresses ("DNS Server IP 1","DNS Server IP 2")

Note: Replace DNS Server IP 1 and DNS Server IP 2 with your DNS server IP addresses.

Use the PortQry tool to test the connectivity to the domain controller on above port. For more information, see Specify one or more target ports on the Microsoft website. To download the PortQry tool, see PortQry Command Line Port Scanner Version 2.0. Extract the zip file. In command prompt, navigate to the path where you extracted the tool and run the following command to test the connectivity.

portqry -n <DNS Server IP address> -p both -e 53
portqry -n <Domain FQDN or Domain Controller IP address> -p both -e 88
portqry -n <Domain FQDN or Domain Controller IP address> -p both -e 389
portqry -n <Domain FQDN or Domain Controller IP address> -p both -e 445
portqry -n <Domain FQDN or Domain Controller IP address> -p both -e 636
portqry -n <Domain FQDN or Domain Controller IP address> -p udp -e 123,137,138
portqry -n <Domain FQDN or Domain Controller IP address> -p tcp -e 135,139

Fix errors as you find them. After all the port test succeed, manually join the instance to the domain.

Note: You can use the steps to join the instance for both AWS Directory Service for Microsoft Active Directory or for a self-managed Active Directory.

Verify that the required ports are open in an Amazon Linux 2, Ubuntu, or Red Hat Enterprise Linux WorkSpace

Complete the following steps:

Use the Linux operating system (OS) that you used to launch the WorkSpace to launch an EC2 instance in each WorkSpaces subnet and attach the directoryID_workspacesMembers security group.
Use SSH to connect to the instance.
To test port connectivity from the WorkSpace subnets to the Domain Controller, run the following commands:

nc -z -v -w 15 domain controller ip 53
nc -z -v -u -w 15 domain controller ip 53
nc -z -v -w 15 domain controller ip 88
nc -z -v -u -w 15 domain controller ip 88
nc -z -v -u -w 15 domain controller ip 135
nc -z -v -w 15 domain controller ip 389
nc -z -v -u -w 15 domain controller ip 389
nc -z -v -w 15 domain controller ip 636
nc -z -v -u -w 15 domain controller ip 636
nc -z -v -w 15 domain controller ip 3268
nc -z -v -w 15 domain controller ip 3269

apt-get install -y adcli
adcli info -S Domain FQDN
adcli info -S domain controller ip

Note: Replace domain controller ip with the Domain Controller IP address and Domain FQDNwith the domain’s fully qualified domain name (FQDN).

Fix errors as you find them. After all the port test succeed, manually join the instance to domain.

For more information about your netcat command flags, use the following command flag summaries:

nc -z: Scans for open ports on a remote host without establishing a full connection. Note: Use nc -4 to connect to IPv4 addresses only.
nc -v: provides verbose output
nc -u: uses UDP instead of TCP. Note: Use nc -t to show all TCP connections.
nc -w: specifies a timeout for connection that can not be established.

Additional Information

Additionally, review best practices, diagnostic logs and troubleshooting specific issues to identify and resolve performance bottlenecks while accessing your WorkSpaces using WorkSpaces client.

Conclusion

In summary, this playbook provides an essential guide to managing Amazon WorkSpaces, covering both fundamental concepts and common troubleshooting scenarios. By following the best practices and solutions outlined here, administrators and users can resolve frequent issues efficiently, ensuring a smoother and more productive WorkSpaces experience.