Configure RES-ready AMIs - Research and Engineering Studio
Prepare an IAM role to access RES environmentCreate EC2 Image Builder componentPrepare your EC2 Image Builder recipeConfigure EC2 Image Builder infrastructureConfigure Image Builder image pipelineRun Image Builder image pipelineRegister a new software stack in RES

Configure RES-ready AMIs

With RES-ready Amazon Machine Images (AMIs), you can pre-install RES dependencies for virtual desktop instances (VDIs) on your custom AMIs. Using RES-ready AMIs improve boot times for VDI instances using the pre-baked images. Using EC2 Image Builder, you can build and register your AMIs as new software stacks. For more information on Image Builder, see the Image Builder User Guide.

Before you begin, you must deploy the latest version of RES.

Prepare an IAM role to access RES environment

To access the RES environment service from EC2 Image Builder, you must create or modify an IAM role called RES-EC2InstanceProfileForImageBuilder. For information on configuring an IAM role for use in Image Builder, see AWS Identity and Access Management (IAM) in the Image Builder User Guide.

Your role requires:

  • Trusted relationships that include the Amazon EC2 service.

  • AmazonSSMManagedInstanceCore and EC2InstanceProfileForImageBuilder policies.

  • A custom RES policy with limited DynamoDB and Amazon S3 access to the deployed RES environment.

    (This policy can be either a customer managed or customer inline policy document.)

  1. Start by creating a new policy that will be attached to your role: IAM -> Policies -> Create policy

  2. Select JSON from the policy editor.

  3. Copy and paste the policy shown here into the editor, replacing your desired {AWS-Region}, {AWS-Account-ID}, and {RES-EnvironmentName} where applicable.

    RES policy:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "RESDynamoDBAccess",
            "Effect": "Allow",
            "Action": "dynamodb:GetItem",
            "Resource": "arn:aws:dynamodb:{AWS-Region}:{AWS-Account-ID}:table/{RES-EnvironmentName}.cluster-settings",
            "Condition": {
                "ForAllValues:StringLike": {
                    "dynamodb:LeadingKeys": [
                        "global-settings.gpu_settings.*",
                        "global-settings.package_config.*",
                        "cluster-manager.host_modules.*",
                        "identity-provider.cognito.enable_native_user_login"
                    ]
                }
            }
        },
        {
            "Sid": "RESS3Access",
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": [
                "arn:aws:s3:::{RES-EnvironmentName}-cluster-{AWS-Region}-{AWS-Account-ID}/idea/vdc/res-ready-install-script-packages/*",
                "arn:aws:s3:::research-engineering-studio-{AWS-Region}/host_modules/*"
            ]
        }
    ]
}

  4. Choose Next and provide a name and optional description to complete the policy creation.

  5. To create the role, start by going to IAM -> Roles -> Create role.

  6. Under Trusted Entity Type, select "AWS service".

  7. Select EC2 in the Service or use case drop down.

  8. In the Use case section, select EC2, then choose Next.

  9. Search for and then select the name of the policy you previously created.

  10. Choose Next and provide a name and optional description to complete the role creation.

  11. Select your new role and verify that the Trust relationship matches the following:

    Trusted relationship entity:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Create EC2 Image Builder component

Follow the directions to Create a component using the Image Builder console in the Image Builder User Guide.

Enter your component details:

  1. For Type, choose Build.

  2. For Image operating system (OS), choose either Linux or Windows.

  3. For Component name, enter a meaningful name such as research-and-engineering-studio-vdi-<operating-system>.

  4. Enter your component's version number and optionally add a description.

  5. For the Definition document, enter the following definition file. If you encounter any errors, the YAML file is space sensitive and is the most likely cause.

    Linux
    #  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
#
#  Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
#  with the License. A copy of the License is located at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
#  or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
#  OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
#  and limitations under the License.
name: research-and-engineering-studio-vdi-linux
description: An RES EC2 Image Builder component to install required RES software dependencies for Linux VDI.
schemaVersion: 1.0
parameters:
  - AWSAccountID:
      type: string
      description: RES Environment AWS Account ID
  - RESEnvName:
      type: string
      description: RES Environment Name
  - RESEnvRegion:
      type: string
      description: RES Environment Region
  - RESEnvReleaseVersion:
      type: string
      description: RES Release Version

phases:
  - name: build
    steps:
       - name: PrepareRESBootstrap
         action: ExecuteBash
         onFailure: Abort
         maxAttempts: 3
         inputs:
            commands:
                - 'mkdir -p /root/bootstrap/logs'
                - 'mkdir -p /root/bootstrap/latest'
       - name: DownloadRESLinuxInstallPackage
         action: S3Download
         onFailure: Abort
         maxAttempts: 3
         inputs:
            - source: 's3://{{ RESEnvName }}-cluster-{{ RESEnvRegion }}-{{ AWSAccountID }}/idea/vdc/res-ready-install-script-packages/linux/res_linux_install_{{ RESEnvReleaseVersion }}.tar.gz'
              destination: '/root/bootstrap/res_linux_install_{{ RESEnvReleaseVersion }}.tar.gz'
              expectedBucketOwner: '{{ AWSAccountID }}'
       - name: RunInstallScript
         action: ExecuteBash
         onFailure: Abort
         maxAttempts: 3
         inputs:
            commands:
                - 'tar -xvf {{ build.DownloadRESLinuxInstallPackage.inputs[0].destination }} -C /root/bootstrap/latest'
                - '/bin/bash /root/bootstrap/latest/virtual-desktop-host-linux/install.sh -r {{ RESEnvRegion }} -n {{ RESEnvName }} -g NONE'
       - name: FirstReboot
         action: Reboot
         onFailure: Abort
         maxAttempts: 3
         inputs:
            delaySeconds: 0
       - name: RunInstallPostRebootScript
         action: ExecuteBash
         onFailure: Abort
         maxAttempts: 3
         inputs:
            commands:
                - '/bin/bash /root/bootstrap/latest/virtual-desktop-host-linux/install_post_reboot.sh'
       - name: SecondReboot
         action: Reboot
         onFailure: Abort
         maxAttempts: 3
         inputs:
            delaySeconds: 0
    Windows
    #  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
#
#  Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
#  with the License. A copy of the License is located at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
#  or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
#  OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
#  and limitations under the License.
name: research-and-engineering-studio-vdi-windows
description: An RES EC2 Image Builder component to install required RES software dependencies for Windows VDI.
schemaVersion: 1.0
parameters:
  - AWSAccountID:
      type: string
      description: RES Environment AWS Account ID
  - RESEnvName:
      type: string
      description: RES Environment Name
  - RESEnvRegion:
      type: string
      description: RES Environment Region
  - RESEnvReleaseVersion:
      type: string
      description: RES Release Version

phases:
  - name: build
    steps:
       - name: CreateRESBootstrapFolder
         action: CreateFolder
         onFailure: Abort
         maxAttempts: 3
         inputs:
            - path: 'C:\Users\Administrator\RES\Bootstrap'
              overwrite: true
       - name: DownloadRESWindowsInstallPackage
         action: S3Download
         onFailure: Abort
         maxAttempts: 3
         inputs:
            - source: 's3://{{ RESEnvName }}-cluster-{{ RESEnvRegion }}-{{ AWSAccountID }}/idea/vdc/res-ready-install-script-packages/windows/res_windows_install_{{ RESEnvReleaseVersion }}.tar.gz'
              destination: '{{ build.CreateRESBootstrapFolder.inputs[0].path }}\res_windows_install_{{ RESEnvReleaseVersion }}.tar.gz'
              expectedBucketOwner: '{{ AWSAccountID }}'
       - name: RunInstallScript
         action: ExecutePowerShell
         onFailure: Abort
         maxAttempts: 3
         inputs:
            commands:
                - 'cd {{ build.CreateRESBootstrapFolder.inputs[0].path }}'
                - 'Tar -xf res_windows_install_{{ RESEnvReleaseVersion }}.tar.gz'
                - 'Import-Module .\virtual-desktop-host-windows\Install.ps1'
                - 'Install-WindowsEC2Instance'
       - name: Reboot
         action: Reboot
         onFailure: Abort
         maxAttempts: 3
         inputs:
            delaySeconds: 0

  6. Create any optional tags and choose Create component.

Prepare your EC2 Image Builder recipe

An EC2 Image Builder recipe defines the base image to use as your starting point to create a new image, along with the set of components that you add to customize your image and verify that everything works as expected. You must either create or modify a recipe to construct the target AMI with the necessary RES software dependencies. For more information on recipes, see Manage recipes.

RES supports the following image operating systems:

  • Amazon Linux 2 (x86 and ARM64)

  • Ubuntu 22.04.3 (x86)

  • RHEL 8 (x86), and 9 (x86)

  • Windows 2019, 2022 (x86)

Create a new recipe

  1. Open the EC2 Image Builder console at https://console.aws.amazon.com/imagebuilder.

  2. Under Saved resources, choose Image recipes.

  3. Choose Create image recipe.

  4. Enter a unique name and a version number.

  5. Select a base image supported by RES.

  6. Under Instance configuration, install an SSM agent if one does not come pre-installed. Enter the information in User data and any other needed user data.

    Note

    For information on how to install an SSM agent, see:

  7. For Linux based recipes, add the Amazon-managed aws-cli-version-2-linux build component to the recipe. RES installation scripts use the AWS CLI to provide VDI access to configuration values for the DynamoDB cluster-settings. Windows does not require this component.

  8. Add the EC2 Image Builder component created for your Linux or Windows environment and enter any required parameter values. The following parameters are required inputs: AWSAccountID, RESEnvName, RESEnvRegion, and RESEnvReleaseVersion.

    Important

    For Linux environments, you must add these components in order with the aws-cli-version-2-linux build component added first.

  9. (Recommended) Add the Amazon-managed simple-boot-test-<linux-or-windows> test component to verify that the AMI can be launched. This is a minimum recommendation. You may select other test components that meet your requirements.

  10. Complete any optional sections if needed, add any other desired components, and choose Create recipe.

Modify a recipe

If you have an existing EC2 Image Builder recipe, you can use it by adding the following components:

  1. For Linux based recipes, add the Amazon-managed aws-cli-version-2-linux build component to the recipe. RES installation scripts use the AWS CLI to provide VDI access to configuration values for the DynamoDB cluster-settings. Windows does not require this component.

  2. Add the EC2 Image Builder component created for your Linux or Windows environment and enter any required parameter values. The following parameters are required inputs: AWSAccountID, RESEnvName, RESEnvRegion, and RESEnvReleaseVersion.

    Important

    For Linux environments, you must add these components in order with the aws-cli-version-2-linux build component added first.

  3. Complete any optional sections if needed, add any other desired components, and choose Create recipe.

Configure EC2 Image Builder infrastructure

You can use infrastructure configurations to specify the Amazon EC2 infrastructure that Image Builder uses to build and test your Image Builder image. For use with RES, you can choose to create a new infrastructure configuration, or use an existing one.

To configure your Image Builder infrastructure:

  1. For IAM role, enter the role you previously configured in Prepare an IAM role to access RES environment.

  2. For Instance type, choose a type with at least 4 GB of memory and supports your chosen base AMI architecture. See Amazon EC2 Instance types.

  3. For VPC, subnet, and security groups, you must permit internet access to download software packages. Access must also be allowed to the cluster-settings DynamoDB table and Amazon S3 cluster bucket of the RES environment.

Configure Image Builder image pipeline

The Image Builder image pipeline assembles the base image, components for building and testing, infrastructure configuration, and distribution settings. To configure an image pipeline for RES-ready AMIs, you can choose to create a new pipeline, or use an existing one. For more information, see Create and update AMI image pipelines in the Image Builder User Guide.

Create a new Image Builder pipeline

  1. Open the Image Builder console at https://console.aws.amazon.com/imagebuilder.

  2. From the navigation pane, choose Image pipelines.

  3. Choose Create image pipeline.

  4. Specify your pipeline details by entering a unique name, optional description, schedule, and frequency.

  5. For Choose recipe, choose Use existing recipe and select the recipe created in Prepare your EC2 Image Builder recipe. Verify that your recipe details are correct.

  6. For Define image creation process, choose either the default or custom workflow depending on the use case. In most cases, the default workflows are sufficient. For more information, see Configure image workflows for your EC2 Image Builder pipeline.

  7. For Define infrastructure configuration, choose Choose existing infrastructure configuration and select the infrastructure configuration created in Configure EC2 Image Builder infrastructure. Verify that your infrastructure details are correct.

  8. For Define distribution settings, choose Create distribution settings using service defaults. The output image must reside in the same AWS Region as your RES environment. Using service defaults, the image will be created in the Region where Image Builder is used.

  9. Review the pipeline details and choose Create pipeline.

Modify an existing Image Builder pipeline

  1. To use an existing pipeline, modify the details to use the recipe created in Prepare your EC2 Image Builder recipe.

  2. Choose Save changes.

Run Image Builder image pipeline

To produce the output image configured, you must initiate the image pipeline. The building process can potentially take up to an hour depending on the number of components in the image recipe.

To run the image pipeline:

  1. From Image pipelines, select the pipeline created in Configure Image Builder image pipeline.

  2. From Actions, choose Run pipeline.

Register a new software stack in RES

  1. Follow the directions in Software Stacks (AMIs) to register a software stack.

  2. For AMI ID, enter the AMI ID of the output image built in Run Image Builder image pipeline.