# Bundles and images for WorkSpaces Pools A *WorkSpace bundle* is a combination of an operating system, and storage, compute, and software resources. When you launch a WorkSpace, you select the bundle that meets your needs. The default bundles available for WorkSpaces are called *public bundles*. For more information about the various public bundles available for WorkSpaces, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/details/#Amazon_WorkSpaces_Bundles). If you've launched a Windows WorkSpace and have customized it, you can create a custom image from that WorkSpace for use with WorkSpaces Pool. Linux are not supported in WorkSpaces Pool. A *custom image* contains only the OS, software, and settings for the WorkSpace. A *custom bundle* is a combination of both that custom image and the hardware from which a WorkSpace can be launched. After you create a custom image, you can build a custom bundle that combines the custom WorkSpace image and the underlying compute and storage configuration that you select. You can then specify this custom bundle when you create new WorkSpaces Pools to ensure that the new WorkSpaces in the pool have the same consistent configuration (hardware and software). If you need to perform software updates or to install additional software on your WorkSpaces, you can update your custom bundle and use it to rebuild your WorkSpaces. WorkSpaces Pools supports several different operating systems (OS), streaming protocols, and bundles. The following table provides information about the licensing, streaming protocols, and bundles that are supported by each OS. | Operating System | Licenses | Streaming protocols | Supported bundles | Lifecycle policy / retirement date | | --- | --- | --- | --- | --- | | Windows Server 2019 | Included | DCV | Value, Standard, Performance, Power, PowerPro | [January 9, 2029](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2019) | | Windows Server 2022 | Included | DCV | Standard, Performance, Power, PowerPro, Graphics.G4dn, GraphicsPro.G4dn | [October 14, 2031](https://learn.microsoft.com/en-us/lifecycle/products/windows-server-2022) | **Note** Operating system versions that are no longer supported by the vender are not guaranteed to work and are not supported by AWS support. **Topics** + [Bundle options for WorkSpaces Pools](pools-custom-images-bundles.md) + [Create a custom image and bundle for WorkSpaces Pools](pools-images-custom-image.md) + [Manage custom images and bundles for WorkSpaces Pools](pools-images-managing.md) + [Use session scripts to manage your users' streaming experience](pools-images-session-scripts.md) # Bundle options for WorkSpaces Pools Before selecting a bundle to use with WorkSpaces Pool, ensure the bundle you want to select is compatible with your WorkSpaces' protocol, operating system, network, and compute type. We recommend testing the performance of bundles you want to choose in a test environment by running and using applications that replicate your users' daily tasks. For more information about protocols, see [Protocols for WorkSpaces Personal](amazon-workspaces-networking.md#amazon-workspaces-protocols). For more information about networks, see [Client network requirements for WorkSpaces Personal](workspaces-network-requirements.md). The following public bundles can be used with WorkSpaces Pool. For information about bundles in WorkSpaces, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/details/#Amazon_WorkSpaces_Bundles). Value, Standard, Performance, Power, PowerPro ## Value bundle This bundle is well-suited for the following: + Basic text editing and data entry + Web browsing with light usage + Instant messaging This bundle is not recommended for word processing, audio and video conferencing, screen sharing, software development tool, business intelligence applications, and graphics applications. ## Standard bundle This bundle is well-suited for the following: + Basic text editing and data entry + Web browsing + Instant messaging + Email This bundle is not recommended for audio and video conferencing, screen sharing, word processing, software development tool, business intelligence applications, and graphics applications ## Performance bundle This bundle is well-suited for the following: + Web browsing + Word processing + Instant messaging + Email + Spreadsheets + Audio processing + Courseware This bundle is not recommended for video conferencing, screen sharing, software development tool, business intelligence applications, and graphics applications ## Power bundle This bundle is well-suited for the following: + Web browsing + Word processing + Email + Instant messaging + Spreadsheets + Audio processing + Software development (Integrated Development Environment (IDE)) + Entry to mid-level data processing + Audio and video conferencing This bundle is not recommended for screen sharing, software development tool, business intelligence applications, and graphics applications. ## PowerPro bundle This bundle is well-suited for the following: + Web browsing + Word processing + Email + Instant messaging + Spreadsheets + Audio processing + Software development (Integrated Development Environment (IDE)) + Data warehousing + Business intelligence applications + Audio and video conferencing This bundle is not recommended for machine learning model training, and graphics applications ## Graphics.g4dn bundle This bundle offers a high level of graphics performance, and moderate level of CPU performance and memory for your WorkSpaces and is well-suited for the following: + Web browsing + Word processing + Email + Spreadsheets + Instant messaging + Audio conferencing + Software development (Integrated Development Environment (IDE)) + Entry to mid-level data processing + Data warehousing + Business intelligence applications + Graphic design + CAD/CAM (computer-aided design/computer-aided manufacturing) This bundle is not recommended for audio and video conferencing, 3D rendering, photo-realistic design, and machine learning model training ## GraphicsPro.g4dn bundle This bundle offers a high level of graphics performance, CPU performance, and memory for your WorkSpaces and is well-suited for the following: + Web browsing + Word processing + Email + Spreadsheets + Instant messaging + Audio conferencing + Software development (Integrated Development Environment (IDE)) + Entry to mid-level data processing + Data warehousing + Business intelligence applications + Graphic design + CAD/CAM (computer-aided design/computer-aided manufacturing) + Video transcoding + 3D rendering + Photo-realistic design + Game streaming + ML (machine learning) model training and ML inference This bundle is not recommended for audio and video conferencing. # Create a custom image and bundle for WorkSpaces Pools WorkSpaces Pool supports Windows images and bundles only. If you've launched a Windows or WorkSpace and have customized it, you can create a custom image and custom bundles from that WorkSpace. A *custom image* contains only the OS, software, and settings for the WorkSpace. A *custom bundle* is a combination of both that custom image and the hardware from which a WorkSpace can be launched. 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). You can use the same custom image to create various custom bundles by selecting different compute and storage options for each bundle. **Important** Custom bundle storage volumes can't be smaller than image storage volumes. Custom bundles cost the same as the public bundles they are created from. For more information about pricing, see [Amazon WorkSpaces Pricing](https://aws.amazon.com/workspaces/pricing/). **Topics** + [Requirements to create Windows custom images](#pools-windows_custom_image_requirements) + [Best practices](#pools-custom_image_best_practices) + [Step 1: Run the Image Checker](#pools-run_image_checker) + [Step 2: Create a custom image and custom bundle](#pools-create_custom_image_bundle) + [What's included with Windows WorkSpaces custom images](#pools-image_creation_windows) ## Requirements to create Windows custom images **Note** Windows currently defines 1 GB as 1,073,741,824 bytes. You must ensure they have greater than 12,884,901,888 bytes (or 12 GiB) free on C drive and the user profile is less than 10,737,418,240 bytes (or 10 GiB) to create an image of a WorkSpace. + The status of the WorkSpace must be **Available** and its modification state must be **None**. + All applications and user profiles on WorkSpaces images must be compatible with Microsoft Sysprep. + All applications to include in the image must be installed on the `C` drive. + All application services running on the WorkSpace must use a local system account instead of domain user credentials. For example, you cannot have a Microsoft SQL Server Express installation running with a domain user's credentials. + The WorkSpace must not be encrypted. Image creation from an encrypted WorkSpace is not currently supported. + The following components are required in an image. Without these components, the WorkSpaces that you launch from the image will not function correctly. For more information, see [Required configuration and service components for WorkSpaces Personal](required-service-components.md). + Windows PowerShell version 3.0 or later + Remote Desktop Services + AWS PV drivers + Windows Remote Management (WinRM) + Teradici PCoIP agents and drivers + STXHD agents and drivers + AWS and WorkSpaces certificates + Skylight agent + WorkSpaces Pools only supports a maximum bundle / image root volume size of 200 GB. When you create a Windows custom image, ensure it is under the root volume size of 200 GB. ## Best practices Before you create an image from a WorkSpace, do the following: + Use a separate VPC that is not connected to your production environment. + Deploy the WorkSpace in a private subnet and use a NAT instance for outbound traffic. + Use a small Simple AD directory. + Use the smallest volume size for the source WorkSpace, and then adjust the volume size as needed when creating the custom bundle. + Install all operating system updates (except Windows feature/version updates) and all application updates on the WorkSpace. + Delete cached data from the WorkSpace that shouldn't be included in the bundle (for example, browser history, cached files, and browser cookies). + Delete configuration settings from the WorkSpace that shouldn't be included in the bundle (for example, email profiles). + Switch to dynamic IP address settings using DHCP. + Make sure that you haven't exceeded your quota for WorkSpace images allowed in a Region. By default, you're allowed 40 WorkSpace images per Region. If you've reached this quota, new attempts to create an image will fail. To request a quota increase, use the [WorkSpaces Limits form](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase&limitType=workspaces). + Make sure that you aren't trying to create an image from an encrypted WorkSpace. Image creation from an encrypted WorkSpace is not currently supported. + If you're running any antivirus software on the WorkSpace, disable it while you're attempting to create an image. + If you have a firewall enabled on your WorkSpace, make sure that it isn't blocking any necessary ports. For more information, see [IP address and port requirements for WorkSpaces Personal](workspaces-port-requirements.md). + 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. We recommend making any customizations to the user profile through GPOs, and applying them after image creation. GPOs can be easily modified or rolled back, and are therefore less prone to error than customizations made to the default user profile. + 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 ](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/enhanced-networking-ena.html#ena-adapter-driver-install-upgrade-win), [AWS NVMe drivers for Windows instances](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/aws-nvme-drivers.html), and [Upgrade PV drivers on Windows instances](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/Upgrading_PV_drivers.html). + Ensure you update the EC2Config, EC2Launch, and EC2Launch V2 agents to the latest versions periodically. You should do this at least once every 6 months. For more information, see [Update EC2Config and EC2Launch](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/migrating-latest-types.html#upgdate-ec2config-ec2launch). ## Step 1: Run the Image Checker To confirm that your Windows WorkSpace meets the requirements for image creation, we recommend running the Image Checker application. The Image Checker performs a series of tests on the WorkSpace that you want to use to create your image, and provides guidance on how to resolve any issues it finds. The Image Checker is available only for Windows WorkSpaces. **Important** The WorkSpace must pass all of the tests run by the Image Checker before you can use it for image creation. Before you run the Image Checker, verify that the latest Windows security and cumulative updates are installed on your WorkSpace. To get the Image Checker, do one of the following: + [Reboot your WorkSpace](reboot-workspaces.md). The Image Checker is downloaded automatically during the reboot and installed at `C:\Program Files\Amazon\ImageChecker.exe`. + Download the Amazon WorkSpaces Image Checker from [https://tools.amazonworkspaces.com/ImageChecker.zip](https://tools.amazonworkspaces.com/ImageChecker.zip) and extract the `ImageChecker.exe` file. Copy this file to `C:\Program Files\Amazon\`. **To run the Image Checker** 1. Open the `C:\Program Files\Amazon\ImageChecker.exe` file. 1. In the **Amazon WorkSpaces Image Checker** dialog box, choose **Run**. 1. After each test is completed, you can view the status of the test. For any test with a status of **FAILED**, choose **Info** to display information about how to resolve the issue that caused the failure. For more information about how to resolve these issues, see [Tips for resolving issues detected by the Image Checker](#pools-image_checker_tips). If any tests display a status of **WARNING**, choose the **Fix All Warnings** button. The tool generates an output log file in the same directory where the Image Checker is located. By default, this file is located at `C:\Program Files\Amazon\ImageChecker_yyyyMMddhhmmss.log`. Don't delete this log file. If an issue occurs, this log file might be helpful in troubleshooting. 1. If applicable, resolve any issues that cause test failures and warnings, and repeat the process of running the Image Checker until the WorkSpace passes all tests. All failures and warnings must be resolved before you can create an image. 1. After your WorkSpace passes all tests, you see a **Validation Successful** message. You are now ready to create a custom bundle. ### Tips for resolving issues detected by the Image Checker In addition to consulting the following tips for resolving issues that are detected by the Image Checker, be sure to review the Image Checker log file at `C:\Program Files\Amazon\ImageChecker_yyyyMMddhhmmss.log`. #### PowerShell version 3.0 or later must be installed Install the latest version of [ Microsoft Windows PowerShell](https://docs.microsoft.com/powershell). **Important** The PowerShell execution policy for a WorkSpace must be set to allow **RemoteSigned** scripts. To check the execution policy, run the **Get-ExecutionPolicy** PowerShell command. If the execution policy is not set to **Unrestricted** or **RemoteSigned**, run the **Set-ExecutionPolicy –ExecutionPolicy RemoteSigned** command to change the value of the execution policy. The **RemoteSigned** setting allows the execution of scripts on Amazon WorkSpaces, which is required to create an image. #### Only the C and D drives can be present Only the `C` and `D` drives can be present on a WorkSpace that's used for imaging. Remove all other drives, including virtual drives. #### No pending reboot due to Windows Updates can be detected + The Create Image process can't run until Windows is rebooted to finish installing security or cumulative updates. Reboot Windows to apply these updates, and make sure that no other pending Windows security or cumulative updates need to be installed. + Image creation is not supported on Windows 10 systems that have been upgraded from one version of Windows 10 to a newer version of Windows 10 (a Windows feature/version upgrade). However, Windows cumulative or security updates are supported by the WorkSpaces image-creation process. #### The Sysprep file must exist and can't be blank If there are problems with your Sysprep file, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/) to get your EC2Config or EC2Launch repaired. #### The user profile size must be less than 10 GB For Windows 7 WorkSpaces, the user profile (`D:\Users\username`) must be less than 10 GB total. Remove files as needed to reduce the size of the user profile. #### Drive C must have enough free space For Windows 7 WorkSpaces, you must have at least 12 GB of free space on drive `C`. Remove files as needed to free up space on drive `C`. For Windows 10 WorkSpaces, ignore if you receive a `FAILED` message and the disk space is above 2GB. #### No services can be running under a domain account To run the Create Image process, no services on the WorkSpace can be running under a domain account. All services must be running under a local account. **To run services under a local account** 1. Open `C:\Program Files\Amazon\ImageChecker_yyyyMMddhhmmss.log` and find the list of services that are running under a domain account. 1. In the Windows search box, enter **services.msc** to open the Windows Services Manager. 1. Under **Log On As**, look for the services that are running under domain accounts. (Services running as **Local System**, **Local Service**, or **Network Service** do not interfere with image creation.) 1. Select a service that is running under a domain account, and then choose **Action**, **Properties**. 1. Open the **Log On** tab. Under **Log on as**, choose **Local System account**. 1. Choose **OK**. #### The WorkSpace must be configured to use DHCP You must configure all network adapters on the WorkSpace to use DHCP instead of static IP addresses. **To set all network adapters to use DHCP** 1. In the Windows search box, enter **control panel** to open the Control Panel. 1. Choose **Network and Internet**. 1. Choose **Network and Sharing Center**. 1. Choose **Change adapter settings**, and select an adapter. 1. Choose **Change settings of this connection**. 1. On the **Networking** tab, select **Internet Protocol Version 4 (TCP/IPv4)**, and then choose **Properties**. 1. In the **Internet Protocol Version 4 (TCP/IPv4) Properties** dialog box, select **Obtain an IP address automatically**. 1. Choose **OK**. 1. Repeat this process for all network adapters on the WorkSpace. #### Remote Desktop Services must be enabled The Create Image process requires Remote Desktop Services to be enabled. **To enable Remote Desktop Services** 1. In the Windows search box, enter **services.msc** to open the Windows Services Manager. 1. In the **Name** column, find **Remote Desktop Services**. 1. Select **Remote Desktop Services**, and then choose **Action**, **Properties**. 1. On the **General** tab, for **Startup type**, choose **Manual** or **Automatic**. 1. Choose **OK**. #### A user profile must exist The WorkSpace that you're using to create images must have a user profile (`D:\Users\username`). If this test fails, contact the [AWS Support Center](https://console.aws.amazon.com/support/home#/) for assistance. #### The environment variable path must be properly configured The environment variable path for the local machine is missing entries for System32 and for Windows PowerShell. These entries are required for Create Image to run. **To configure your environment variable path** 1. In the Windows search box, enter **environment variables** and then choose **Edit the system environment variables**. 1. In the **System Properties** dialog box, open the **Advanced** tab, and choose **Environment Variables**. 1. In the **Environment Variables** dialog box, under **System variables**, select the **Path** entry and then choose **Edit**. 1. Choose **New**, and add the following path: `C:\Windows\System32` 1. Choose **New** again, and add the following path: `C:\Windows\System32\WindowsPowerShell\v1.0\` 1. Choose **OK**. 1. Restart the WorkSpace. **Tip** The order in which items appear in the environment variable path matters. To determine the correct order, you might want to compare the environment variable path of your WorkSpace with one from a newly created WorkSpace or a new Windows instance. #### Windows Modules Installer must be enabled The Create Image process requires the Windows Modules Installer service to be enabled. **To enable the Windows Modules Installer service** 1. In the Windows search box, enter **services.msc** to open the Windows Services Manager. 1. In the **Name** column, find **Windows Modules Installer**. 1. Select **Windows Modules Installer**, and then choose **Action**, **Properties**. 1. On the **General** tab, for **Startup type**, choose **Manual** or **Automatic**. 1. Choose **OK**. #### Amazon SSM Agent must be disabled The Create Image process requires the Amazon SSM Agent service to be disabled. **To disable the Amazon SSM Agent service** 1. In the Windows search box, enter **services.msc** to open the Windows Services Manager. 1. In the **Name** column, find **Amazon SSM Agent**. 1. Select **Amazon SSM Agent**, and then choose **Action**, **Properties**. 1. On the **General** tab, for **Startup type**, choose **Disabled**. 1. Choose **OK**. #### SSL3 and TLS version 1.2 must be enabled To configure SSL/TLS for Windows, see [ How to Enable TLS 1.2](https://docs.microsoft.com/configmgr/core/plan-design/security/enable-tls-1-2) in the Microsoft Windows documentation. #### Only one user profile can exist on the WorkSpace There can be only one WorkSpaces user profile (`D:\Users\username`) on the WorkSpace that you're using to create images. Delete any user profiles that don't belong to the intended user of the WorkSpace. For image creation to work, your WorkSpace can have only three user profiles on it: + The user profile of the intended user of the WorkSpace (`D:\Users\username`) + The default user profile (also known as Default Profile) + The Administrator user profile If there are additional user profiles, you can delete them through the advanced system properties in the Windows Control Panel. **To delete a user profile** 1. To access the advanced system properties, do one of the following: + Press the **Windows key\$1Pause Break**, and then choose **Advanced system settings** in the left pane of the **Control Panel** > **System and Security** > **System** dialog box. + In the Windows search box, enter **control panel**. In the Control Panel, choose **System and Security**, then choose System, and then choose **Advanced system settings** in the left pane of the **Control Panel** > **System and Security** > **System** dialog box. 1. In the **System Properties** dialog box, on the **Advanced** tab, choose **Settings** under **User Profiles**. 1. If any profile is listed other than the Administrator profile, the Default Profile, and the profile of the intended WorkSpaces user, select that additional profile and choose **Delete**. 1. When asked if you want to delete the profile, choose **Yes**. 1. If necessary, repeat Steps 3 and 4 to remove any other profiles that don't belong on the WorkSpace. 1. Choose **OK** twice and close the Control Panel. 1. Restart the WorkSpace. #### No AppX packages can be in a staged state One or more AppX packages are in a staged state. This might cause a Sysprep error during image creation. **To remove all staged AppX packages** 1. In the Windows search box, enter **powershell**. Choose **Run as Administrator**. 1. When asked "Do you want to allow this app to make changes to your device?", choose **Yes**. 1. In the Windows PowerShell window, enter the following commands to list all staged AppX packages, and press Enter after each one. ``` $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*") } ``` 1. Execute the following command with elevated SYSTEM privileges to remove all staged AppX package provisioning entries, and press Enter. ``` $packages | Remove-AppxPackage -ErrorAction SilentlyContinue ``` 1. Run the Image Checker again. If this test still fails, enter the following commands to remove all AppX packages, and press Enter after each one. ``` Get-AppxProvisionedPackage -Online | Remove-AppxProvisionedPackage -Online -ErrorAction SilentlyContinue ``` ``` Get-AppxPackage -AllUsers | Remove-AppxPackage -ErrorAction SilentlyContinue ``` #### Windows must not have been upgraded from a previous version Image creation is not supported on Windows systems that have been upgraded from one version of Windows 10 to a newer version of Windows 10 (a Windows feature/version upgrade). To create images, use a WorkSpace that has not undergone a Windows feature/version upgrade. #### The Windows rearm count must not be 0 The rearm feature allows you to extend the activation period for the trial version of Windows. The Create Image process requires that the rearm count be a value other than 0. **To check the Windows rearm count** 1. On the Windows **Start** menu, choose **Windows System**, then choose **Command Prompt**. 1. In the Command Prompt window, enter the following command, and then press Enter. `cscript C:\Windows\System32\slmgr.vbs /dlv` To reset the rearm count to a value other than 0, see [ Sysprep (Generalize) a Windows installation](https://docs.microsoft.com/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation) in the Microsoft Windows documentation. #### Other troubleshooting tips If your WorkSpace passes all of the tests run by the Image Checker, but you are still unable to create an image from the WorkSpace, check for the following issues: + Make sure that the WorkSpace isn't assigned to a user within a **Domain Guests** group. To check if there are any domain accounts, run the following PowerShell command. ``` Get-WmiObject -Class Win32_Service | Where-Object { $_.StartName -like "*$env:USERDOMAIN*" } ``` + Some Group Policy Objects (GPOs) restrict access to the RDP certificate thumbprint when it is requested by the EC2Config service or the EC2Launch scripts during Windows instance configuration. Before you try to create an image, move the WorkSpace to a new organizational unit (OU) with blocked inheritance and no GPOs applied. + Make sure that the Windows Remote Management (WinRM) service is configured to start automatically. Do the following: 1. In the Windows search box, enter `services.msc` to open the Windows Services Manager. 1. In the **Name** column, find **Windows Remote Management (WS-Management)**. 1. Select **Windows Remote Management (WS-Management)**, and then choose **Action**, **Properties**. 1. On the **General** tab, for **Startup type**, choose **Automatic**. 1. Choose **OK**. ## Step 2: Create a custom image and custom bundle After you have validated your WorkSpace image, complete the following procedure to create your custom image and custom bundle using the WorkSpaces console. To create an image programmatically, use the CreateWorkspaceImage API action. For more information, see [ CreateWorkspaceImage](https://docs.aws.amazon.com/workspaces/latest/api/API_CreateWorkspaceImage.html) in the *Amazon WorkSpaces API Reference*. To create a bundle programmatically, use the **CreateWorkspaceBundle** API action. For more information, see [ CreateWorkspaceBundle](https://docs.aws.amazon.com/workspaces/latest/api/API_CreateWorkspaceBundle.html) in the *Amazon WorkSpaces API Reference*. **To create a custom image and custom bundle using the WorkSpaces console** 1. If you are still connected to the WorkSpace, disconnect by choosing **Amazon WorkSpaces** and **Disconnect** in the WorkSpaces client application. 1. Open the WorkSpaces console at [https://console.aws.amazon.com/workspaces/v2/home](https://console.aws.amazon.com/workspaces/v2/home). 1. In the navigation pane, choose **WorkSpaces**. 1. Select the WorkSpace to open its details page and choose **Create image**. If the status of the WorkSpace is **Stopped**, you must start it first (choose **Actions**, **Start WorkSpaces**) before you can choose **Actions**, **Create Image**. 1. A message displays, prompting you to reboot (restart) your WorkSpace before continuing. Rebooting your WorkSpace updates your Amazon WorkSpaces software to the latest version. Reboot your WorkSpace by closing the message and following the steps in [Reboot a WorkSpace in WorkSpaces Personal](reboot-workspaces.md). When you're done, repeat [Step 4](create-custom-bundle.md#step_create_image) of this procedure, but this time choose **Next** when the reboot message appears. To create an image, the status of the WorkSpace must be **Available** and its modification state must be **None**. 1. Enter an image name and a description that will help you identify the image, and then choose **Create Image**. While the image is being created, the status of the WorkSpace is **Suspended** and the WorkSpace is unavailable. Don't use a dash (`-`) special character in the description. It will cause an error. 1. In the navigation pane, choose **Images**. The image is complete when the status of the WorkSpace changes to **Available** (this can take up to 45 minutes). 1. Select the image and choose **Actions**, **Create bundle**. 1. Enter a bundle name and a description, and then do the following: + For **Bundle hardware type**, choose the hardware to use when launching WorkSpaces from this custom bundle. + The default available size combinations for the root volume is 200 GB per WorkSpace. 1. To confirm that your bundle has been created, choose **Bundles** and verify that the bundle is listed. ## What's included with Windows WorkSpaces custom images When you create an image from a Windows WorkSpace, the entire contents of the `C` drive are included. + Contacts + Downloads + Music + Pictures + Saved games + Videos + Podcasts + Virtual machines + .virtualbox + Tracing + appdata\$1local\$1temp + appdata\$1roaming\$1apple computer\$1mobilesync\$1 + appdata\$1roaming\$1apple computer\$1logs\$1 + appdata\$1roaming\$1apple computer\$1itunes\$1iphone software updates\$1 + appdata\$1roaming\$1macromedia\$1flash player\$1macromedia.com\$1support\$1flashplayer\$1sys\$1 + appdata\$1roaming\$1macromedia\$1flash player\$1\$1sharedobjects\$1 + appdata\$1roaming\$1adobe\$1flash player\$1assetcache\$1 + appdata\$1roaming\$1microsoft\$1windows\$1recent\$1 + appdata\$1roaming\$1microsoft\$1office\$1recent\$1 + appdata\$1roaming\$1microsoft office\$1live meeting + appdata\$1roaming\$1microsoft shared\$1livemeeting shared\$1 + appdata\$1roaming\$1mozilla\$1firefox\$1crash reports\$1 + appdata\$1roaming\$1mcafee\$1common framework\$1 + appdata\$1local\$1microsoft\$1feeds cache + appdata\$1local\$1microsoft\$1windows\$1temporary internet files\$1 + appdata\$1local\$1microsoft\$1windows\$1history\$1 + appdata\$1local\$1microsoft\$1internet explorer\$1domstore\$1 + appdata\$1local\$1microsoft\$1internet explorer\$1imagestore\$1 + appdata\$1locallow\$1microsoft\$1internet explorer\$1iconcache\$1 + appdata\$1locallow\$1microsoft\$1internet explorer\$1domstore\$1 + appdata\$1locallow\$1microsoft\$1internet explorer\$1imagestore\$1 + appdata\$1local\$1microsoft\$1internet explorer\$1recovery\$1 + appdata\$1local\$1mozilla\$1firefox\$1profiles\$1 # Manage custom images and bundles for WorkSpaces Pools The process to manage custom images and bundles is the same between WorkSpaces Personal and WorkSpaces Pool. For more information about how to manage images and bundles, refer to the following documentation within the WorkSpaces Personal section of this guide: **Note** The primary difference between custom bundles that you can use for WorkSpaces Personal and ones that you can use for WorkSpaces Pool is the operating system and base public bundle that can be used. For the operating systems and bundles that are supported in WorkSpaces Pool, see [ WorkSpaces Pools BundlesBundles Learn about WorkSpaces Pools bundles. A *WorkSpace bundle* is a combination of an operating system, and storage, compute, and software resources. When you launch a WorkSpace, you select the bundle that meets your needs. The default bundles available for WorkSpaces are called *public bundles*. For more information about the various public bundles available for WorkSpaces, see [Amazon WorkSpaces Bundles](https://aws.amazon.com/workspaces/details/#Amazon_WorkSpaces_Bundles). The following table provides information about the licensing, streaming protocols, and bundles that are supported by each OS. | Operating System | Licenses | Streaming protocols | Supported bundles | | --- | --- | --- | --- | | Windows Server 2019 | Included | DCV | Value, Standard, Performance, Power, PowerPro | | Windows Server 2022 | Included | DCV | Standard, Performance, Power, PowerPro, Graphics.G4dn, GraphicsPro.G4dn | Operating system versions that are no longer supported by the vender are not guaranteed to work and are not supported by AWS support. ](instance-types.md#instance-types.title). + [Update a custom bundle for WorkSpaces Personal](update-custom-bundle.md). + [Copy a custom image in WorkSpaces Personal](copy-custom-image.md). + [Share or unshare a custom image in WorkSpaces Personal](share-custom-image.md). + [Delete a custom bundle or image in WorkSpaces Personal](delete_bundle.md). # Use session scripts to manage your users' streaming experience WorkSpaces Pool provides on-instance session scripts. You can use these scripts to run your own custom scripts when specific events occur in users' streaming sessions. For example, you can use custom scripts to prepare your WorkSpaces Pools environment before your users' streaming sessions begin. You can also use custom scripts to clean up streaming instances after users complete their streaming sessions. Session scripts are specified within a WorkSpace image. These scripts are run within the user context or the system context. If your session scripts use the standard out to write information, error, or debugging messaging, these can be optionally saved to an Amazon S3 bucket within your Amazon Web Services account. **Topics** + [Run Scripts Before Streaming Sessions Begin](#run-scripts-before-streaming-sessions-begin) + [Run Scripts After Streaming Sessions End](#run-scripts-after-streaming-sessions-end) + [Create and Specify Session Scripts](#create-specify-session-scripts) + [Session Scripts Configuration File](#session-script-configuration-file) + [Using Windows PowerShell Files](#using-powershell-files-with-session-scripts) + [Logging Session Script Output](#logging-session-output) + [Use persistent storage with session scripts](#use-storage-connectors-with-session-scripts) + [Enable Amazon S3 Bucket Storage for Session Script Logs](#enable-S3-bucket-storage-session-script-logs) ## Run Scripts Before Streaming Sessions Begin You can configure your scripts to run for a maximum of 60 seconds before your users' applications launch and their streaming sessions begin. Doing so enables you to customize the WorkSpaces Pools environment before users start streaming their applications. When the session scripts run, a loading spinner displays for your users. When your scripts complete successfully or the maximum waiting time elapses, your users' streaming session will begin. If your scripts don't complete successfully, an error message displays for your users. However, your users are not prevented from using their streaming session. When you specify a file name on a Windows instance, you must use a double backslash. For example: ``` C:\\Scripts\\Myscript.bat ``` If you don't use a double backslash, an error displays to notify you that the `.json` file is incorrectly formatted. **Note** When your scripts complete successfully, they must return a value of 0. If your scripts return a value other than 0, WorkSpaces displays the error message to the user. When you run scripts before streaming sessions begin, the following process occurs: 1. Your users connect to a WorkSpace in a WorkSpaces Pool that is not domain-joined. They connect by using SAML 2.0. 1. One of the following occurs: + If application settings persistence is enabled for your users, the application settings Virtual Hard Disk (VHD) file that stores your users' customizations and Windows settings is downloaded and mounted. Windows user login is required in this case. For information about application settings persistence, see [Enable application settings persistence for your WorkSpaces Pools users](app-settings-persistence.md). + If application settings persistence is not enabled, the Windows user is already logged in. 1. Your session scripts start. If persistent storage is enabled for your users, storage connector mounting also starts. For information about persistent storage, see [Enable and Administer Persistent Storage for WorkSpaces Pools](persistent-storage.md). **Note** The storage connector mount doesn't need to complete for the streaming session to start. If the session scripts complete before the storage connector mount completes, the streaming session starts. For information about monitoring the mount status of storage connectors, see [Use persistent storage with session scripts](#use-storage-connectors-with-session-scripts). 1. Your session scripts complete or time out. 1. The users' streaming session starts. ## Run Scripts After Streaming Sessions End You can also configure your scripts to run after users' streaming sessions end. For example, you can run a script when users select **End Session** from the WorkSpaces client toolbar, or when they reach the maximum allowed duration for the session. You can also use these session scripts to clean up your WorkSpaces environment before a streaming instance is terminated. For example, you can use scripts to release file locks or upload log files. When you run scripts after streaming sessions end, the following process occurs: 1. Your users' WorkSpaces streaming session ends. 1. Your session termination scripts start. 1. The session termination scripts complete or time out. 1. Windows user logout occurs. 1. One or both of the following occur in parallel, if applicable: + If application settings persistence is enabled for your users, the application settings VHD file that stores your users' customizations and Windows settings is unmounted and uploaded to an Amazon S3 bucket in your account. + If persistent storage is enabled for your users, the storage connector completes a final synchronization and is unmounted. 1. The WorkSpace is terminated. ## Create and Specify Session Scripts Complete the following procedure to create and specify session scripts for your WorkSpaces in a WorkSpaces Pool. 1. Connect to the Windows WorkSpaces from which you are creating a custom image. 1. Create the directory `/AWSEUC/SessionScripts` if it does not already exist. 1. Create a configuration file `/AWSEUC/SessionScripts/config.json` if it does not already exist, using the [Session Script Configuration template](https://docs.aws.amazon.com/workspaces/latest/adminguide/pools-images-session-scripts.html#session-script-configuration-file). 1. Navigate to `C:\AWSEUC\SessionScripts`, and open the `config.json` configuration file. For information about session script parameters, see [Session Scripts Configuration File](#session-script-configuration-file). 1. After you finish making your changes, save and close the `config.json` file. 1. Complete the steps to create an image from the WorkSpace. For more information, see [Create a custom image and bundle for WorkSpaces Pools](pools-images-custom-image.md). ## Session Scripts Configuration File To locate the session scripts configuration file in a Windows instance, navigate to `C:\AWSEUC\SessionScripts\config.json`. The file is formatted as follows. **Note** The configuration file is in JSON format. Verify that any text you type in this file is in valid JSON format. ``` { "SessionStart": { "executables": [ { "context": "system", "filename": "", "arguments": "", "s3LogEnabled": true }, { "context": "user", "filename": "", "arguments": "", "s3LogEnabled": true } ], "waitingTime": 30 }, "SessionTermination": { "executables": [ { "context": "system", "filename": "", "arguments": "", "s3LogEnabled": true }, { "context": "user", "filename": "", "arguments": "", "s3LogEnabled": true } ], "waitingTime": 30 } } ``` You can use the following parameters in the session scripts configuration file. **`SessionStart/SessionTermination `** The session scripts to run in the appropriate session event based on the name of the object. **Type**: String **Required**: No **Allowed values:** **SessionStart**, **SessionTermination** **`WaitingTime`** The maximum duration of the session scripts in seconds. **Type**: Integer **Required**: No **Constraints:** The maximum duration is 60 seconds. If the session scripts don't complete within this duration, they will be stopped. If you require a script to continue running, launch it as a separate process. **`Executables`** The details for the session scripts to run. **Type**: String **Required**: Yes **Constraints:** The maximum number of scripts that can run per session event is 2 (one for the user context, one for the system context). **`Context`** The context in which to run the session script. **Type**: String **Required**: Yes **Allowed values:** **user**, **system** **`Filename`** The full path to the session script to run. If this parameter is not specified, the session script is not run. **Type**: String **Required**: No **Constraints:** The maximum length for the file name and full path is 1,000 characters. **Allowed values:** **.bat**, **.exe**, **.sh** You can also use Windows PowerShell files. For more information, see [Using Windows PowerShell Files](#using-powershell-files-with-session-scripts). **`Arguments`** The arguments for your session script or executable file. **Type**: String **Required**: No **Length constraints:** The maximum length is 1,000 characters. **`S3LogEnabled`** When the value for this parameter is set to **True**, an S3 bucket is created within your Amazon Web Services account to store the logs created by the session script. By default, this value is set to **True**. For more information, see the *Logging Session Script Output* section later in this topic. **Type**: Boolean **Required**: No **Allowed values:** **True**, **False** ## Using Windows PowerShell Files To use Windows PowerShell files, specify the full path to the PowerShell file in the `filename` parameter: ``` "filename": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", ``` Then specify your session script in the **arguments** parameter: ``` "arguments": "-File \"C:\\path\\to\\session\\script.ps1\"", ``` Finally, verify that the PowerShell Execution Policy allows your PowerShell file to run. ## Logging Session Script Output When this option is enabled in the configuration file, WorkSpaces Pool automatically captures the output from the session script that is written to the standard out. This output is uploaded to an Amazon S3 bucket in your account. You can review the log files for troubleshooting or debugging purposes. **Note** The log files are uploaded when the session script returns a value, or the value set in **WaitingTime** has elapsed, whichever comes first. ## Use persistent storage with session scripts When WorkSpaces persistent storage is enabled, the storage begins mounting when the session start scripts run. If your script relies on persistent storage being mounted, you can wait for the connectors to be available. WorkSpaces maintains the mount status of the storage connectors in the Windows registry on Windows WorkSpaces, at the following key: ``` HKEY_LOCAL_MACHINE\SOFTWARE\Amazon\AWSEUC\Storage\\ ``` The registry key values are as follows: + Provided user name — The user ID provided through the access mode. The access modes and value for each mode are as follows: + User Pool — The email address for the user + Streaming URL — The UserID + SAML — The NameID. If the user name includes a slash (for example, a domain user’s SAMAccountName), the slash is replaced by a "-" character. + Storage connector — The connector for the persistent storage option that is enabled for the user. The storage connector values are as follows: + HomeFolder Each storage connector registry key contains a **MountStatus** DWORD value. The following table lists the possible values for **MountStatus**. **Note** To view these registry keys, you must have Microsoft .NET Framework version 4.7.2 or later installed on your image. | Value | Description | | --- | --- | | 0 | Storage connector not be enabled for this user | | 1 | Storage connector mounting is in progress | | 2 | Storage connector mounted successfully | | 3 | Storage connector mounting failed | | 4 | Storage connector mounting is enabled, but not mounted yet | ## Enable Amazon S3 Bucket Storage for Session Script Logs When you enable Amazon S3 logging in your session script configuration, WorkSpaces Pool captures standard output from your session script. The output is periodically uploaded to an S3 bucket within your Amazon Web Services account. For every AWS Region, WorkSpaces Pool creates a bucket in your account that is unique to your account and the Region. You do not need to perform any configuration tasks to manage these S3 buckets. They are fully managed by the WorkSpaces service. The log files that are stored in each bucket are encrypted in transit using Amazon S3's SSL endpoints and at rest using Amazon S3-managed encryption keys. The buckets are named in a specific format as follows: ``` wspool-logs---random-identifier ``` **``** This is the AWS Region code in which the WorkSpaces Pool is created with Amazon S3 bucket storage enabled for session script logs. **``** Your Amazon Web Services account identifier. The random ID ensures that there is no conflict with other buckets in that Region. The first part of the bucket name, `wspool-logs`, does not change across accounts or Regions. For example, if you specify session scripts in an image in the US West (Oregon) Region (`us-west-2`) on account number `123456789012`, WorkSpaces Pool creates an Amazon S3 bucket within your account in that Region with the name shown. Only an administrator with sufficient permissions can delete this bucket. ``` wspool-logs-us-west-2-1234567890123-abcdefg ``` Disabling session scripts does not delete log files stored in the S3 bucket. To permanently delete log files, you or another administrator with adequate permissions must do so by using the Amazon S3 console or API. WorkSpaces Pools adds a bucket policy that prevents accidental deletion of the bucket. When session scripts are enabled, a unique folder is created for each streaming session that is started. The path for the folder where the log files are stored in the S3 bucket in your account uses the following structure: ``` //////SessionScriptsLogs/ ``` ****** The name of the S3 bucket in which the session scripts are stored. The name format is described earlier in this section. ****** The name of the stack the session came from. ****** The name of the WorkSpaces Pool the session script is running on. ****** The identity method of the user: `custom` for the WorkSpaces API or CLI, `federated` for SAML, and `userpool` for users in the user pool. ****** The user-specific folder name. This name is created using a lowercase SHA-256 hash hexadecimal string generated from the user identifier. ****** The identifier of the user's streaming session. Each user streaming session generates a unique ID. ****** The event that generated the session script log. The event values are: `SessionStart` and `SessionTermination`. The following example folder structure applies to a streaming session started from the test-stack and test-fleet. The session uses the API of user ID `testuser@mydomain.com`, from an AWS account ID of `123456789012`, and the settings group `test-stack` in the US West (Oregon) Region (`us-west-2`): ``` wspool-logs-us-west-2-1234567890123-abcdefg/test-stack/test-fleet/custom/a0bcb1da11f480d9b5b3e90f91243143eac04cfccfbdc777e740fab628a1cd13/05yd1391-4805-3da6-f498-76f5x6746016/SessionScriptsLogs/SessionStart/ ``` This example folder structure contains one log file for a user context session start script, and one log file for a system context session start script, if applicable.