The code that accompanies this blogpost can be found :
EC2 Image Builder simplifies the building, testing, and deployment of Virtual Machine and container images for use on AWS or on-premises.
Keeping Virtual Machine and container images up-to-date can be time consuming, resource intensive, and error-prone. Currently, customers either manually update and snapshot VMs or have teams that build automation scripts to maintain images.
Image Builder significantly reduces the effort of keeping images up-to-date and secure by providing a simple graphical interface, built-in automation, and AWS-provided security settings. With Image Builder, there are no manual steps for updating an image nor do you have to build your own automation pipeline.
Image Builder is offered at no cost, other than the cost of the underlying AWS resources used to create, store, and share the images.
There are some caveats when using Image Builder:
- EBS encryption by default should be off. An encrypted volume cannot be exported to an alternative image format.
- The S3 bucket the exported image will be stored in, should use the AWS managed KMS key for S3 (
SSE-S3) for encryption. - AWS encourages you to use IMDSv2 when running EC2 instances. This requires an adjustments to any scripts querying the instance metadata, as well as an adjustment to the maximum number of hops for an HTTP put request.
More information on these caveats can be found later in this post.
Creating an Image Builder pipeline
To create an Image Builder pipeline, the following resources are needed:
- IAM roles with permissions for building the Amazon Machine Image (AMI), lifecycle management of the created AMIs, and for exporting the AMI to an additional image format
- An S3 bucket to export the additional image format to
- Any custom components for building your custom AMI
- An image recipe
- An infrastructure configuration
- A distribution configuration
- The Image Builder pipeline
- (Optional) an SNS topic
In the GitHub repository I've linked, the code for the IAM-roles can be found in iam.tf, the code for the S3 bucket can be found in s3.tf, the code for SNS can be found in sns.tf, and the code for the remaining resources can be found in main.tf.
Make sure you're using at least version 5.74.0 of the Terraform AWS provider, to be able to enjoy these enhancements:
- In version
5.74.0support was added to theaws_imagebuilder_distribution_configurationresource for exporting the AMI to S3. - In version
5.59.0support was added to theaws_imagebuilder_image_pipelineresource to set the workflow of the pipeline.
Custom components
A component can have multiple steps, in any of the two phases build ortest. It should have at least one step, and can contain steps for both build as well as test.
The first phase that is run, is the build phase. This is where the initial image if built. After the image has been created, a new EC2 instance (or container) will be started using that image, to run the test steps of the used components.
In the example, I'm using a simple component, which sets the timezone of the AMI to Europe/Amsterdam during the build phase.
resource "aws_imagebuilder_component" "set_timezone" {
name = join("-", [var.name, "set-timezone-linux"])
description = "Sets the timezone to Europe/Amsterdam"
platform = "Linux"
version = "1.0.0"
skip_destroy = false # Setting this to true retains any previous versions
data = yamlencode({
schemaVersion = 1.0
phases = [{
name = "build"
steps = [
{
name = "SetTimezone"
action = "ExecuteBash"
onFailure = "Abort"
inputs = {
commands = [
"timedatectl set-timezone Europe/Amsterdam"
]
}
}
]
}]
})
}
Image recipe
The image recipe brings together all the 'ingredients' that make the image.
The recipe is where you define the source image (parent_image) you're building on, making overrides to settings of the source, as well as adding your own or AWS managed components, which are executed in the order they're listed in the recipe (per phase).
You can also have the SSM agent removed after building the image. This is useful to do if the image will be used outside of AWS, where the SSM agent has no use.
resource "aws_imagebuilder_image_recipe" "this" {
# Currently the service only supports x86-based images for import or export.
name = join("-", [var.name, "image-recipe"])
parent_image = "arn:aws:imagebuilder:eu-west-1:aws:image/amazon-linux-2023-ecs-optimized-x86/x.x.x"
version = "1.0.0"
block_device_mapping {
# The device name is the same device name as the root volume of the selected AMI,
# which means we're overriding (some of) the root disk configuration in the AMI.
# In this case we're increasing the size of the disk from 20 GB to 40 GB.
device_name = "/dev/xvda"
no_device = false
ebs {
delete_on_termination = true
volume_size = 40
volume_type = "gp3"
encrypted = false
iops = 3000
throughput = 125
}
}
# Add the components to the recipe.
# Recipes require a minimum of one build component, and can have a maximum of 20 build and test components in any combination.
# Components are executed in the order they are listed here.
component {
# Here we're adding an AWS managed component to install the AWS CLI
component_arn = "arn:aws:imagebuilder:${data.aws_region.current.name}:aws:component/aws-cli-version-2-linux/x.x.x"
}
component {
# Here we're adding our custom component
component_arn = aws_imagebuilder_component.set_timezone.arn
}
systems_manager_agent {
# Set this to false to keep the SSM agent installed after building the image.
uninstall_after_build = true
}
lifecycle {
# Adding resources to the replace_triggered_by, ensures that replacing a resource doesn't fail because of dependencies.
# Instead, this resource will be replaced as well.
replace_triggered_by = [
aws_imagebuilder_component.set_timezone
]
}
}
Infrastructure configuration
The infrastructure configuration defines what instance type(s) can be used to build and test the image, which subnet the build/test instances should use, as well as which security group(s) should be attached to the instance. The instance profile to use is also defined here, as well as the SNS topic to send messages to upon either success or failure of the pipeline run.
If no subnet ID and security group IDs are provided, a subnet from the default VPC will be used, with the default security group. When providing a subnet ID, one or more security group IDs must also be provided.
If you run into issues during the build phase, you can set terminate_instance_on_failure to false. This means the build-instance will not be terminated, and can be used to investigate the issue.
In this example, IMDSv2 is used (http_tokens = required). Also see here for more information about the http_put_response_hop_limit.
resource "aws_imagebuilder_infrastructure_configuration" "this" {
name = join("-", [var.name, "infrastructure-config"])
description = "Infrastructure Configuration for ${var.name}."
instance_profile_name = aws_iam_instance_profile.imagebuilder_build.name
instance_types = var.instance_types
sns_topic_arn = aws_sns_topic.this.arn
# If you want to keep the instance when an error occurs, so you can debug the issue, set this to false
terminate_instance_on_failure = true
# When not providing a subnet id and security group id(s),
# Image Builder uses a subnet in the default VPC with the default security group.
security_group_ids = var.security_group_ids
subnet_id = var.subnet_id
instance_metadata_options {
http_tokens = "required"
http_put_response_hop_limit = 1 # Increase this to 3 when building a container image
}
tags = {
ImageType = "CustomisedAmazonLinux2023Image"
}
}
Distribution configuration
The distribution configuration tells Image Builder how to name the output AMI, and how to distribute the output AMI to different accounts, regions, organisations, and export the AMI to an alternative image format (VHD, VMDK or RAW)
resource "aws_imagebuilder_distribution_configuration" "this" {
name = join("-", [var.name, "distribution-config"])
description = "Distribution Configuration for ${var.name}."
distribution {
region = data.aws_region.current.name
ami_distribution_configuration {
name = join("-", [var.name, "{{ imagebuilder:buildDate }}-{{ imagebuilder:buildVersion }}"])
kms_key_id = null
ami_tags = {
ImageType = "CustomisedAmazonLinux2023Image"
}
}
s3_export_configuration {
role_name = aws_iam_role.vmexport.name
disk_image_format = upper(var.image_export_format)
s3_bucket = aws_s3_bucket.this.id
}
}
}
Image Builder pipeline
The Image Builder pipeline is what ties all the previous resources together. This orchestrates building the image, and additionally trigger scanning of the output AMI for security issues. Amazon Inspector should be enabled in the account to be able to scan the image.
The pipeline also defines the workflow to use. By default, a workflow that runs both the build and the test phases is used. In the example, no test components are used, so we're shaving some time off of the pipeline runtime, by selecting an AWS-managed workflow that only runs the build phase. When changing the default workflow, an . The pipeline can also be triggered
Another setting that will need adjustment when using Image Builder for building a container image, is setting the Metadata Hop Limit (HttpPutResponseHopLimit) to 2 or 3.
More information on the IMDS options can be found here.
Conclusion
My goal with this post was to show you how you can start using Image Builder to automate creating your custom AMIs or container images, and help you take that initial hurdle to start looking into Image Builder.
It also shows the issues I ran into while implementing Image Builder for a project I'm working on, and how to overcome those.
If you have any feedback on this post, please reach out to me.
SOCIAL SHARE CARD GENERATOR