# What is Image Builder? EC2 Image Builder is a fully managed AWS service that helps you to automate the creation, management, and deployment of customized, secure, and up-to-date server images. You can use the AWS Management Console, AWS Command Line Interface, or APIs to create custom images in your AWS account. You own the customized images that Image Builder creates in your account. You can configure pipelines to automate updates and system patching for the images that you own. You can also run a stand-alone command to create an image with the configuration resources that you've defined. The Image Builder pipeline wizard can guide you through the steps to create a custom image, as follows: ## Step 1: Specify pipeline details + Name your pipeline and add tags. + Define metadata and vulnerability scan settings. + Set up a schedule for your pipeline. ## Step 2: Customize your image You can select an existing recipe or create a new one. + Choose a base image for your customizations. + Add to or remove software from your base image. + Customize settings and scripts with build components. + Select test components to run. ## Step 3: Define your workflow An image workflow defines the sequence of steps that Image Builder performs during the build and test stages of the image creation process. This is part of the overall Image Builder workflow framework. ## Step 4: Configure build infrastructure + Select an IAM role to associate with the instance profile for instances that Image Builder launches during the image creation process. + Select one or more instance types that can be applied at launch. + Select an Amazon Simple Notification Service (SNS) Topic to receive notifications from Image Builder. + Specify VPC, subnet, and security groups that apply for the image creation process. + Select troubleshooting settings such as where Image Builder writes logs, and whether to terminate the build instance on failure (default) or keep it running for further troubleshooting. ## Step 5: Define image distribution + Select AWS Regions where Image Builder distributes your Amazon Machine Image (AMI) or container image. + If your Image Builder pipeline creates an AMI, Image Builder also supports the following configuration: + Select a KMS key to use for encryption. + Configure AMI sharing across AWS accounts and Organizations. + Associate a License Manager self-managed license with your distributed image. + Configure a launch template for your image. ## Features of Image Builder EC2 Image Builder provides the following features: **Increase productivity and reduce operations for building compliant and up-to-date images** Image Builder reduces the amount of work involved in creating and managing images at scale by automating your build pipelines. You can automate your builds by providing your build execution schedule preference. Automation reduces the operational cost of maintaining your software with the latest operating system patches. **Increase service uptime** Image Builder provides access to test components that you can use to test your images before deployment. You can also create custom test components with AWS Task Orchestrator and Executor (AWSTOE), and use those. Image Builder distributes your image only if all of the configured tests have succeeded. **Raise the security bar for deployments** Image Builder allows you to create images that remove unnecessary exposure to component security vulnerabilities. You can apply AWS security settings to create secure, out-of-the-box images that meet industry and internal security criteria. Image Builder also provides collections of settings for companies in regulated industries. You can use these settings to help you quickly and easily build compliant images for STIG standards. For a complete list of STIG components available through Image Builder, see [Amazon managed STIG hardening components for Image Builder](ib-stig.md). **Centralized enforcement and lineage tracking** Using built-in integrations with AWS Organizations, Image Builder enables you to enforce policies that restrict accounts to run instances only from approved AMIs. **Simplified sharing of resources across AWS accounts** EC2 Image Builder integrates with AWS Resource Access Manager (AWS RAM) to allow you to share certain resources with any AWS account or through AWS Organizations. EC2 Image Builder resources that can be shared are: + Components + Images + Image recipes + Container recipes For more information, see [Share Image Builder resources with AWS RAM](manage-shared-resources.md). ## Supported operating systems Image Builder supports the following operating system versions: | Operating system/distribution | Supported versions | | --- | --- | | Amazon Linux | 2 and 2023 | | CentOS | 7 and 8 | | CentOS Stream | 8 | | macOS | 12.x (Monterey), 13.x (Ventura), 14.x (Sonoma), 15.x (Sequoia), 26.x (Tahoe) | | Red Hat Enterprise Linux (RHEL) | 7, 8, 9, and 10 | | SUSE Linux Enterprise Server (SUSE) | 12, 15 and 16 | | Ubuntu | 18.04 LTS, 20.04 LTS, 22.04 LTS, and 24.04 LTS | | Windows Server | 2012 R2, 2016, 2019, 2022, and 2025 | ## Supported image formats For your custom images that create an Amazon Machine Image (AMI), you can choose an existing AMI as a starting point. For Docker container images, you can choose from public images hosted on DockerHub, existing container images in Amazon ECR, or Amazon-managed container images as your starting point. ## Default quotas To view the default quotas for Image Builder, see [Image Builder Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/imagebuilder.html). ## AWS Regions and Endpoints To view the service endpoints for Image Builder, see [Image Builder Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/imagebuilder.html). ## Concepts The following terms and concepts are central to your understanding and use of EC2 Image Builder. **AMI** An Amazon Machine Image (AMI) is the basic unit of deployment in Amazon EC2, and is one of the types of images you can create with Image Builder. An AMI is a pre-configured virtual machine image that contains the operating system (OS) and preinstalled software to deploy EC2 instances. For more information, see [Amazon Machine Images (AMI)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html). **Image pipeline** An image pipeline provides an automation framework for building secure AMIs and container images on AWS. The Image Builder image pipeline is associated with an image recipe or container recipe that defines the build, validation, and test phases for an image build lifecycle. An image pipeline can be associated with an infrastructure configuration that defines where your image is built. You can define attributes, such as instance type, subnets, security groups, logging, and other infrastructure-related configurations. You can also associate your image pipeline with a distribution configuration to define how you would like to deploy your image. **Managed image** A managed image is a resource in Image Builder that consists of an AMI or container image, plus metadata, such as version and platform. The managed image is used by Image Builder pipelines to determine which base image to use for the build. In this guide, managed images are sometimes referred to as "images," however, an image is not the same as an AMI. **Image recipe** An Image Builder image recipe is a document that defines the base image and the components that are applied to the base image to produce the desired configuration for the output AMI image. You can use an image recipe to duplicate builds. Image Builder image recipes can be shared, branched, and edited using the console wizard, the AWS CLI, or the API. You can use image recipes with your version control software to maintain shareable, versioned image recipes. **Container recipe** An Image Builder container recipe is a document that defines the base image and the components that are applied to the base image to produce the desired configuration for the output container image. You can use a container recipe to duplicate builds. You can share, branch, and edit Image Builder image recipes by using the console wizard, the AWS CLI, or the API. You can use container recipes with your version control software to maintain shareable, versioned container recipes. **Base image** The base image is the selected image and operating system used in your image or container recipe document, along with the components. The base image and the component definitions combined produce the desired configuration for the output image. **Components** A component defines the sequence of steps required to either customize an instance prior to image creation (a **build component**), or to test an instance that was launched from the created image (a **test component**). A component is created from a declarative, plain-text YAML or JSON document that describes the runtime configuration for building and validating, or testing an instance that is produced by your pipeline. Components run on the instance using a component management application. The component management application parses the documents and runs the desired steps. After they are created, one or more components are grouped together using an image recipe or container recipe to define the plan for building and testing a virtual machine or container image. You can use public components that are owned and managed by AWS, or you can create your own. For more information about components, see [How Image Builder uses the AWS Task Orchestrator and Executor application to manage components](toe-component-manager.md). **Component document** A declarative, plain-text YAML or JSON document that describes configuration for a customization you can apply to your image. The document is used to create a build or test component. **Runtime stages** EC2 Image Builder has two runtime stages: **build** and **test**. Each runtime stage has one or more phases with configuration defined by the component document. **Configuration phases** The following list shows the phases that run during the **build** and **test** stages:*Build stage:* Build phase An image pipeline begins with the build phase of the build stage when it runs. The base image is downloaded, and configuration that is specified for the build phase of the component is applied to build and launch an instance. Validate phase After Image Builder launches the instance and applies all of the build phase customizations, the validation phase begins. During this phase, Image Builder ensures that all of the customizations work as expected, based on the configuration that the component specifies for the validate phase. If the instance validation succeeds, Image Builder stops the instance, creates an image, and then continues to the test stage.*Test stage:* Test phase During this phase, Image Builder launches an instance from the image that it created after the validation phase completed successfully. Image Builder runs test components during this phase to verify that the instance is healthy and functions as expected. Container host test phase After Image Builder runs the test phase for all of the components that you selected in the container recipe, Image Builder runs this phase for container workflows. The container host test phase can run additional tests that validate container management and custom runtime configurations. **Workflow** Workflows define the sequence of steps that Image Builder performs when it creates a new image. All images have build, test, and distribution workflows.*Workflow types* `BUILD` Covers build stage configuration for every image created. `TEST` Covers test stage configuration for every image created. `DISTRIBUTION` Covers distribution stage configuration for every image created. ## Pricing There is no cost to use EC2 Image Builder to create custom AMI or container images. However, standard pricing applies for other services that are used in the process. The following list includes the usage of some AWS services that can incur costs when you create, build, store, and distribute your custom AMI or container images, depending on your configuration. + Launching an EC2 instance + Storing logs on Amazon S3 + Validating images with Amazon Inspector + Storing Amazon EBS Snapshots for your AMIs + Storing container images in Amazon ECR + Pushing and pulling container images into and out of Amazon ECR + If Systems Manager Advanced Tier is turned on, and Amazon EC2 instances run with on-premises activation, you might be charged for resources through Systems Manager ## Related AWS services EC2 Image Builder uses other AWS services to build images, depending on your Image Builder recipe configuration. For more information about product and service integration for your custom images, see [Integrate products and services in Image Builder](integrate-products-services.md). # How EC2 Image Builder works How Image Builder works When you use the EC2 Image Builder console to create a custom image pipeline, the system 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. 1. **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. 1. **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 AWS account during the build process. 1. **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)](https://docs.aws.amazon.com/sns/latest/dg/welcome.html). 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. **Topics** + [ ## AMI elements ](#ami-image-elements) + [ ## Component management ](#ibhow-component-management) + [ ## Resources created ](#image-builder-resources) + [ ## Distribution ](#image-builder-distribution) + [ ## Sharing Resources ](#ibhow-sharing) + [ ## Compliance ](#ibhow-compliance) ## 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/RootDeviceStorage.html). + When Amazon EBS is used, the root device is an EBS volume created from an [EBS snapshot](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-snapshots.html). + Launch permissions that determine the AWS accounts that can launch VMs with the AMI. + [Block device mapping](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html) data that specifies the volumes to attach to the instance after launch. + A unique [resource identifier](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/resource-ids.html) for each Region, for each account. + [Metadata ](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)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](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/instance-identity-documents.html). ## Component management EC2 Image Builder uses a component management application AWS Task Orchestrator and Executor (AWSTOE) that helps you orchestrate complex workflows, modify system configurations, and test your systems with YAML-based script components. Because AWSTOE 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 AWSTOE as a standalone application, see [Manual set up to develop custom components with AWSTOE](toe-get-started.md). Image Builder uses AWSTOE 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 AWSTOE to manage its components, see [Use components to customize your Image Builder image](manage-components.md). For more information about creating components with AWSTOE, see [How Image Builder uses the AWS Task Orchestrator and Executor application to manage components](toe-component-manager.md). ### Image testing You can use AWSTOE 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 AWS 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 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 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](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts.html). To update your distribution settings using the Image Builder console, follow the steps to [Create a new image recipe version from the console](create-image-recipes.md#create-image-recipe-version-console), or [Create a new container recipe version with the console](create-container-recipes.md#create-container-recipe-version). ## Sharing Resources To share components, recipes, or images with other accounts or within AWS Organizations, see [Share Image Builder resources with AWS RAM](manage-shared-resources.md). ## Compliance For Center for Internet Security (CIS) Benchmarks, EC2 Image Builder uses Amazon Inspector to perform assessments for exposure, vulnerabilities, and deviations from best practices and compliance standards. For example, Image Builder assesses unintended network accessibility, unpatched CVEs, public internet connectivity, and remote root login activation. 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](https://docs.aws.amazon.com/inspector/v1/userguide/inspector_introduction.html) User Guide*. For more information, see [Center for Internet Security (CIS) Benchmarks](https://docs.aws.amazon.com/inspector/latest/userguide/inspector_cis.html). 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](ib-stig.md). # Semantic versioning in Image Builder Semantic versioning Image Builder uses semantic versioning to organize resources and ensure that they have unique IDs. The semantic version has four nodes: ***.**.**/* You can assign values for the first three, and can filter on all of them. Semantic versioning is included in each object's Amazon Resource Name (ARN), at the level that applies to that object as follows: 1. Versionless ARNs and Name ARNs do not include specific values in any of the nodes. The nodes are either left off entirely, or they are specified as wildcards, for example: x.x.x. 1. Version ARNs have only the first three nodes: .. 1. Build version ARNs have all four nodes, and point to a specific build for a specific version of an object. **Assignment:** For the first three nodes you can assign any positive integer value, or zero, with an upper limit of 2^30-1, or 1073741823 for each node. Image Builder automatically assigns the build number to the fourth node. **Patterns:** You can use any numeric pattern that adheres to the assignment requirements for the nodes that you can assign. For example, you might choose a software version pattern, such as 1.0.0, or a date, such as 2021.01.01. **Selection:** With semantic versioning, you have the flexibility to use wildcards (x) to specify the most recent versions or nodes when selecting the base image or components for your recipe. When you use a wildcard in any node, all nodes to the right of the first wildcard must also be wildcards. For example, given the following recent versions: 2.2.4, 1.7.8, and 1.6.8, version selection using wildcards produces the following results: + `x.x.x` = 2.2.4 + `1.x.x` = 1.7.8 + `1.6.x` = 1.6.8 + `x.2.x` is not valid, and produces an error + `1.x.8` is not valid, and produces an error ## Wildcard versioning in lifecycle policies You can use wildcard patterns for semantic versions in lifecycle policy recipe selection to target multiple versions of a recipe with a single policy. This simplifies lifecycle management by eliminating the need to create separate policies for each recipe version. The following wildcard patterns are supported for lifecycle policy recipe versions: + `x.x.x` – Matches all versions of the recipe. + `1.x.x` – Matches all minor and patch versions within major version 1. + `1.0.x` – Matches all patch versions within version 1.0. When a lifecycle policy with wildcard patterns runs, Image Builder resolves the wildcards to all matching recipe versions at execution time. This creates an immutable list of versions for that execution. New recipe versions created after the policy execution begins are automatically included in the next scheduled execution. For more information about creating lifecycle policies with wildcard versioning, see [Create lifecycle policies](create-lifecycle-policies.md). ## Using version references Version references are ready-to-use ARN strings that incorporate wildcard patterns based on the semantic version of the resource you created or retrieved. Instead of writing custom code to parse ARNs and insert wildcards, Image Builder does this work for you. When you create or retrieve Image Builder resources, Image Builder automatically provides pre-constructed ARNs with wildcard version patterns in the `latestVersionReferences` object. This eliminates the need to manually parse and reconstruct ARNs when you want to reference resources using wildcard versioning patterns. For example, when you create a component with version `1.2.3`, Image Builder returns: ``` { "componentBuildVersionArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-component/1.2.3/1", "latestVersionReferences": { "latestVersionArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-component/x.x.x", "latestMajorVersionArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-component/1.x.x", "latestMinorVersionArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-component/1.2.x", "latestPatchVersionArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-component/1.2.3" } } ``` ## Available version reference patterns The `latestVersionReferences` object contains four ARN patterns: + latestVersionArn (x.x.x) - Always resolves to the absolute latest version. + atestMajorVersionArn (1.x.x) - Resolves to the latest minor and patch versions within a major version. + latestMinorVersionArn (1.2.x) - Resolves to the latest patch version within a specific minor version. + latestPatchVersionArn (1.2.3) - References a specific semantic version and resolves to the latest build version for resources that support multiple build versions. ## Resources that return version references Version references are returned by `Create` and `Get` APIs for all versioned Image Builder resources: + Components - `CreateComponent`, `GetComponent` + Image recipes - `CreateImageRecipe`, `GetImageRecipe` + Container recipes - `CreateContainerRecipe`, `GetContainerRecipe` + Images - `CreateImage`, `GetImage` + Workflows - `CreateWorkflow`, `GetWorkflow` *Note:* For Image Builder-managed workflows, only `latestVersionArn (x.x.x)` is returned, since Image Builder requires you to always use the latest version of Image Builder-managed workflows.