How EC2 Image Builder works - EC2 Image Builder

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 source 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 source 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 source image and components make up an image recipe.

  3. Define infrastructure configuration – Image Builder launches Amazon 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 AWS account during the build process.

  4. Define distribution settings – Choose the AWS 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 AWS 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 components

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 components:

  • A template for the root volume of the VM. When you launch an 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 AWS 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 per Region per 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 to protect against unauthorized tampering. For more information, see Instance Identity Documents.

Default quotas

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

AWS Regions and Endpoints

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

Logs

EC2 Image Builder integrates with AWS services for monitoring to help you troubleshoot image build issues. Image Builder tracks and displays the progress for each step in the image building process. You can configure the image-building application to send logs to CloudWatch as well as to an S3 location that you provide. For more information about CloudWatch Logs, see What Is Amazon CloudWatch Logs?

CloudWatch logging support is enabled by default. Logs are retained on the instance and streamed to CloudWatch. As part of the AMI creation process, logs are removed from the instance. The logs are streamed to the following LogStream:

  • LogGroup: "/aws/imagebuilder/<ImageName>

  • LogStream: <ImageVersion>/<ImageBuildVersion>["x.x.x/x"]

You can opt out of CloudWatch streaming by removing the following permissions associated with the instance profile.

"Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogStream", "logs:CreateLogGroup", "logs:PutLogEvents" ], "Resource": "arn:aws:logs:*:*:log-group:/aws/imagebuilder/*" } ]

For advanced troubleshooting, you can run predefined commands and scripts using Amazon EC2 Systems Manager (SSM) Run Command. For more information, see Troubleshoot EC2 Image Builder.

Component manager

EC2 Image Builder uses a component management application (AWS TOE) that helps you orchestrate complex workflows, modify system configurations, and test your systems without writing code. This application uses a declarative document schema. Because it is a standalone application, it does not require additional server setup. It can run on any cloud infrastructure and on premises. To download the component management application (AWS TOE) as a standalone application, see Get started with the AWS TOE application .

Image Builder uses this application to perform all on-instance activities, such as build, validation, and test. You define a document that describes how to build, validate, and test your image. Image Builder sends the component to your instance and the application interprets and applies it to your instance by executing the defined phases, steps, and actions. When complete, the application sends a summary to Image Builder. It also sends detailed execution outputs to Amazon S3 if you specified an S3 bucket in your pipeline configuration. Image Builder then cleans up the application and removes it from the instance using AWS best practices for hardening and cleaning the image.

  • Build phase. The image is modified. For example, you can configure your image to install an application or to modify the operating system firewall settings. The validate phase is executed as part of the build phase, prior to the creation of the image.

  • Test phase. Tests are executed against your new image after it is created.

Image Builder uses the component management application as follows.

  1. You define an Image Builder component, which is a document that describes how to build, validate, and test your image.

  2. Image Builder dispatches the work to be performed by copying the document and application to your instance.

  3. The application executes the phases, steps, and actions defined in the document.

For more information about the Component Manager used by Image Builder to orchestrate workflows, including information about documents, supported action modules, and STIGs, see AWS Task Orchestrator and Executor component manager.

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 AWS CLI: StartImagePipelineExecution or CreateImage

The following resources are created during the image build process:

AMI image pipelines

  • Amazon EC2 Instance (temporary)

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

  • Amazon EC2 AMI

  • The Amazon EBS Snapshot associated with Amazon EC2 AMI

Container image pipelines

  • Docker container running on an Amazon EC2 instance (temporary)

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

  • Docker container image

  • Dockerfile

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

Testing

Generally, each test consists of 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).

Distribution

EC2 Image Builder can distribute AMIs or container images to any AWS 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 AWS accounts are permitted to launch Amazon 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.

You can also use your AWS Organizations account to enforce limitations on member accounts to launch instances only with approved and compliant AMIs. For more information, see Managing the AWS Accounts in Your Organization.

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

Sharing Resources

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

Compliance

For CIS, EC2 Image Builder uses Amazon Inspector to perform assessments for exposure, vulnerabilities, and deviations from best practices and compliance standards. For example, it assesses unintended network accessibility, unpatched CVEs, public internet connectivity, and remote root login enablement. Amazon Inspector is offered as a test component that you can choose to add to your image recipe. For more information about Amazon Inspector, see the Amazon Inspector User Guide. For hardening, EC2 Image Builder validates using STIG. For a complete list of STIG components available through Image Builder, see EC2 Image Builder STIG components. For more information, see Center for Internet Security (CIS) Benchmarks and Amazon EC2 Windows Server AMIs for STIG Compliance.