Get set up to build custom images with Image Builder

Before you build images with EC2 Image Builder, verify that you've met the following prerequisites to create an image pipeline. Unless specifically stated otherwise, these prerequisites are required for all types of pipelines.

After you've met the prerequisites, you can manage EC2 Image Builder from any of the following interfaces.

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 first 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 Use IAM service-linked roles for Image Builder.

Configuration requirements

Container repository for container image pipelines

For container image pipelines, the recipe defines the configuration 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.

Dedicated host for macOS images

Amazon EC2 Mac instances require a Dedicated Host running on a metal instance type. Before you create a custom macOS image, you must Allocate a Dedicated Host to your account. For more information about Mac instances and a list of instance types that natively support the macOS operating system, see Amazon EC2 Mac instances in the Amazon EC2 User Guide.

When you've created a Dedicated Host, you can configure settings in the infrastructure configuration resource for your image. The infrastructure configuration includes placement properties where you can specify the host, host placement group, or Availability Zone where the instances that launch from your image should go.

IAM prerequisites

The IAM role that you associate with your instance profile 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 profile:

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.

Systems Manager Agent prerequisites

EC2 Image Builder runs AWS Systems Manager (Systems Manager) Agent on the EC2 instances it launches to build and test your image. Image Builder collects additional information about the instance used during the build phase with Systems Manager Inventory. This information includes the operating system (OS) name and version, as well as the list of packages and their respective versions as reported by your operating system.

To opt out of collecting this information, select the method that matches your preferred environment:

Image Builder uses RunCommand to send actions to your build and test instance as part of the image build and test workflow. You can't opt out of the use of RunCommand to send actions to your build and test instance.