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.
Topics
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.)
-
Start by creating a new policy that will be attached to your role: IAM -> Policies -> Create policy
-
Select JSON from the policy editor.
-
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/*" ] } ] } -
Choose Next and provide a name and optional description to complete the policy creation.
-
To create the role, start by going to IAM -> Roles -> Create role.
-
Under Trusted Entity Type, select "AWS service".
-
Select EC2 in the Service or use case drop down.
-
In the Use case section, select EC2, then choose Next.
-
Search for and then select the name of the policy you previously created.
-
Choose Next and provide a name and optional description to complete the role creation.
-
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:
-
For Type, choose Build.
-
For Image operating system (OS), choose either Linux or Windows.
-
For Component name, enter a meaningful name such as
research-and-engineering-studio-vdi-<operating-system>. -
Enter your component's version number and optionally add a description.
-
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.
# 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 -
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 Server 2019, 2022 (x86)
-
Windows 10, 11 (x86)
-
Open the EC2 Image Builder console at https://console.aws.amazon.com/imagebuilder
. -
Under Saved resources, choose Image recipes.
-
Choose Create image recipe.
-
Enter a unique name and a version number.
-
Select a base image supported by RES.
-
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:
-
For Linux based recipes, add the Amazon-managed
aws-cli-version-2-linuxbuild 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. -
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-linuxbuild component added first.
-
(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. -
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 create a new infrastructure configuration, see Create an infrastructure configuration.
-
To use an existing infrastructure configuration, Update an infrastructure configuration.
To configure your Image Builder infrastructure:
-
For IAM role, enter the role you previously configured in Prepare an IAM role to access RES environment.
-
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
. -
For VPC, subnet, and security groups, you must permit internet access to download software packages. Access must also be allowed to the
cluster-settingsDynamoDB 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.
-
Open the Image Builder console at https://console.aws.amazon.com/imagebuilder
. -
From the navigation pane, choose Image pipelines.
-
Choose Create image pipeline.
-
Specify your pipeline details by entering a unique name, optional description, schedule, and frequency.
-
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.
-
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.
-
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.
-
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.
-
Review the pipeline details and choose Create pipeline.
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:
-
From Image pipelines, select the pipeline created in Configure Image Builder image pipeline.
-
From Actions, choose Run pipeline.
Register a new software stack in RES
-
Follow the directions in Software Stacks (AMIs) to register a software stack.
-
For AMI ID, enter the AMI ID of the output image built in Run Image Builder image pipeline.
