search

aws-samples / appstream-serverless-image-creation-automation

This repository contains the file associated with the Amazon AppStream 2.0 Serverless Image Automation blog posts.
MIT No Attribution
10 stars 6 forks source link

readme

security: bandit cfn_nag:passing GitHub

Amazon AppStream 2.0 Serverless Image Automation for Windows

Customers often ask how they can streamline the management and maintenance of their Amazon AppStream 2.0 images and fleets. The AppStream 2.0 service includes a rich set of APIs that allow you to programmatically interact with the service. In addition, the Image Assistant utility within the image builder instances supports command line interface (CLI) operations for adding applications to the fleet and creating images. What we commonly see is customers struggle with linking the two together; interacting with the service external to the image builder and running commands programmatically within the Microsoft Windows guest operating system within.

This repository contains the supporting scripts for the AWS Desktop and Application Streaming blog article Automatically create customized AppStream 2.0 Windows images. Please refer to the blog article for guidance on deploying the solution.

Solution Diagram for Windows Image Builders

Once you have successfully deployed the solution and ran the sample automation pipeline, you should customize the applications installed into the image and the parameters of the workflow to meet your needs.

Customizing Executions of Step Function

For any parameters not specified in the Step Function execution JSON, a default value will be used. These default values can be viewed and/or modified on the Lambda function that creates the image builder.

  1. Navigate to the AWS Lambda console and select Functions.
  2. Click on the AS2_Automation_Windows_FN01_CreateBuilder######## function.
  3. Select the Configuration tab.
  4. Select Environment variables.
  5. To change a default value, click Edit, modify the value, and click Save.

Default values were entered when the automation was deployed from CloudFormation. These values are used as inputs into the Step Function running the automation and the below parameters can be passed into the Step Function to override them. Options include:

An example JSON statement used to start an execution of the automation Step Function can be found below. In this example, several of the above parameters are entered to control the behavior of the automation. The resulting image will be named "AS2_Automation_Windows_Example_TIMESTAMP", uses a stream.standard.large instance size, and will ensure the latest version of the AppStream agent is installed. It also tags the image, places the image builder into the Image_Builders OU in the Active Direcotry domain yourdomain.int, and runs two PowerShell commands to set two registry key values.

{
    "ImageBuilderName": "AS2_Automation_Windows_Example",
    "ImageBuilderType": "stream.standard.large",
    "ImageOutputPrefix": "AS2_Automation_Windows_Example",
    "ImageBuilderDomain": "yourdomain.int,
    "ImageBuilderOU": "OU=Image_Builders,OU=AppStream,DC=yourdomain,DC=int",
    "UseLatestAgent": true,
    "ImageTags": "'tag1' 'value1' 'tag2' 'value2'",
    "DeleteBuilder": true,
    "ImageBuilderExtraCommands": [
      "New-Item -Path 'HKLM:/Software/AS2-Automation-Pipeline' -Force;New-ItemProperty -Path 'HKLM:/Software/AS2-Automation-Pipeline' -Name 'TestValue' -Value 'Success' -PropertyType String -Force",
      "New-ItemProperty -Path 'HKLM:/Software/AS2-Automation-Pipeline' -Name 'TestValue2' -Value 'Success' -PropertyType String -Force"
    ]
}

Customizing Installation Packages

While the sample applications included as part of this article are useful in demonstrating the workflow, you should now update the packages and scripts to reflect the applications required in your image(s).

  1. Use the existing packages provided with the workshop as a template when creating or modifying your own install routines. In particular, your install routines need to ensure that they are adding the application to the AppStream Image Assistant catalog. Please refer to the CLI documentation for additional details about programmatically adding applications to the catalog.

Below is the relevant section of PowerShell code in the sample install scripts that you can use when creating your own application install packages:

    ##*===============================================
    ##* APPSTREAM VARIABLE DECLARATION
    ##*===============================================
    [string]$AppName = 'Notepad++'
    [string]$AppPath = 'C:\Program Files\Notepad++\notepad++.exe'
    [string]$AppDisplayName = 'Notepad++'
    [string]$AppParameters = ''
    [string]$AppWorkingDir = ''
    [string]$AppIconPath =  ''
    [string]$ManifestPath = $PSScriptRoot + '\NotepadPPManifest.txt'

    [string]$ImageAssistantPath = "C:\Program Files\Amazon\Photon\ConsoleImageBuilder\image-assistant.exe"

    ##*===============================================
    ##* ADD APPLICATION TO APPSTREAM CATALOG
    ##*===============================================
    #AppStream's Image Assistant Required Parameters
    $Params = " --name " + $AppName + " --absolute-app-path """ + $AppPath + """"     

    #AppStream's Image Assistant Optional Parameters
    if ($AppDisplayName) { $Params += " --display-name """ + $AppDisplayName + """" }
    if ($AppWorkingDir) { $Params += " --working-directory """ + $AppWorkingDir + """" }
    if ($AppIconPath) { $Params += " --absolute-icon-path """ + $AppIconPath + """" }      
    if ($AppParameters) { $Params += " --launch-parameters """ + $AppParameters + """" }     
    if ($ManifestPath) { $Params += " --absolute-manifest-path """ + $ManifestPath + """" }

    #Escape spaces in EXE path
    $ImageAssistantPath = $ImageAssistantPath -replace ' ','` '

    #Assemble Image Assistant API command to add applications
    $AddAppCMD = $ImageAssistantPath + ' add-application' + $Params

    Write-Host "Adding $AppDisplayName to AppStream Image Catalog using command $AddAppCMD"

    #Run Image Assistant command and parameters
    $AddApp = Invoke-Expression $AddAppCMD | ConvertFrom-Json
    if ($AddApp.status -eq 0) {
        Write-Host "SUCCESS adding $AppName to the AppStream catalog."
    } else {
        Write-Host "ERROR adding $AppName to the AppStream catalog." 
        Write-Host $AddApp.message
  1. Once you have created your own application install packages, upload them to the Amazon S3 bucket created by the CloudFormation template.
  2. Navigate to the AWS Lambda console and select Functions.
  3. Choose the AS2_Automation_Windows_FN02_ScriptedInstall######## function.
  4. In the Code source section, scroll down to the line 77 in the default script. The line of hash marks outlines the beginning and end of each application install section.
  5. Modify or replace the sections for the sample applications referencing your own packages in Amazon S3 or downloaded off the web.
  6. Once complete, click Deploy to make the updated code active for the next execution of the Lambda function.

Amazon AppStream 2.0 Serverless Image Automation for Linux

In 2021, 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 that had been available for Windows based workloads.

This repository contains the supporting scripts for the AWS Desktop and Application Streaming blog article Automatically create customized AppStream 2.0 Linux images. Please refer to the blog article for guidance on deploying the solution.

Solution Diagram for Linux Image Builders

Once you have successfully deployed the solution and ran the sample automation pipeline, you should customize the applications installed into the image and the parameters of the workflow to meet your needs.

Customizing Executions of Step Function

For any parameters not specified in the Step Function execution JSON, a default value will be used. These default values can be viewed and/or modified on the Lambda function that creates the image builder.

  1. Navigate to the AWS Lambda console and select Functions.
  2. Click on the AS2_Automation_Linux_FN01_CreateBuilder######## function.
  3. Select the Configuration tab.
  4. Select Environment variables.
  5. To change a default value, click Edit, modify the value, and click Save.

Default values were entered when the automation was deployed from CloudFormation. These values are used as inputs into the Step Function running the automation and the below parameters can be passed into the Step Function to override them. Options include:

An example JSON statement used to start an execution of the automation Step Function can be found below. In this example, several of the above parameters are entered to control the behavior of the automation. The image will be named "AS2_Automation_Linux_Example_TIMESTAMP", uses a stream.standard.large instance size, will ensure the latest version of the AppStream agent is installed, tags the image, and runs commands to ensure installed packages are up-to-date and that Gimp and PuTTY are installed. It will then attempt to create the optimization manifests for each app, will not remove the manifest file from /tmp afterwards (for admin review), and then adds each app to the AppStream application catalog.

{
    "ImageBuilderName": "AS2_Automation_Linux_Example",
    "ImageBuilderType": "stream.standard.large",
    "ImageOutputPrefix": "AS2_Automation_Linux_Example",
    "UseLatestAgent": true,
    "ImageBuilderCommands": ["sudo yum -y update", "sudo amazon-linux-extras install gimp", "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"],
    "CreateManifests": true,
    "DeleteTempManifests": false,
    "ImageTags": "'tag1' 'value1' 'tag2' 'value2'",
    "DeleteBuilder": true
}

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.