search

aws-samples / amazon-workspaces-serverless-image-creation-automation

This repository contains the file associated with the Amazon WorkSpaces serverless image automation blog post.
https://aws.amazon.com/blogs/desktop-and-application-streaming/automatically-create-customized-amazon-workspaces-windows-images/
MIT No Attribution
2 stars 1 forks source link

readme

security: bandit cfn_nag:passing GitHub

Amazon WorkSpaces Serverless Image Automation for Windows

Customers often ask how they can streamline the management and maintenance of their Amazon WorkSpaces images and bundles. The WorkSpaces service includes a rich set of API operations with which you can programmatically interact with the service. A common customer struggle is programmatically interacting with the operating system within the WorkSpace to install and configure applications to customize their image. In this blog, I walk you through how to set up a serverless automation pipeline to create a customized WorkSpaces Windows OS based image.

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

Solution Diagram for Windows Image Pipeline

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 WKS_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:

Customizing installation and configuration routine

The InstallRoutine JSON parameter defines the steps that run on your image builder WorkSpace such as installing software, runing commands, and configuring settings. These parameter is passed as a list of lists. There are currently four types of commands supported by the pipeline:

Below is a sample InstallRoutine value that downloads two files, one from S3 and one from the internet, runs the commands to silently install both, and sets a regitry key.

      "InstallRoutine" : [
        ["DOWNLOAD_S3","s3://wks-automation-installer-source-d3dcc6e0/putty/putty-installer.msi","c:\\wks_automation\\putty\\"],
        ["RUN_COMMAND","msiexec /i c:\\wks_automation\\putty\\putty-installer.msi /qn"],
                ["DOWNLOAD_HTTP","https://github.com/notepad-plus-plus/notepad-plus-plus/releases/download/v8.6/npp.8.6.Installer.x64.exe"],
        ["RUN_COMMAND","c:\\wks_automation\\npp.8.6.Installer.x64.exe /S"],
                ["RUN_POWERSHELL", "New-ItemProperty -Path HKLM:\\Software\\Amazon -Name Automated_Image -Value true -PropertyType String -Force"]

Windows Updates considerations

The image creation pipeline can optinally trigger Windows Updates utilizing the PSWindowsUpdate PowerShell module. You have the option to run the Windows Update portion of the workflow by including the SkipWindowsUpdates in the input JSON statement, and settings it to false. By default, your Windows WorkSpaces are configured to receive updates from directly from Microsoft via Windows Update over the internet. If you do not configure any Windows Updates settings with a GPO attached to your image creation OU, then your WorkSpaces will continue to receive approved updates from Microsoft. Alternatively, you can configure your own update mechanisms for Windows. See the documentation for Windows Server Update Services (WSUS) or the systems management platform you have in place for details.

Example JSON statement to start Step Function execution

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. Replace the XXXXXX with the S3 bucket you uploaded the PuTTY installer into. 

{
    "DeleteBuilder": true,
    "CreateBundle": true,
    "SkipWindowsUpdates": true,
    "ImageNamePrefix": "WKS_Blog_Test",
    "ImageTags": [
        {
            "Key": "Automation",
            "Value": "Test run"
        },
        {
            "Key": "Blog",
            "Value": "pipeline test"
        }
    ],
    "BundleNamePrefix": "WKS_Blog_Test",
    "BundleDescription": "This bundle uses an image containing Notepad++ and PuTTY.",
    "InstallRoutine": [
        [
            "DOWNLOAD_S3",
            "s3://wks-automation-installer-source-XXXXXX/putty/putty-installer.msi",
            "c:\\wks_automation\\putty\\"
        ],
        [
            "RUN_COMMAND",
            "msiexec /i c:\\wks_automation\\putty\\putty-installer.msi /qn"
        ],
        [
            "DOWNLOAD_HTTP",
            "https://github.com/notepad-plus-plus/notepad-plus-plus/releases/download/v8.6/npp.8.6.6.Installer.x64.exe"
        ],
        [
            "RUN_COMMAND",
            "c:\\wks_automation\npp.8.6.6.Installer.x64.exe /S"
        ],
        [
            "RUN_POWERSHELL",
            "New-Item -Path HKLM:\\Software\\AmazonBlog -Force"
        ],
        [
            "RUN_POWERSHELL",
            "New-ItemProperty -Path HKLM:\\Software\\AmazonBlog -Name Automated_Image -Value true -PropertyType String -Force"
        ]
    ]
}

These example parameters will run the AWS Step Functions state machine resulting in a customized WorkSpaces image and bundle named WKS_Blog_Test-timestamp. The image will have two tags applied to it, will have PuTTY and Notepad++ installed, and will have a registry key set. Once complete the state machine will delete the image builder WorkSpace used to create the image.

Troubleshooting the configuration routine

The configuration routine expects silent installs and properly formatted commands. That being said, there are times when you need to troubleshoot and investigate failures. The WKS_Automation_Windows_FN03_Configuration_Routine Lambda function writes each of the actions, and their results, to the CloudWatch log. Additionally, if any of the commands do not return a status code of 0, then they are considered a failure and the command and return code are added to InstallRoutineErrors list. This value is passed along the Step Function steps and you can view it on the Output tabs of the Step Function. The final count of errors and their details are included in the final email that is sent at the end of the pipeline.

Cleanup

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 code and the S3 bucket holding the software installation packages.

    • Navigate to the Amazon S3 console.
    • Select the bucket created in Step 1.
    • Select all the objects inside the bucket and choose Delete.
    • Confirm the deletion and choose Delete objects.
    • Once the bucket is empty, return to the Amazon S3 bucket page.
    • Select the bucket and choose Delete.
    • Confirm the deletion and choose Delete bucket.
    • Repeat these steps to remove the bucket containing the software installation packages. This bucket will be named similar to: wks-automation-installer-source-#######.

  2. Remove any WorkSpaces bundles and images created from the automation.

    • Navigate to the Amazon WorkSpaces console.
    • Select Bundles.
    • Filter the bundle list by selecting Custom bundles under Filter owner.
    • Select the bundle name to delete and choose Delete.
    • Choose Delete to confirm.
    • Select Images.
    • Select the image name to delete and choose Delete.
    • Choose Delete to confirm.
    • Repeat for any additional bundles and images created using the automation that are no longer needed.

  3. Remove any image builder WorkSpaces created by the automation that remain.

    • Navigate to the Amazon WorkSpaces console.
    • Select WorkSpaces.
    • To find WorkSpaces created for your image builder user, type the username into the Filter WorkSpaces box.
    • Select the box next to the WorkSpace to delete.
    • Select the image builder to delete, choose Delete.
    • Enter the Delete into the confirmation box, then choose Delete.
    • Repeat for any additional image builders left behind from the automation that are no longer needed.
    1. Remove all the remaining resources created by the CloudFormation template:
      • Navigate to the AWS CloudFormation console.
      • Select the stack created in Step 3, WorkSpaces-Windows-Image-Pipeline.
      • Choose Delete. This will automatically delete the remaining resources used in the solution.

Security

See CONTRIBUTING for more information.

License

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