Desktop and Application Streaming

Automatically create customized AppStream 2.0 Linux images

Customers often ask how they can streamline the management and maintenance of their Amazon AppStream 2.0 images and fleets. In a previous post, I walked you through automatically creating customized AppStream 2.0 images running Microsoft Windows. Late last year, Amazon AppStream 2.0 introduced support for Amazon Linux 2 based images and fleets. This brought the same ability to securely stream Linux applications and desktops to users as well as the same customer ask to efficiently manage their environment. In this blog article, I walk you through how to set up a serverless automation pipeline to create a customized AppStream 2.0 Amazon Linux 2 (AL2) based image.


The automation creates a fresh image builder instance and establishes remote access using secure shell (SSH) keys that are stored securely in AWS Systems Manager parameter store. Then, it installs software packages and runs commands to customize the image. It then creates an AppStream 2.0 image using the built-in Image Assistant utility. Once complete, it sends a notification email with the results. To further simplify the process, the automation will attempt to dynamically generate the optimization manifest for each application if you do not provide one yourself.

In this blog, I provide examples of using install packages hosted in an Amazon managed repository, as well as off the internet. These allow you to setup and test the pipeline, and can be replaced later to customize the image for your environment.

Diagram outlining how the various services used within the workflow connect. Step Functions talk to Lambda and AppStream. Lambda talks to AppStream, Step Functions, Systems Manager and SNS. EventBridge talks to SNS.

Time to read 15 minutes
Time to complete 1 hour
Cost to complete (estimated) $5
Learning level Advanced (300)
Services used Amazon AppStream 2.0
Amazon EventBridge
Amazon Simple Notification Service
AWS CloudFormation
AWS Lambda
AWS Systems Manager
AWS Step Functions


In this article, you complete the following tasks:

  1. Use a CloudFormation template to create the required components to build the AppStream 2.0 image creation automation pipeline.
  2. Create a base image configured to accept remote commands.
  3. Run the automation to build a fully automated and customized Amazon Linux 2 based AppStream 2.0 image.


This article assumes that you have the following already in place:

  • An AWS account setup for Amazon AppStream 2.0 and IAM permissions to create AppStream 2.0 image builders and images.
  • Permissions to create the following service components:
    • AWS IAM roles and policies
    • AWS Lambda functions
    • AWS Step Functions
    • AWS Systems Manger parameters
    • Amazon EventBridge rules
    • Amazon Simple Notification Service topics and subscriptions
    • Amazon S3 buckets
  • Permissions to run AWS CloudFormation templates.
  • Connectivity to the internet from the image builder subnets to download application packages and access AWS Systems Manager.
  • Download and extract the files required in this guide from the project’s latest Linux release on GitHub to your desktop.

Step 1: Place automation deployment files into an Amazon S3 bucket

  1. Navigate to the Amazon S3 console.
  2. Choose Create bucket.
  3. Enter a unique name for the bucket, and select the Region. The Region does not have to be the same Region where AppStream 2.0 resides.
  4. Keep the defaults for the rest of the options.
  5. Choose Create bucket.
  6. Select the newly created bucket
  7. Choose Upload.
  8. Choose Add files. . Select the entire contents of the INSTALL folder extracted to your desktop from the release ZIP file downloaded from the project’s GitHub repository. Be sure to include the four .ZIP files containing the Lambda function Python code and the fifth .ZIP containing the paramiko library Lambda layer. Do not unzip these files.
  9. Choose Upload.
  10. Once complete, choose Close.

Step 2: Create base image with SSH key

The key to the entire application automation process is to establish a known user account and SSH key within the image builder operating system. This user and key are utilized to issue remote commands from the Lambda functions. Below is the one-time manual process required to create a base image for use with this automation workflow. In addition, the key is stored in AWS Systems Manager for safe storage and programmatic retrieval.

Step a: Create an image builder

  1. Follow the steps in the Amazon AppStream 2.0 administration guide to launch an image builder, ensure you select an Amazon Linux 2 based image.

Step b: Deploy the image configuration script

  1. Once the image builder enters the Running status, select the radio button and choose Connect.
  2. Select the option to upload a file on the AppStream 2.0 toolbar.

  1. Select Temporary Files, and Upload Files.
  2. In the file picker, select the script provided with the workshop. Choose Open. This script is found within the RUN folder previously extracted to your desktop from the release .ZIP file.
  3. Once uploaded you will see the file listed in the Temporary Files folder. Close the My Files interface.
  4. Launch a terminal window by choosing Applications in the top left corner of the desktop and then Terminal.
  5. Within the terminal window, run the following commands. First you configure the file to be executable. Then you run the script to configure the as2-automation user account and generate the SSH keys.
    chmod +x /home/ImageBuilderAdmin/MyFiles/TemporaryFiles/
  6. Choose My Files from the AppStream 2.0 toolbar again.
  7. Select Temporary Files, then as2-automate.pem.
  8. This will initiate a file download within your web browser. Save the file to your desktop for a later step.
  9. Back in the terminal window inside the image builder, run the following command to clean up the temporary files:
    rm /home/ImageBuilderAdmin/MyFiles/TemporaryFiles/as2-* -f
  10. Navigate to the AWS Systems Manager console in the Region with the AppStream 2.0 image.
  11. Select Parameter Store under Application Management.
  12. Choose Create parameter.
  13. For Name, enter /as2_automation/sshkey.
  14. For Type, choose SecureString.
  15. In a text editor, open the as2-automate.pem file on your desktop.
  16. Select and copy the entire contents of the file.
  17. Back in the Create Parameter page, paste the contents of the .pem file within the Value box.
  18. Choose Create parameter.

Step c: Create a base image

Now that we have created a local account within the Amazon Linux 2 image builder and successfully stored the SSH key as an AWS Systems Manager parameter, we must create a new base image that will be used as part of the automation.

  1. Back on the image builder console, within the terminal window, run the following command to create your new base image:
    sudo AppStreamImageAssistant create-image --name Linux_Automation_Base
  2. You should see a success message briefly appear in the terminal window before you are disconnected from the session.

Step 3: Deploy the AWS CloudFormation template

A CloudFormation template deploys the AppStream 2.0 image creation pipeline. It creates all the components and security definitions required.

  1. Navigate to the AWS CloudFormation console in the Region with the AppStream 2.0 image.
  2. Choose Create stack then With new resources (standard).
  3. Select Upload a template file then Choose file.
  4. Select AS2-Automation-Linux-CloudFormation.yaml from the release .ZIP.
  5. Choose Next.
  6. For name, enter AppStream2-Linux-Pipeline.
  7. Complete the template parameters.
    1. AS2DefaultImage – enter the name of the default base AppStream 2.0 image to use for automations. This should be the customized image created in step 2, Linux_Automation_Base.
    2. AS2DefaultSSHKeyARN – enter the ARN of the AWS Systems Manager parameter created in step 2 that contains the encrypted SSH key. The format should be as follows, replacing the three items in red with your values: arn:aws:ssm:<region>:<account-id>:parameter/<parameter_name>
    3. AS2VPCId – select the VPC where the image builder and Lambda functions will be deployed into.
    4. AS2VPCSubnet1 and AS2VPCSubnet2 – select the two subnets where the Lambda functions will be deployed into.
    5. SNSEmailSubscriptionEndPoint – Email address to receive completion notification.
    6. SourceS3Bucket – the name of the S3 bucket created in step 1 where the .zip files were uploaded.
  8. Choose Next.
  9. On the Configure stack options page, choose Next.
  10. On the review page, select the box I acknowledge that AWS CloudFormation might create IAM resources with custom names.
  11. Choose Create stack.
  12. After a few moments, the email address entered into SNSEmailSubscriptionEndPoint will receive a subscription notification email from AWS Notifications.
  13. Select Confirm subscription in that email before the final email from the automations can be sent.

Step 4: Test the image creation pipeline

  1. Navigate to the AWS Step Functions console.
  2. Under State machines, select the AS2_Automation_Linux state machine created by the CloudFormation template and choose View details.
  3. Choose Start execution.
  4. For Name, enter AS2-Automation-Linux-Test.
  5. Replace the contents of the Input field with the following JSON statement.
  "ImageBuilderName": "AS2_Automation_Linux_Test",
  "ImageBuilderType": "stream.standard.medium",
  "ImageOutputPrefix": "AS2_Automation_Linux_Test",
  "DeleteBuilder": true,
  "ImageBuilderCommands": [
    "sudo yum -y update",
    "sudo amazon-linux-extras install gimp -y",
    "sudo AppStreamImageAssistant add-application --name Gimp --absolute-app-path /usr/bin/gimp --display-name Gimp",
    "sudo yum -y install putty",
    "sudo AppStreamImageAssistant add-application --name PuTTY --absolute-app-path /usr/bin/putty --display-name PuTTY",
    "mkdir /tmp/LibreOfficeInstall",
    "wget -P /tmp",
    "tar -C /tmp/LibreOfficeInstall -xvf /tmp/LibreOffice_*_Linux_x86-64_rpm.tar.gz",
    "sudo yum -y localinstall /tmp/LibreOfficeInstall/LibreOffice_7.5.0*/RPMS/*.rpm",
    "sudo rm /tmp/LibreOffice_7.5.0_Linux_x86-64_rpm.tar.gz -f",
    "sudo rm -r -f /tmp/LibreOfficeInstall",
    "sudo AppStreamImageAssistant add-application --name LibreWriter --absolute-app-path /opt/libreoffice7.5/program/oosplash --display-name Writer --absolute-icon-path /usr/share/icons/hicolor/128x128/apps/libreoffice7.5-writer.png --launch-parameters='-writer'",
    "sudo AppStreamImageAssistant add-application --name LibreCalc --absolute-app-path /opt/libreoffice7.5/program/oosplash --display-name Calc --absolute-icon-path /usr/share/icons/hicolor/128x128/apps/libreoffice7.5-calc.png --launch-parameters='-calc'",
    "sudo AppStreamImageAssistant add-application --name LibreImpress --absolute-app-path /opt/libreoffice7.5/program/oosplash --display-name Impress --absolute-icon-path /usr/share/icons/hicolor/128x128/apps/libreoffice7.5-impress.png --launch-parameters='-impress'"
  1. The previous parameters will run the AWS Step Functions state machine resulting in an AppStream 2.0 private image named AS2_Automation_Linux_Test-<timestamp>. The pipeline will install Gimp, PuTTY, and LibreOffice and add each to the AppStream 2.0 application catalog. Once complete the state machine will delete the image builder used to create the image.
  2. Choose Start execution.
  3. The state machine status can be monitored in the console.
  4. Once completed, you receive an email notification at the address specified when deploying the solution. The new image will be in the AppStream 2.0 console under Images. Additionally, if the automation encounters an issue that results in a failed status, this event will trigger an Amazon EventBridge rule to notify you.

For greater flexibility, the automation workflow accepts additional parameters by adding to the JSON statement in step 5. For more information on customization and next steps, review the readme on the GitHub repository.


In this blog post, you created several components that may generate costs based on usage. To avoid incurring future charges, remove the following resources.

  1. Remove the S3 buckets used to store the .zip files containing the Lambda function .ZIP files imported with CloudFormation.
    1. Navigate to the Amazon S3 console.
    2. Select the bucket created in step 1.
    3. Select all the objects inside the bucket and choose Delete.
    4. Confirm the deletion and choose Delete objects.
    5. Once the bucket is empty, return to the Amazon S3 bucket page.
    6. Select the bucket and choose Delete.
    7. Confirm the deletion and choose Delete bucket.
  2. Remove any AppStream 2.0 images created from the automation.
    1. Navigate to the AppStream 2.0 console.
    2. Select Images.
    3. Filter the image registry to custom images: Visibility = Private.
    4. Select the image to delete and click Action then Delete.
    5. Repeat for any additional images created using the automation that are no longer needed.
  3. Remove any AppStream 2.0 image builders created by the automation.
    1. Navigate to the AppStream 2.0 console.
    2. Select Images.
    3. Select the Image Builder tab.
    4. Select the image builder to delete and click Action then Delete.
    5. Repeat for any additional image builders left behind from the automation that are no longer needed.
  4. Remove all the remaining resources created by the CloudFormation template:
    1. Navigate to the CloudFormation console.
    2. Select the stack created in step 3, AppStream2-Linux-Pipeline.
    3. Choose Delete. This will automatically delete the other resources used in the solution.


You now have a fully automated pipeline to create Amazon Linux 2 based AppStream 2.0 images. I have included sample applications as part of this article to demonstrate the pipeline. You should now replace the example commands with those required to install your required applications and configurations to the image.

By using automation to streamline the process of creating images for your AppStream 2.0 fleets you can increase operational efficiency, eliminate human error and increase consistency, and quickly build new images and update your applications.