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 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 include the Amazon EC2 service
-
AmazonSSMManagedInstanceCore and EC2InstanceProfileForImageBuilder policies
-
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.)
Trusted relationship entity:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "ec2.amazonaws.com"
}
"Action": "sts:AssumeRole"
}
]
}
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.*"
]
}
}
},
{
"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/*"
}
]
}
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.
- 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
-
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:
- Create a new recipe
-
-
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.
For information on how to install an SSM agent, see:
-
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.
-
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.
For Linux environments, you must add these components in order with the
aws-cli-version-2-linux
build 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.
- Modify a recipe
-
If you have an existing EC2 Image Builder recipe, you can use it by adding the following
components:
-
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.
-
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.
For Linux environments, you must add these components in order with the
aws-cli-version-2-linux
build component added first.
-
Complete any optional sections if needed, add any other desired components,
and choose Create recipe.
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:
-
For IAM role, enter the role you previously configured
in Prepare 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-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
-
-
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.
- Modify an existing Image Builder 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.
Register a new software stack in RES