# Import Image
You can create WorkSpaces Applications images by importing your customized EC2 AMIs. Here's how it works:
1. Customize your EC2 AMI using any preferred method including [EC2 Image Builder](https://docs.aws.amazon.com/imagebuilder/).
1. Import your customized AMI into WorkSpaces Applications to create a WorkSpaces Applications image
1. Optionally, use Image Builder for additional image customization
Images created through AMI import are of `type = "custom"`, while WorkSpaces Applications provided images are of `type = "native"`.
You can use stream.\$1 instance types for images with `type = "native"`. To use any of the following instance type you must import your AMI and create an image with `type = "custom"`.
+ GeneralPurpose.\$1
+ MemoryOptimized.\$1
+ ComputeOptimized.\$1
+ Accelerated.\$1
## Prerequisites for image import
All these prerequisites are important for a successful workflow execution. Supported AMI configurations and other mandatory requirements are listed below.
### Required AMI Properties
EBS
+ Less or equal to 500GB size
+ You can import an AMI with < 200 GB, however, the imported image will use minimum 200GB.
+ GP2
+ You can import an AMI with gp2 or gp3 EBS volume type, however, the imported image will use gp2.
+ One volume per image
+ `/dev/sda1` Root Device Name
+ Image Type: Machine
+ Architecture: x86\$164
+ Virtualization Type: HVM
+ Boot Mode: UEFI
+ TPM Support: v2.0. This is required, Refer to [https://docs.aws.amazon.com/ec2/latest/windows-ami-reference/ami-windows-tpm.html\$1ami-windows-tpm-find](https://docs.aws.amazon.com/ec2/latest/windows-ami-reference/ami-windows-tpm.html#ami-windows-tpm-find) to find a TPM enabled AMI.
+ ENA Support: true
+ Platform: Windows
+ Platform Details: Windows
### Operating System Properties
Windows Server 2022/2025 **Full Base**
+ Windows Server **Core** is not supported
+ Windows with SQL Server is not supported
Agents
+ EC2 Launch V2 Version >= 2.1.1
+ SSM Agent required
Drivers
+ EC2 ENA Driver Version >= 2.9.0
+ EC2 NVMe Driver Version >= 1.6.0
Library Support
+ .NET Framework 4.8 or greater
+ Installed by default in Windows Server 2022/2025
+ PowerShell 5.1 or greater
+ Installed by default in Windows Server 2022/2025
+ Windows Features: Remote Desktop Services Licensing and Remote Desktop Services Session Host must not be installed
+ Ports: Ports 8000, 8300, and 8443 must be unblocked and unoccupied
+ Boot Mode: UEFI
If you want to use image with graphics instances such as Accelerated.g4dn, Accelerated.g5, Accelerated.G6, or Accelerated.G6e you much install proper GRID driver on your AMI. For more details please refer to [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nvidia-GRID-driver.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nvidia-GRID-driver.html). If the drivers are not setup correctly the streaming will work, however, graphics card may not available.
**Important**
"Owner Account Id" of the AMI must be your AWS account id. You cannot import a public EC2 AMI.
Perform any Windows updates and disable automatic Windows updates before importing the image.
Import of encrypted EC2 AMIs is currently not supported
### IAM Role Requirements
**Important**
"Create an IAM role with the following permissions to use for image import:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowModifyImageAttributeWithTagCondition",
"Effect": "Allow",
"Action": "ec2:ModifyImageAttribute",
"Resource": "*"
},
{
"Sid": "AllowDescribeImages",
"Effect": "Allow",
"Action": "ec2:DescribeImages",
"Resource": "*"
}
]
}
```
Add the following trust relationship for this IAM role
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "appstream.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
## To import an image
1. Open the WorkSpaces Applications console at [https://console.aws.amazon.com/appstream2](https://console.aws.amazon.com/appstream2).
1. In the left navigation pane, choose **Images** and then choose **Image registry**.
1. Choose **Import Image**.
1. **AMI ID** - Enter an AMI ID for AMI that you would like to import to WorkSpaces Applications. You can also search for your AMI using this field.
1. **Image name** - Enter a unique name for the image that will be created because of import operation.
1. **Display name** *(Optional)* - Enter a to display for the image.
1. **Description** *(Optional)* – Enter a description for the image.
1. **IAM Role** - Select the IAM role that you have created for image import. For more details refer to [IAM Role Requirements](#iam-role-requirements).
1. **Manage WorkSpaces Applications agent** – Select this option if you want to always use the latest WorkSpaces Applications agent version, your streaming instances are automatically updated with the latest features, performance improvements, and security updates that are available from AWS when a new agent version is released.
1. **Runtime validation** *(Optional)*: Select this option and service will provision an instance with the image being imported and run streaming tests.
+
**Note**
These streaming tests will be executed in the background, you cannot connect to this instance via WorkSpaces Applications client.
+ We recommend using this option to get higher confidence that your image is suitable for WorkSpaces Applications.
+ You will be billed for the hourly price of that instance.
+ You can avoid running runtime validation if you are re-importing your AMI after making minor changes that may not affect the streaming test, and if runtime validation passed the last time, you imported this AMI.
+ **Choose instance type** *(Optional)*: Select the right instance family, type, and size for running the streaming test. It is recommended that you use the same instance which you are planning to use for fleet creation.
1. **Applications catalog and launch performance manifest** *(Optional)*: Provide details to create applications catalog for your end users and improve the launch performance of your applications.
+ **Application catalog**: To create an application catalog specify details about the applications installed your image. For each application that you plan to stream, you can specify the name, display name, executable file to launch, and icon to display.
+ **Launch performance**: Adding files to the application optimization manifest reduces the time that it takes for the application to launch for the first time on a new fleet instance. The optimization manifest is a line-delimited text file that is per application.
To learn more refer to [Applications Details](applications-details.md).
1. **Tags** *(Optional)* - Choose **Add Tag** and type the key and value for the tag. To add more tags, repeat this step. For more information, see [Tagging Your Amazon WorkSpaces Applications Resources](tagging-basic.md).
1. **Import Image** – Review all the information you have entered and choose **Import Image**. Service will run compatibility checks to make sure AMI is compatible with WorkSpaces Applications.
+ If the static checks fail, you will receive an error straight away.
+ If the static checks pass, your import request will be submitted and depending upon the options you have selected it could take 30-60 min to create a new WorkSpaces Applications image with `type = "custom"`
# Applications Details
Applications details contains information about pre-warm manifests and app catalog configurations.
## Application PreWarm Manifests
When creating WorkSpaces Applications images you may specify applications to be made available to your users. To speed up the application's launch time you can prepare a PreWarm manifest. This is essentially a catalog of the files that your application needs to launch when users launch your application. During instance provisioning these files will be prepared ahead of session connections to speed up application launch times in user sessions.
Prewarm manifests must be pre-created on your AMI before being imported into the WorkSpaces Applications environment. You can choose to either create one common Prewarm manifest file or one per each application. This changes how you will import your AMI later.
### Common Prewarm Manifest
For each application you wish to prewarm, launch the application and perform any initial interactions your users may perform. Then, use the following command targeting the directory where your applications data is stored.
```
dir -path "C:\Path\To\Folder\To\Optimize" -Recurse -ErrorAction SilentlyContinue | %{$_.FullName} | Out-File "C:\ProgramData\Amazon\Photon\Prewarm\PrewarmManifest.txt" -encoding UTF8 -append
```
This will append the files to optimize for each application into the common `C:\\ProgramData\\Amazon\\Photon\\Prewarm\\PrewarmManifest.txt` file. There is no additional action needed to perform application prewarming. WorkSpaces Applications will look for the prewarm file at the above location and use it if it is present.
This process is optional and as the size of the prewarm manifest increases, fleet provisioning time will also increase. So take care to balance optimization with fleet provisioning.
### Application Specific Manifests
During image import, you may wish to specify separate application manifest files per application for easier tracking of the prewarm assets per application. To do this perform the same steps as above, but instead of creating a common `C:\\ProgramData\\Amazon\\Photon\\Prewarm\\PrewarmManifest.txt` file, create a file per application on your AMI.
For each application you wish to prewarm, launch the application and perform any initial interactions your users may perform. Then, use the following command targeting the directory where your applications data is stored.
```
dir -path "C:\Path\To\Folder\To\Optimize" -Recurse -ErrorAction SilentlyContinue | %{$_.FullName} | Out-File "C:\Path\To\My\PreWarm.txt" -encoding UTF8 -append
```
We will use these application prewarm files during the image import process. Again this is completely optional. You may choose to use this method, the Common Prewarm Manifest method, or no Prewarm manifest at all.
## Application Catalog Configs
`AppCatalogConfig` which allows you to specify the applications you wish to register to your WorkSpaces Applications image during AMI import. The `AppCatalogConfig` is a JSON list of Application configuration objects of the following structure.
```
[
{
"Name": "Rufus", //Required and must be unique among the list of applications
"DisplayName": "Rufus",
"AbsoluteAppPath": "Rufus", //Required
"AbsoluteIconPath": "Rufus",
"AbsoluteManifestPath": "Rufus",
"WorkingDirectory": "Rufus",
"LaunchParameters": "Rufus"
}
...
// Up to 50 applications total
]
```
The only required fields per application are the `Name` and the `AbsoluteAppPath`. The details of each field as follows:
Name [**Required**]
+ A given name for your application to identify it
+ Between 1 and 100 characters
+ Allowed characters regex `^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,99}$`
+ Must be unique in a given AppCatalogConfig
DisplayName
+ The display name for a given application to display to users
+ Between 0 and 100 characters
+ Allowed characters regex `^[a-zA-Z0-9][a-zA-Z0-9_. -]{0,99}$`
AbsoluteAppPath [**Required**]
+ The path to the executable to launch your application
+ This is the executable that will be launched when users select your application
+ Between 1 and 32767 characters
+ This character length upper limit is to support extended file paths in Windows. Ensure your AMI and application is properly configured to support Windows extended file paths if using file paths larger than 260 characters.
+ Use escaped file path strings such as
+ `"C:\\Windows\\System32\\notepad.exe"`
AbsoluteManifestPath
+ Only applicable if you are using [Application Specific Manifests](#application-specific-manifests)
+ Path to prewarm manifest file for this application
+ Between 0 and 32767 characters
+ This character length upper limit is to support extended file paths in Windows. Ensure your AMI and application is properly configured to support Windows extended file paths if using file paths larger than 260 characters.
+ Use escaped file path strings such as
+ `"C:\\Path\\To\\PrewarmManifest.txt"`
AbsoluteIconPath
+ Path to icon file on the AMI to use for the application.
+ This icon will be shown to users when streaming to this image.
+ If none is provided the icon will be derived from the executable itself.
+ Take care to select icon files with appropriately handled background transparency for a good client experience for your users
+ Use PNG images
+ Between 1 and 32767 characters
+ This character length upper limit is to support extended file paths in Windows. Ensure your AMI and application is properly configured to support Windows extended file paths if using file paths larger than 260 characters.
+ Use escaped file path strings such as
+ `"C:\\Path\\To\\ApplicationIcon.png"`
WorkingDirectory
+ The working directory to launch your application in
+ Between 0 and 32767 characters
+ This character length upper limit is to support extended file paths in Windows. Ensure your AMI and application is properly configured to support Windows extended file paths if using file paths larger than 260 characters.
+ Use escaped file path strings such as
+ `"C:\\Path\\To\\Working\\Directory"`
LaunchParameters
+ A string to use as the launch parameters for the executable specified in `AbsoluteAppPath`
+ Between 0 and 1024 characters
+ Use escaped strings with the full list of required launch parameters such as the following example which shows how you may use PowerShell scripts as your applications by using the PowerShell executable as your app with a script provided in the launch parameters
+ AbsoluteAppPath
+ `"C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"`
+ LaunchParameters
+ `"-File \"C:\\Path\\To\\App\\Script.ps1\""`
### Sample AppCatalogConfig
This is a bare bones example of an AppCatalogConfig for Notepad, Google Chrome, and Mozilla Firefox
```
[
{
"Name": "Notepad",
"DisplayName": "Notepad",
"AbsoluteAppPath": "C:\\Windows\\System32\\notepad.exe"
},
{
"Name": "Chrome",
"DisplayName": "Chrome",
"AbsoluteAppPath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
"LaunchParameters": "https://www.amazon.com/"
},
{
"Name": "Firefox",
"DisplayName": "Firefox",
"AbsoluteAppPath": "C:\\Program Files\\Mozilla Firefox\\firefox.exe",
"LaunchParameters": "https://aws.amazon.com/"
}
]
```