Prerequisites - EC2 Image Builder
EC2 Image Builder service-linked roleConfiguration requirementsContainer repository (container image pipelines)Amazon Identity and Access Management (IAM)
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Prerequisites

Verify the following prerequisites to create an image pipeline with EC2 Image Builder. Unless specifically 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 Amazon 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 Amazon Management Console, the Amazon CLI, or the Amazon 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.

Configuration requirements

  • Image Builder supports Amazon PrivateLink. For more information about configuring VPC endpoints for Image Builder, see EC2 Image Builder and interface VPC endpoints (Amazon PrivateLink).

  • The instances that Image Builder uses to build container images must have internet access to download the Amazon CLI from Amazon S3, and to download a base image from the Docker Hub repository, if applicable. Image Builder uses the Amazon CLI to get the Dockerfile from the container recipe, where it is stored as data.

  • The instances that Image Builder uses to build images and run tests must have access to the Systems Manager service. 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 Amazon Systems Manager User Guide.

Container repository (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.

Amazon Identity and Access Management (IAM)

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.

  1. Sign in to the Amazon Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the left navigation pane, choose Policies.

  3. Filter the list of policies with EC2InstanceProfileForImageBuilder

  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 EC2InstanceProfileForImageBuilderECRContainerBuilds and AmazonSSMManagedInstanceCore policies.

Note

If 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, and attach the Ec2ImageBuilderCrossAccountDistributionAccess policy managed policy to the role. For more information, see Share EC2 Image Builder resources.