EC2 Image Builder

(1)

EC2 Image Builder

User Guide

(2)

EC2 Image Builder: User Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is EC2 Image Builder?

EC2 Image Builder is a fully managed AWS service that makes it easier to automate the creation, management, and deployment of customized, secure, and up-to-date server images that are preinstalled and pre-conﬁgured with software and settings to meet speciﬁc IT standards.

You can use the AWS Management Console, AWS CLI, or APIs to create custom images in your AWS account. When you use the AWS Management Console, the Image Builder wizard guides you through steps to:

• Provide starting artifacts

• Add and remove software

• Customize settings and scripts

• Run selected tests

• Distribute images to AWS Regions

The images you build are created in your account and you can conﬁgure them for operating system patches on an ongoing basis.

For troubleshooting and debugging your image deployment, you can configure build logs to be added to your Amazon Simple Storage Service (Amazon S3) bucket. You can also configure the instance-building application to send logs to CloudWatch. To receive notifications of image build status, and associate an Amazon Elastic Compute Cloud (Amazon EC2) key pair with your instance to perform manual debugging and inspection, you can configure an SNS topic.

Along with a ﬁnal image, Image Builder creates an image recipe, which is a combination of the source image and components for building and testing. You can use the image recipe with existing source code version control systems and continuous integration/continuous deployment pipelines for repeatable automation.

Section Contents

• Features of EC2 Image Builder (p. 1)

• Supported operating systems (p. 2)

• Supported image formats (p. 2)

• Concepts (p. 2)

• Pricing (p. 4)

• Related AWS services (p. 5)

Features of EC2 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

(8)

Supported operating systems

Image Builder allows you to test your images before deployment with both AWS-provided and customized tests. AWS will distribute your image only if all of the conﬁgured 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 EC2 Image Builder STIG components (p. 112).

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.

Simpliﬁed 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 EC2 Image Builder resources (p. 174).

Supported operating systems

Image Builder supports the following operating systems:

• Amazon Linux 2

• Windows Server 2019/2016/2012 R2

• Windows Server version 2004, and 20H2

• Red Hat Enterprise Linux (RHEL) 8 and 7

• CentOS 8 and 7

• Ubuntu 20, 18, and 16

• SUSE Linux Enterprise Server (SUSE) 15

Supported image formats

For your custom AMI images, 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.

Concepts

The following terms and concepts are central to your understanding and use of EC2 Image Builder.

(9)

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-conﬁgured virtual machine image that contains the operating system (OS) and preinstalled software to deploy EC2 instances. For more information, see Amazon Machine Images (AMI).

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 deﬁnes 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 deﬁnes the base image and the components that are applied to the base image to produce the desired conﬁguration 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 deﬁnes the base image and the components that are applied to the base image to produce the desired conﬁguration 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 deﬁnitions combined produce the desired conﬁguration for the output image.

Components

A component deﬁnes 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 conﬁguration 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 deﬁne the plan for building and testing a virtual machine or container image. You

(10)

Pricing

can use public components that are owned and managed by AWS, or you can create your own. For more information about components, see AWS Task Orchestrator and Executor component manager (p. 23).

Component document

A declarative, plain-text YAML or JSON document that describes conﬁguration 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 conﬁguration deﬁned by the component document.

Conﬁguration 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 conﬁguration that is speciﬁed for the build phase of the component is applied to build and launch an instance.

Validate phase

After the instance is launched and all of the build phase customizations are applied, the validation phase begins. During the validation phase, Image Builder validates that customizations are applied successfully, based on configuration that is specified for the validate phase of the component. If the instance validation is successful, the instance is turned off, an image is created, and Image Builder continues to the test stage.

Test stage:

Test phase

The test stage has only one phase – test. During this phase, an instance is launched from the image that was created after the validation phase completed successfully. Image Builder runs test components during this phase to verify that the instance is healthy, and is functioning as expected.

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 conﬁguration.

• 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

(11)

Related AWS services

EC2 Image Builder uses other AWS services to build images. Depending on your Image Builder image recipe or container recipe conﬁguration, the following services might be used.

AWS License Manager

AWS License Manager allows you to create and apply license configurations from an account license configuration store. For each AMI, you can use Image Builder to attach to a preexisting license configuration that your AWS account has access to as part of the Image Builder workflow. License configurations can be applied only to AMIs. Image Builder can use only preexisting license configurations and cannot directly create or modify license configurations. License Manager settings will not replicate across AWS Regions that must be enabled in your account, for example, between the ap-east-1 (Asia Pacific: Hong Kong) and the me-south-1 (Middle East: Bahrain) Regions.

AWS Organizations

AWS Organizations allows you to apply Service Control Policies (SCP) on accounts in your organization.

You can create, manage, enable, and disable individual policies. Similar to all other AWS artifacts and services, Image Builder honors the policies deﬁned in AWS Organizations. AWS provides template SCPs for common scenarios, such as enforcing constraints on member accounts to launch instances with only approved AMIs.

Amazon Inspector

Image Builder uses Amazon Inspector as the default vulnerability scanning agent to establish security baselines for Amazon Linux 2, Windows Server 2012, and Windows Server 2016. For more information, see What is Amazon Inspector?

AWS Systems Manager Automation

An AWS Systems Manager automation document deﬁnes the actions that AWS Systems Manager performs on your managed instances and AWS resources. Systems Manager documents use JSON or YAML and include steps and parameters that you specify. The steps you specify run in sequential order.

Automation documents are AWS Systems Manager documents of type Automation, as opposed to Command and Policy documents. For more information, see AWS Systems Manager Automation.

AWS Resource Access Manager

AWS Resource Access Manager (AWS RAM) lets you share your resources with any AWS account or through AWS Organizations. If you have multiple AWS accounts, you can create resources centrally and use AWS RAM to share those resources with other accounts. EC2 Image Builder allows sharing for the following resources: components, images, and image recipes. For more information about AWS RAM, see the AWS Resource Access Manager User Guide. For information about sharing Image Builder resources, see Share EC2 Image Builder resources (p. 174).

Amazon CloudWatch Logs

You can use Amazon CloudWatch Logs to monitor, store, and access your log ﬁles from EC2 instances, AWS CloudTrail, Amazon Route 53, and other sources.

Amazon Elastic Container Registry (Amazon ECR)

Amazon ECR is a managed AWS container image registry service that is secure, scalable, and reliable.

Container images you create with Image Builder are stored in Amazon ECR in your default Region, and in any Regions where you distribute the container image. For more information about Amazon ECR, see the Amazon Elastic Container Registry User Guide.

(12)

AMI elements

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 deﬁne Dockerﬁles, and the target Amazon ECR repository for your output Docker container image.

NoteComponents 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 AWS account during the build process.

4.Deﬁne 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.

Section contents

• AMI elements (p. 6)

• Default quotas (p. 7)

• AWS Regions and Endpoints (p. 7)

• Image Builder service integrations (p. 7)

• Component management (p. 9)

• Semantic versioning (p. 9)

• Resources created (p. 10)

• Distribution (p. 11)

• Sharing Resources (p. 11)

• Compliance (p. 11)

AMI elements

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

(13)

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 AWS accounts that can launch VMs with the AMI.

• Block device mapping data that speciﬁes the volumes to attach to the instance after launch.

• A unique resource identiﬁer 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.

AWS Regions and Endpoints

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

Image Builder service integrations

EC2 Image Builder integrates with the following AWS services to provide detailed event metrics, logging, and monitoring to help you track your activity and troubleshoot image build issues.

• Amazon CloudWatch Logs – Monitor, store, and access your Image Builder log ﬁles. You can optionally save your logs to an S3 bucket. For more information about CloudWatch Logs, see What Is Amazon CloudWatch Logs? in the Amazon CloudWatch Logs User Guide.

• Amazon EventBridge – Connect to a stream of real-time event data from Image Builder activities in your account. For more information about EventBridge, see What Is Amazon EventBridge? in the Amazon EventBridge User Guide.

• AWS CloudTrail – Monitor Image Builder events that are sent to CloudTrail. For more information about CloudTrail, see What Is AWS CloudTrail? in the AWS CloudTrail User Guide.

Service integrations

• Amazon CloudWatch Logs (p. 7)

• Amazon EventBridge (p. 8)

• AWS CloudTrail (p. 9)

Amazon CloudWatch Logs

CloudWatch Logs support is enabled by default. Logs are retained on the instance during the build process, and streamed to CloudWatch Logs. The instance logs are removed from the instance before image creation.

(14)

Amazon EventBridge

Build logs are streamed to following the Image Builder CloudWatch Logs group and stream:

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

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

You can opt out of CloudWatch Logs streaming by removing the following permissions associated with the instance proﬁle.

"Statement": [ {

"Effect": "Allow", "Action": [

"logs:CreateLogStream", "logs:CreateLogGroup", "logs:PutLogEvents"

],

"Resource": "arn:aws:logs:*:*:log-group:/aws/imagebuilder/*"

} ]

For advanced troubleshooting, you can run predeﬁned commands and scripts using AWS Systems Manager Run Command. For more information, see Troubleshoot EC2 Image Builder (p. 236).

Amazon EventBridge

Amazon EventBridge is a serverless event bus service that you can use to connect your Image Builder application with related data from other AWS services. In EventBridge, a rule matches incoming events and sends them to targets for processing. A single rule can send an event to multiple targets, which then run in parallel.

EventBridge enables you to automate your AWS services and respond automatically to system events such as application availability issues or resource changes. Events from AWS services are delivered to EventBridge in near real time. You can set up rules that react to incoming events to initiate actions;

for example, sending an event to a Lambda function when the status of an EC2 instance changes from pending to running. These are called patterns. To create a rule based on an event pattern, see Creating Amazon EventBridge rules that react to events in the Amazon EventBridge User Guide.

Actions that can be automatically initiated include the following:

• Invoke an AWS Lambda function

• Invoke Amazon EC2 Run Command

• Relay the event to Amazon Kinesis Data Streams

• Activate an AWS Step Functions state machine

• Notify an Amazon SNS topic or an AWS SMS queue

You can also set up scheduling rules for the default event bus to perform an action at regular intervals, such as running an Image Builder pipeline to refresh an image on a quarterly basis. There are two types of schedule expressions:

• cron expressions – The following example of a cron expression schedules a task to run every day at noon UTC+0:

cron(0 12 * * ? *)

For more information about using cron expressions with EventBridge, see Cron expressions in the Amazon EventBridge User Guide.

(15)

• rate expressions – The following example of a rate expression schedules a task to run every 12 hours:

rate(12 hour)

For more information about using rate expressions with EventBridge, see Rate expressions in the Amazon EventBridge User Guide.

For more information about how EventBridge integrates with Image Builder image pipelines, see Use EventBridge rules with Image Builder pipelines (p. 199).

AWS CloudTrail

This service supports AWS CloudTrail, which is a service that records AWS calls for your AWS account and delivers log ﬁles to an Amazon S3 bucket. By using information collected by CloudTrail, you can determine what requests were successfully made to AWS services, who made the request, when it was made, and so on. For more information about CloudTrail integration with Image Builder, see Logging EC2 Image Builder API calls using AWS CloudTrail (p. 202).

To learn more about CloudTrail, including how to turn it on and ﬁnd your log ﬁles, see the AWS CloudTrail User Guide.

Component management

EC2 Image Builder uses a component management application AWS Task Orchestrator and Executor (AWSTOE) that helps you orchestrate complex workﬂows, modify system conﬁgurations, 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 Get started with AWSTOE (p. 25).

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 ﬁnal image. For more information about how Image Builder uses AWSTOE to manage its components, see Manage components with AWSTOE (p. 125). For more information about creating components with AWSTOE, see AWS Task Orchestrator and Executor component manager (p. 23).

Image testing

You can use AWSTOE test components to validate your image, and ensure that it functions as expected, prior to creating the ﬁnal 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.

Semantic versioning

Image Builder uses semantic versioning to organize resources and ensure that they have unique IDs. The semantic version has four nodes:

<major>.<minor>.<patch>/<build>

You can assign values for the ﬁrst three, and can ﬁlter on all of them.

(16)

Resources created

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.

2. Version ARNs have only the ﬁrst three nodes: <major>.<minor>.<patch>

3. Build version ARNs have all four nodes, and point to a speciﬁc build for a speciﬁc version of an object.

Assignment: For the ﬁrst three nodes you can assign any positive integer value, including 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 ﬂexibility 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 ﬁrst 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

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) 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)

(17)

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

• Docker container image

• Dockerﬁle

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.

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

Sharing Resources

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

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 oﬀered as a test component that you can choose to add to your image recipe. For more information about Amazon Inspector, see the Amazon InspectorUser 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 (p. 112). For more information, see Center for Internet Security (CIS) Benchmarks.

(18)

Prerequisites

Get started with EC2 Image Builder

This chapter helps you set up your environment and create an automated image pipeline or container pipeline for the ﬁrst time, using the EC2 Image Builder Create image pipeline console wizard.

Contents

• Prerequisites (p. 12)

• Access EC2 Image Builder (p. 14)

• Create an image pipeline using the EC2 Image Builder console wizard (p. 14)

• Create a container image pipeline using the EC2 Image Builder console wizard (p. 18)

Prerequisites

Verify the following prerequisites to create an image pipeline with EC2 Image Builder. Unless speciﬁcally stated otherwise, prerequisites are required for all types of pipelines.

EC2 Image Builder service-linked role

EC2 Image Builder uses a service-linked role to grant permissions to other AWS services on your behalf.

You don't need to manually create a service-linked role. When you create your ﬁrst Image Builder resource in the AWS Management Console, the AWS CLI, or the AWS API, Image Builder creates the service-linked role for you. For more information about the service-linked role that Image Builder creates in your account, see Using service-linked roles for EC2 Image Builder (p. 227).

Conﬁguration requirements

• Image Builder supports AWS PrivateLink.

• Image Builder supports EC2-Classic.

• The instances that Image Builder uses to build images and run tests must have access to the Systems Manager service. All build activity is orchestrated by Systems Manager Automation. Installation requirements depend on your operating system.

To see the installation requirements for your base image, choose the tab that matches your base image operating system.

Linux

For Amazon EC2 Linux instances, Image Builder installs the Systems Manager Agent on the build instance if it is not already present, and removes it before creating the image.

Windows

Image Builder does not install the Systems Manager Agent on Amazon EC2 Windows Server build instances. If your base image did not come preinstalled with the Systems Manager Agent, you must launch an instance from your source image, manually install Systems Manager on the instance, and create a new base image from your instance.

To manually install the Systems Manager agent on your Amazon EC2 Windows Server instance, see Manually install Systems Manager Agent on EC2 instances for Windows Server in the AWS Systems Manager User Guide.

(19)

Container repository (container image pipelines)

For container image pipelines, the recipe deﬁnes the conﬁguration for the Docker images that are produced and stored in the target container repository. You must create the target repository before you create the container recipe for your Docker image.

Image Builder uses Amazon ECR as its target repository for container images. To create an Amazon ECR repository, follow the steps described in Creating a repository in the Amazon Elastic Container Registry User Guide.

AWS Identity and Access Management (IAM)

The IAM role that you associate with your instance proﬁle must have permissions to run the build and test components included in your image. The following IAM role policies must be attached to the IAM role that is associated with the instance proﬁle:

• EC2InstanceProﬁleForImageBuilder

• EC2InstanceProﬁleForImageBuilderECRContainerBuilds

• AmazonSSMManagedInstanceCore

If you configure logging, the instance profile specified in your infrastructure configuration must have s3:PutObject permissions for the target bucket (arn:aws:s3:::BucketName/*). For example:

{ "Version": "2012-10-17", "Statement": [

{

"Effect": "Allow", "Action": [

"s3:PutObject"

],

"Resource": "arn:aws:s3:::bucket-name/*"

} ] }

Attach policy

The following steps guide you through the process of attaching the IAM policies to an IAM role to grant the preceding permissions.

1. Sign in to the AWS Management Console and open the IAM console at https://

console.aws.amazon.com/iam/.

2. In the left navigation pane, choose Policies.

3. Filter the list of policies with EC2InstanceProﬁleForImageBuilder

4. Select the bullet next to the policy, and from the Policy actions dropdown list, select Attach.

5. Select the name of the IAM role to which to attach the policy.

6. Choose Attach policy.

7. Repeat steps 3-6 for the EC2InstanceProﬁleForImageBuilderECRContainerBuilds and AmazonSSMManagedInstanceCore policies.

NoteIf you want to copy an image created with Image Builder to another account, you must create the EC2ImageBuilderDistributionCrossAccountRole role in all of the target accounts,

(20)

Access EC2 Image Builder

and attach the Ec2ImageBuilderCrossAccountDistributionAccess policy (p. 223) managed policy to the role. For more information, see Share EC2 Image Builder resources (p. 174).

Access EC2 Image Builder

You can manage EC2 Image Builder from one of the following interfaces.

• EC2 Image Builder console landing page. From the EC2 Image Builder console.

• AWS Command Line Interface (AWS CLI). You can use the AWS CLI to access AWS API operations.

For more information, see Installing the AWS Command Line Interface in the AWS Command Line Interface User Guide.

• AWS Tools for SDKs. You can use AWS SDKs and Tools to access and manage Image Builder using your preferred language.

Create an image pipeline using the EC2 Image Builder console wizard

This tutorial walks you through creating an automated pipeline to build and maintain a customized EC2 Image Builder image using the Create image pipeline console wizard. To help you move through the steps eﬃciently, default settings are used when they are available, and optional sections are skipped.

Create image pipeline workﬂow

• Step 1: Specify pipeline details (p. 14)

• Step 2: Choose recipe (p. 15)

• Step 3: Deﬁne infrastructure conﬁguration - optional (p. 16)

• Step 4: Deﬁne distribution settings - optional (p. 16)

• Step 5: Review (p. 17)

• Step 6: Clean up (p. 17)

Step 1: Specify pipeline details

1. Open the EC2 Image Builder console at https://console.aws.amazon.com/imagebuilder/.

2. To begin creating your pipeline, choose Create image pipeline.

3. In the General section, enter your Pipeline name (required).

Tip

Enhanced metadata collection is turned on by default. To ensure compatibility between components and base images, keep it turned on.

4. In the Build schedule section, you can keep the defaults for the Schedule options. Note that the Time zone shown for the default schedule is Universal Coordinated Time (UTC). For more information about UTC time, and to ﬁnd the oﬀset for your time zone, see Time Zone Abbreviations – Worldwide List.

For Dependency update settings, choose the Run pipeline at the scheduled time if there are dependency updates option. This setting causes your pipeline to check for updates before starting the build. If there are no updates, it skips the scheduled pipeline build.

(21)

NoteTo ensure that your pipeline recognizes dependency updates and builds as expected, you must use semantic versioning (x.x.x) for your base image and components. To learn more about semantic versioning for Image Builder resources, see Semantic versioning (p. 9).

5. Choose Next to proceed to the next step.

Step 2: Choose recipe

1. Image Builder defaults to Use existing recipe in the Recipe section. For your ﬁrst time through, choose the Create new recipe option.

2. In the Image type section, choose the Amazon Machine Image (AMI) option to create an image pipeline that will produce and distribute an AMI.

3. In the General section, enter the following required boxes:

• Name – your recipe name

• Version – your recipe version (use the format <major>.<minor>.<patch>, where major, minor, and patch are integer values). New recipes generally start with 1.0.0.

4. In the Source image section, keep the default values for Select image, Image Operating System (OS), and Image origin. This results in a list of Amazon Linux 2 AMIs, managed by Amazon, for you to choose from for your base image.

a. From the Image name dropdown, choose an image.

b. Keep the default for Auto-versioning options (Use latest available OS version).

NoteThis setting ensures that your pipeline uses semantic versioning for the base image, to detect dependency updates for automatically scheduled jobs. To learn more about semantic versioning for Image Builder resources, see Semantic versioning (p. 9).

5. In the Instance conﬁguration section, keep the default values for the Systems Manager agent.

This results in Image Builder removing the Systems Manager agent after the build and tests are complete, before creating the new image.

Keep User data blank for this tutorial. You can use this area at other times to provide commands, or a command script to run when you launch your build instance. However, it replaces any commands that Image Builder might have added to ensure that Systems Manager is installed. When you do use it, make sure that the Systems Manager agent is preinstalled on your base image, or that you include the install in your user data.

6. In the Components section, you must choose at least one build component.

In the Build components – Amazon Linux panel, you can browse through the components listed on the page. Use the pagination control in the upper right corner to navigate through additional components that are available for your base image OS. You can also search for speciﬁc components, or create your own build component using the Component manager.

For this tutorial, choose a component that updates Linux with the latest security updates, as follows:

a. Filter the results by entering the word update in the search bar that's located at the top of the panel.

b. Select the check box for the update-linux build component.

c. Scroll down, and in the upper right corner of the Selected components list, choose Expand all . d. Keep the default for Versioning options (Use latest available component version).

(22)

Step 3: Deﬁne infrastructure conﬁguration - optional

NoteThis setting ensures that your pipeline uses semantic versioning for the selected component, to detect dependency updates for automatically scheduled jobs. To learn more about semantic versioning for Image Builder resources, see Semantic versioning (p. 9).

If you had selected a component that has input parameters, you would also see the parameters in this area. Parameters are not covered in this tutorial. For more information about using input parameters in your components, and setting them in your recipes, see Manage AWSTOE component parameters with EC2 Image Builder (p. 134).

Reorder components (optional)

If you have chosen more than one component to include in your image, you can use the drag-and- drop action to rearrange them into the order in which they should run during the build process.

1. Scroll back up to the list of available components.

2. Select the check box for the update-linux-kernel-mainline build component (or any other component of your choice).

3. Scroll down to the Selected components list, to see that there are at least two results.

4. Newly added components might not have their versioning or input parameter settings expanded.

To expand Versioning options or Input parameters settings, you can either choose the arrow next to the name of the setting, or you can toggle the Expand all switch oﬀ and on to expand all of the settings for all of the selected components.

5. Choose one of the components, and drag it up or down to change the order in which the components will run.

6. To remove the update-linux-kernel-mainline component, choose X from the upper right corner of the component box.

7. Repeat the previous step to remove any other components you might have added, leaving only the update-linux component selected.

Step 3: Deﬁne infrastructure conﬁguration - optional

Image Builder launches EC2 instances in your account to customize images and run validation tests. The Infrastructure conﬁguration settings specify infrastructure details for the instances that will run in your AWS account during the build process.

In the Infrastructure configuration section, the Configuration options default to Create infrastructure configuration using service defaults. This creates an IAM role and associated instance profile that are used by build instances to configure your EC2 AMIs. You can also create your own custom infrastructure configuration, or use settings that you have already created. For this tutorial, we are using the default settings.

• Choose Next to proceed to the next step.

Step 4: Deﬁne distribution settings - optional

Distribution settings include specific Region settings for encryption, launch permissions, accounts that can launch the output AMI, the output AMI name, license configurations, and Windows AMI faster launching configuration.

(23)

In the Distribution settings section, the Conﬁguration options default to Create distribution settings using service defaults. This option will distribute the output AMI to the current Region. For this tutorial, we are using the default settings. For more information about conﬁguring your distribution settings, see Manage EC2 Image Builder distribution settings (p. 158).

Step 5: Review

The Review section displays all of the settings you have conﬁgured. To edit information in any given section, choose the Edit button located in the top right corner of the step section. For example, if you want to change your pipeline name, choose the Edit button in the top right corner of the Step 1:

Pipeline details section.

1. When you have reviewed your settings, choose Create pipeline to create your pipeline.

2. You can see success or failure messages at the top of the page, as your resources are created for distribution settings, infrastructure conﬁguration, your new recipe, and the pipeline. To see details for a resource, including the resource identiﬁer, choose View details.

3. After you have viewed the details for a resource, you can view details about other resources by choosing the resource type from the navigation pane. For example, to see details for your new pipeline, choose Image pipelines from the navigation pane. If your build was successful, your new pipeline is displayed in the Image pipelines list.

Step 6: Clean up

Your Image Builder environment, just like your home, needs regular maintenance to help you ﬁnd what you need, and complete your tasks without wading through clutter. Make sure to regularly clean up temporary resources that you created for testing. Otherwise, you might forget about those resources, and then later, not remember what they were used for. By then, it might not be clear if you can safely get rid of them.

Tip

To prevent dependency errors when you delete resources, make sure to delete your resources in the following order:

1. Image pipeline 2. Image recipe

3. All remaining resources

To clean up the resources that you created for this tutorial, follow these steps:

Delete the pipeline

1. To see a list of the build pipelines created under your account, choose Image pipelines from the navigation pane.

2. Select the check box next to Pipeline name to select the pipeline that you want to delete.

3. At the top of the Image pipelines panel, on the Actions menu, choose Delete.

4. To conﬁrm the deletion, enter Delete in the box, and choose Delete.

Delete the recipe

1. To see a list of the recipes created under your account, choose Image recipes from the navigation pane.

(24)

Create an image pipeline (Docker)

2. Select the check box next to Recipe name to select the recipe that you want to delete.

3. At the top of the Image recipes panel, on the Actions menu, choose Delete recipe.

Delete infrastructure conﬁguration

1. To see a list of the infrastructure conﬁgurations created under your account, choose Infrastructure conﬁguration from the navigation pane.

2. Select the check box next to Conﬁguration name to select the infrastructure conﬁguration that you want to delete.

3. At the top of the Infrastructure conﬁgurations panel, choose Delete.

Delete distribution settings

1. To see a list of the distribution settings created under your account, choose Distribution settings from the navigation pane.

2. Select the check box next to Conﬁguration name to select the distribution settings that you created for this tutorial.

3. At the top of the Distribution settings panel, choose Delete.

Delete the image

Follow these steps to verify that you have deleted any image that was created from the tutorial pipeline.

This tutorial is not likely to create an image unless enough time has elapsed since you created your pipeline that it runs, according to the build schedule.

1. To see a list of the images created under your account, choose Images from the navigation pane.

2. Choose the image Version for the image that you want to remove. This opens the Image build versions page.

3. Select the check box next to the Version for any image that you want to delete. You can select more than one image version at a time.

4. At the top of the Image build versions panel, choose Delete version.

Create a container image pipeline using the EC2 Image Builder console wizard

This tutorial walks you through creating an automated pipeline to build and maintain a customized EC2 Image Builder Docker image using the Create image pipeline console wizard. To help you move through the steps eﬃciently, default settings are used when they are available, and optional sections are skipped.

Create image pipeline workﬂow

• Step 1: Specify pipeline details (p. 19)

• Step 2: Choose recipe (p. 19)

• Step 3: Deﬁne infrastructure conﬁguration - optional (p. 20)

• Step 4: Deﬁne distribution settings - optional (p. 21)

• Step 5: Review (p. 21)

(25)

• Step 6: Clean up (p. 21)

Step 1: Specify pipeline details

1. Open the EC2 Image Builder console at https://console.aws.amazon.com/imagebuilder/.

2. To begin creating your pipeline, choose Create image pipeline.

3. In the General section, enter your Pipeline name (required).

TipEnhanced metadata collection is turned on by default. To ensure compatibility between components and base images, keep it turned on.

4. In the Build schedule section, you can keep the defaults for the Schedule options. Note that the Time zone shown for the default schedule is Universal Coordinated Time (UTC). For more information about UTC time, and to ﬁnd the oﬀset for your time zone, see Time Zone Abbreviations – Worldwide List.

For Dependency update settings, choose the Run pipeline at the scheduled time if there are dependency updates option. This setting causes your pipeline to check for updates before starting the build. If there are no updates, it skips the scheduled pipeline build.

NoteTo ensure that your pipeline recognizes dependency updates and builds as expected, you must use semantic versioning (x.x.x) for your base image and components. To learn more about semantic versioning for Image Builder resources, see Semantic versioning (p. 9).

Step 2: Choose recipe

1. Image Builder defaults to Use existing recipe in the Recipe section. For your ﬁrst time through, choose the Create new recipe option.

2. In the Image type section, choose the Docker image option to create a container pipeline that will produce a Docker image and distribute it to Amazon ECR repositories in target Regions.

3. In the General section, enter the following required boxes:

• Name – your recipe name

• Version – your recipe version (use the format <major>.<minor>.<patch>, where major, minor, and patch are integer values). New recipes generally start with 1.0.0.

4. In the Source image section, keep the default values for Select image, Image Operating System (OS), and Image origin. This results in a list of Amazon Linux 2 container images, managed by Amazon, for you to choose from for your base image.

a. From the Image name dropdown, choose an image.

b. Keep the default for Auto-versioning options (Use latest available OS version).

Note

This setting ensures that your pipeline uses semantic versioning for the base image, to detect dependency updates for automatically scheduled jobs. To learn more about semantic versioning for Image Builder resources, see Semantic versioning (p. 9).

5. In the Components section, you must choose at least one build component.

In the Build components – Amazon Linux panel, you can browse through the components listed on the page. Use the pagination control in the upper right corner to navigate through additional components that are available for your base image OS. You can also search for speciﬁc components, or create your own build component using the Component manager.

(26)

Step 3: Deﬁne infrastructure conﬁguration - optional

For this tutorial, choose a component that updates Linux with the latest security updates, as follows:

a. Filter the results by entering the word update in the search bar that's located at the top of the panel.

b. Select the check box for the update-linux build component.

c. Scroll down, and in the upper right corner of the Selected components list, choose Expand all . d. Keep the default for Versioning options (Use latest available component version).

Note

This setting ensures that your pipeline uses semantic versioning for the selected component, to detect dependency updates for automatically scheduled jobs. To learn more about semantic versioning for Image Builder resources, see Semantic versioning (p. 9).

If you had selected a component that has input parameters, you would also see the parameters in this area. Parameters are not covered in this tutorial. For more information about using input parameters in your components, and setting them in your recipes, see Manage AWSTOE component parameters with EC2 Image Builder (p. 134).

Reorder components (optional)

If you have chosen more than one component to include in your image, you can use the drag-and- drop action to rearrange them into the order in which they should run during the build process.

1. Scroll back up to the list of available components.

2. Select the check box for the update-linux-kernel-mainline build component (or any other component of your choice).

3. Scroll down to the Selected components list, to see that there are at least two results.

4. Newly added components might not have their versioning expanded. To expand Versioning options, you can either choose the arrow next to Versioning options, or you can toggle the Expand all switch oﬀ and on to expand versioning for all of the selected components.

5. Choose one of the components, and drag it up or down to change the order in which the components will run.

6. To remove the update-linux-kernel-mainline component, choose X from the upper right corner of the component box.

7. Repeat the previous step to remove any other components you might have added, leaving only the update-linux component selected.

6. In the Dockerﬁle template section, select the Use example option. In the Content panel, notice the contextual variables where Image Builder places build information or scripts, based on your container image recipe.

7. In the Target repository section, you must specify the name of an existing Amazon ECR repository that you created as a prerequisite for this tutorial.

NoteThe target repository must exist in Amazon ECR for all target Regions prior to distribution.

Step 3: Deﬁne infrastructure conﬁguration - optional

Image Builder launches EC2 instances in your account to customize images and run validation tests. The Infrastructure conﬁguration settings specify infrastructure details for the instances that will run in your AWS account during the build process.

(27)

In the Infrastructure configuration section, the Configuration options default to Create infrastructure configuration using service defaults. This creates an IAM role and associated instance profile that are used by build instances to configure your EC2 AMIs. You can also create your own custom infrastructure configuration, or use settings that you have already created. For this tutorial, we are using the default settings.

Step 4: Deﬁne distribution settings - optional

Distribution settings consist of the target Regions, and the target Amazon ECR repository name. Output Docker images are deployed to the named Amazon ECR repository in each Region.

In the Distribution settings section, the Conﬁguration options default to Create distribution settings using service defaults. This option will distribute the output Docker image to the Amazon ECR repository in the current Region. For this tutorial, we are using the default settings.

Step 5: Review

The Review section displays all of the settings you have conﬁgured. To edit information in any given section, choose the Edit button located in the top right corner of the step section. For example, if you want to change your pipeline name, choose the Edit button in the top right corner of the Step 1:

Pipeline details section.

1. When you have reviewed your settings, choose Create pipeline to create your pipeline.

2. You can see success or failure messages at the top of the page, as your resources are created for distribution settings, infrastructure conﬁguration, your new recipe, and the pipeline. To see details for a resource, including the resource identiﬁer, choose View details.

3. After you have viewed the details for a resource, you can view details about other resources by choosing the resource type from the navigation pane. For example, to see details for your new pipeline, choose Image pipelines from the navigation pane. If your build was successful, your new pipeline is displayed in the Image pipelines list.

Step 6: Clean up

Your Image Builder environment, just like your home, needs regular maintenance to help you ﬁnd what you need, and complete your tasks without wading through clutter. Make sure to regularly clean up temporary resources that you created for testing. Otherwise, you might forget about those resources, and then later, not remember what they were used for. By then, it might not be clear if you can safely get rid of them.

TipTo prevent dependency errors when you delete resources, make sure to delete your resources in the following order:

1. Image pipeline 2. Image recipe

3. All remaining resources

To clean up the resources that you created for this tutorial, follow these steps:

(28)

Step 6: Clean up

Delete the pipeline

1. To see a list of the build pipelines created under your account, choose Image pipelines from the navigation pane.

2. Select the check box next to Pipeline name to select the pipeline that you want to delete.

3. At the top of the Image pipelines panel, on the Actions menu, choose Delete.

Delete the container recipe

1. To see a list of the container recipes created under your account, choose Container recipes from the navigation pane.

2. Select the check box next to Recipe name to select the recipe that you want to delete.

3. At the top of the Container recipes panel, on the Actions menu, choose Delete recipe.

Delete infrastructure conﬁguration

1. To see a list of the infrastructure conﬁgurations created under your account, choose Infrastructure conﬁguration from the navigation pane.

2. Select the check box next to Conﬁguration name to select the infrastructure conﬁguration that you want to delete.

3. At the top of the Infrastructure conﬁgurations panel, choose Delete.

Delete distribution settings

1. To see a list of the distribution settings created under your account, choose Distribution settings from the navigation pane.

2. Select the check box next to Conﬁguration name to select the distribution settings that you created for this tutorial.

3. At the top of the Distribution settings panel, choose Delete.

Delete the image

Follow these steps to verify that you have deleted any image that was created from the tutorial pipeline.

This tutorial is not likely to create an image unless enough time has elapsed since you created your pipeline that it runs, according to the build schedule.

1. To see a list of the images created under your account, choose Images from the navigation pane.

2. Choose the image Version for the image that you want to remove. This opens the Image build versions page.

3. Select the check box next to the Version for any image that you want to delete. You can select more than one image version at a time.

4. At the top of the Image build versions panel, choose Delete version.

(29)

AWS Task Orchestrator and Executor component manager

EC2 Image Builder uses the AWS Task Orchestrator and Executor (AWSTOE) application to orchestrate complex workﬂows, modify system conﬁgurations, 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 install AWSTOE, choose the download link for your architecture and platform.

Contents

• AWSTOE downloads (p. 23)

• Supported Regions (p. 24)

• Get started with AWSTOE (p. 25)

• Use component documents in AWSTOE (p. 33)

• Action modules supported by AWSTOE component manager (p. 53)

• Conﬁgure input for the AWSTOE run command (p. 109)

• EC2 Image Builder STIG components (p. 112)

• AWSTOE command reference (p. 120)

AWSTOE downloads

Architecture Platform Download link Example

386 AL2, RHEL 8 and 7,

Ubuntu 18 and 16, CentOS 7, SUSE 15

https://

awstoe-

<region>.s3.<region>.amazonaws.com/

latest/linux/386/

awstoe

https://awstoe- us-east-1.s3.us-

east-1.amazonaws.com/

latest/linux/386/

awstoe

AMD64 Windows Server

2019/2016/2012 R2/

version 1909

https://

awstoe-

latest/windows/

amd64/awstoe.exe

latest/windows/

amd64/awstoe.exe

AMD64 AL2, RHEL 8 and 7,

https://

awstoe-

latest/linux/

amd64/awstoe

latest/linux/amd64/

awstoe

ARM64 AL2, RHEL 8 and 7,

https://

awstoe-

(30)

Supported Regions

Architecture Platform Download link Example

latest/linux/

arm64/awstoe

latest/linux/arm64/

awstoe

Supported Regions

AWSTOE is supported as a standalone application in the following Regions.

Region name Region

US East (Ohio) us-east-2

US East (N. Virginia) us-east-1

AWS GovCloud (US-East) us-gov-east-1

AWS GovCloud (US-West) us-gov-west-1

US West (N. California) us-west-1

US West (Oregon) us-west-2

Africa (Cape Town) af-south-1

Asia Paciﬁc (Hong Kong) ap-east-1

Asia Paciﬁc (Mumbai) ap-south-1

Asia Paciﬁc (Osaka) ap-northeast-3

Asia Paciﬁc (Seoul) ap-northeast-2

Asia Paciﬁc (Singapore) ap-southeast-1

Asia Paciﬁc (Sydney) ap-southeast-2

Asia Paciﬁc (Tokyo) ap-northeast-1

Canada (Central) ca-central-1

Europe (Frankfurt) eu-central-1

Europe (Ireland) eu-west-1

Europe (London) eu-west-2

Europe (Milan) eu-south-1

Europe (Paris) eu-west-3

Europe (Stockholm) eu-north-1

Middle East (Bahrain) me-south-1

South America (São Paulo) sa-east-1

China (Beijing) cn-north-1

China (Ningxia) cn-northwest-1

EC2 Image Builder

EC2 Image Builder

User Guide

EC2 Image Builder: User Guide

Table of Contents

What is EC2 Image Builder?

Features of EC2 Image Builder

Supported operating systems

Supported image formats

Concepts

Pricing

Related AWS services

How EC2 Image Builder works

AMI elements

Default quotas

AWS Regions and Endpoints

Image Builder service integrations

Amazon CloudWatch Logs

Amazon EventBridge

AWS CloudTrail

Component management

Image testing

Semantic versioning

Resources created

Distribution

Sharing Resources

Compliance

Get started with EC2 Image Builder

Prerequisites

EC2 Image Builder service-linked role

Conﬁguration requirements

Container repository (container image pipelines)

AWS Identity and Access Management (IAM)

Access EC2 Image Builder

Create an image pipeline using the EC2 Image Builder console wizard

Step 1: Specify pipeline details

Step 2: Choose recipe

Step 3: Deﬁne infrastructure conﬁguration - optional

Step 4: Deﬁne distribution settings - optional

Step 5: Review

Step 6: Clean up

Create a container image pipeline using the EC2 Image Builder console wizard

Step 1: Specify pipeline details

Step 2: Choose recipe

Step 3: Deﬁne infrastructure conﬁguration - optional

Step 4: Deﬁne distribution settings - optional

Step 5: Review

Step 6: Clean up

AWS Task Orchestrator and Executor component manager

AWSTOE downloads

Supported Regions