How EC2 Image Builder works - EC2 Image Builder
AMI elementsDefault quotasAmazon Regions and EndpointsComponent managementResources createdDistributionSharing ResourcesCompliance
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

How EC2 Image Builder works

When you use the EC2 Image Builder pipeline console wizard to create a custom image, a wizard guides you through the following steps.

  1. Specify pipeline details – Enter information about your pipeline, such as a name, description, tags, and a schedule to run automated builds. You can choose manual builds, if you prefer.

  2. Choose recipe – Choose between building an AMI, or building a container image. For both types of output images, you enter a name and version for your recipe, select a base image, and choose components to add for building and testing. You can also choose automatic versioning, to ensure that you always use the latest available Operating System (OS) version for your base image. Container recipes additionally define Dockerfiles, and the target Amazon ECR repository for your output Docker container image.

    Note

    Components are the building blocks that are consumed by an image recipe or a container recipe. For example, packages for installation, security hardening steps, and tests. The selected base image and components make up an image recipe.

  3. Define infrastructure configuration – Image Builder launches EC2 instances in your account to customize images and run validation tests. The Infrastructure configuration settings specify infrastructure details for the instances that will run in your Amazon Web Services account during the build process.

  4. Define distribution settings – Choose the Amazon Regions to distribute your image to after the build is complete and has passed all its tests. The pipeline automatically distributes your image to the Region where it runs the build, and you can add image distribution for other Regions.

The images that you build from your custom base image are in your Amazon Web Services account. You can configure your image pipeline to produce updated and patched versions of your image by entering a build schedule. When the build is complete, you can receive notification through Amazon Simple Notification Service (SNS). In addition to producing a final image, the Image Builder console wizard generates a recipe that can be used with existing version control systems and continuous integration/continuous deployment (CI/CD) pipelines for repeatable automation. You can share and create new versions of your recipe.

AMI elements

An Amazon Machine Image (AMI) is a preconfigured virtual machine (VM) image that contains the OS and software to deploy EC2 instances.

An AMI includes the following elements:

  • A template for the root volume of the VM. When you launch an Amazon EC2 VM, the root device volume contains the image to boot the instance. When instance store is used, the root device is an instance store volume created from a template in Amazon S3. For more information, see Amazon EC2 Root Device Volume.

  • When Amazon EBS is used, the root device is an EBS volume created from an EBS snapshot.

  • Launch permissions that determine the Amazon Web Services accounts that can launch VMs with the AMI.

  • Block device mapping data that specifies the volumes to attach to the instance after launch.

  • A unique resource identifier for each Region, for each account.

  • Metadata payloads such as tags, and properties, such as Region, operating system, architecture, root device type, provider, launch permissions, storage for the root device, and signing status.

  • An AMI signature for Windows images to protect against unauthorized tampering. For more information, see Instance Identity Documents.

Default quotas

To view the default quotas for Image Builder, see Image Builder Endpoints and Quotas.

Amazon Regions and Endpoints

To view the service endpoints for Image Builder, see Image Builder Endpoints and Quotas.

Component management

EC2 Image Builder uses a component management application EC2 Task Orchestrator and Executor (EC2 TOE) that helps you orchestrate complex workflows, modify system configurations, and test your systems with YAML-based script components. Because EC2 TOE is a standalone application, it does not require any additional setup. It can run on any cloud infrastructure and on premises. To get started using EC2 TOE as a standalone application, see Manual set up to develop custom components with EC2 TOE.

Image Builder uses EC2 TOE to perform all on-instance activities. These include building and validating your image before taking a snapshot, and testing the snapshot to ensure that it functions as expected before creating the final image. For more information about how Image Builder uses EC2 TOE to manage its components, see Use components to customize your Image Builder image. For more information about creating components with EC2 TOE, see How Image Builder uses the EC2 Task Orchestrator and Executor application to manage components.

Image testing

You can use EC2 TOE test components to validate your image, and ensure that it functions as expected, prior to creating the final image.

Generally, each test component consists of a YAML document that contains a test script, a test binary, and test metadata. The test script contains the orchestration commands to start the test binary, which can be written in any language supported by the OS. Exit status codes indicate the test outcome. Test metadata describes the test and its behavior; for example, the name, description, paths to test binary, and expected duration.

Resources created

When you create a pipeline, no resources external to Image Builder are created, unless the following is true:

  • When an image is created through the pipeline schedule

  • When you choose Run Pipeline from the Actions menu in the Image Builder console

  • When you run either of these commands from the API or Amazon CLI: StartImagePipelineExecution or CreateImage

The following resources are created during the image build process:

AMI image pipelines

  • EC2 instance (temporary)

  • Systems Manager Inventory Association (through Systems Manager State Manager if EnhancedImageMetadata is Enabled) on the EC2 instance

  • Amazon EC2 AMI

  • The Amazon EBS Snapshot associated with Amazon EC2 AMI

Container image pipelines

  • Docker container running on an EC2 instance (temporary)

  • Systems Manager Inventory Association (through Systems Manager State Manager) EnhancedImageMetadata is Enabled) on the EC2 instance

  • Docker container image

  • Dockerfile

After the image has been created, all of the temporary resources are deleted.

Distribution

EC2 Image Builder can distribute AMIs or container images to any Amazon Region. The image is copied to each Region that you specify in the account used to build the image.

For AMI output images, you can define AMI launch permissions to control which Amazon Web Services accounts are permitted to launch EC2 instances with the created AMI. For example, you can make the image private, public, or share with specific accounts. If you both distribute the AMI to other Regions, and define launch permissions for other accounts, the launch permissions are propagated to the AMIs in all of the Regions in which the AMI is distributed.

To update your distribution settings using the Image Builder console, follow the steps to Create a new image recipe version from the console, or Create a new container recipe version with the console.

Sharing Resources

To share components, recipes, or images with other accounts or within Amazon Organizations, see Share Image Builder resources with Amazon RAM.

Compliance

Image Builder provides STIG hardening components to help you more efficiently build compliant images for baseline STIG standards. These STIG components scan for misconfigurations and run a remediation script. There are no additional charges for using STIG-compliant components. For a complete list of STIG components available through Image Builder, see Amazon managed STIG hardening components for Image Builder.