How do I share WorkSpaces images or BYOL images with other AWS accounts?

Resolution

You can share custom WorkSpaces images across AWS accounts within the same Region. After your share a WorkSpaces image, the recipient account can copy the image to other Regions as needed. To self-manage WorkSpaces image transfers, use the WorkSpaces console or the AWS Command Line Interface (AWS CLI).

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

BYOL images can be shared only with other accounts with the same AWS payer account ID. To copy a BYOL image to another Region, the destination Region must be set up for BYOL images.

Share an image using the WorkSpaces console

Use the WorkSpaces console to share or unshare an image with other accounts in the same Region. For instructions, see Share or unshare a custom image in WorkSpaces Personal.

Share an image using the AWS CLI

Share or unshare images programmatically using API calls and the AWS CLI.

Important: In the following process, the commands require version 2 of the AWS CLI. For installation instructions, see Installing or updating to the latest version of the AWS CLI.

To copy a WorkSpaces image to a different account within the same Region, complete the following steps:

1. From the source account, identify the image ID for the source image. Run the following command, and replace region-code with the WorkSpaces Region code:

   aws workspaces describe-workspace-images --region region-code

   Then, note the ImageId from the output.

2. From the source account, call the UpdateWorkspaceImagePermission API to share the source image with the target account. Run the following command, and replace ImageId with the output from step 1. Also, replace region-code with the WorkSpaces Region code, and target-account with the target account number:

   aws workspaces update-workspace-image-permission --image-id ImageId --region region-code --shared-account-id target-account --allow-copy-image

3. (Optional) From the source account, call the DescribeWorkspaceImagePermissions API to see the permissions and verify that the image is shared with the target account. Run the following command, and replace ImageId and region-code with your values:

   aws workspaces describe-workspace-image-permissions --image-id ImageId --region region-code

4. (Optional) From the target account, call the DescribeWorkspaceImages API to see the shared image. Run the following command, and replace ImageId and region-code with your values:

   aws workspaces describe-workspace-images --image-ids ImageId --region region-code --image-type SHARED

5. From the target account, call the CopyWorkspaceImage API to copy the shared image. Run the following command, and replace ImageId and region-code with your values. Also, replace new-image-name with the name that you want to use for the image on the target account:

   aws workspaces copy-workspace-image --source-image-id ImageId --source-region region-code --name new-image-name --region region-code

   The target account can now see the new image in the WorkSpaces console. It typically takes about 15 minutes for the workflow to complete and for the image state to move from Pending to Available.

Related information

How do I create a WorkSpaces image?

Copy a custom image in WorkSpaces Personal