Share EC2 Image Builder resources - EC2 Image Builder
Working with shared resourcesPrerequisites for sharing components, images, and recipesRelated servicesSharing across RegionsSharing a component, image, or recipeUnsharing a shared component, image, or recipeIdentifying a shared component, image, or recipeShared component, image, and recipe permissionsBilling and meteringResource limits
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).

Share EC2 Image Builder resources

EC2 Image Builder integrates with Amazon Resource Access Manager (Amazon RAM) to allow you to share certain resources with any Amazon Web Services account or through Amazon Organizations. EC2 Image Builder resources that can be shared are:

  • Components

  • Images

  • Recipes

This section provides information to help you share these EC2 Image Builder resources.

Working with shared components, images, and recipes in EC2 Image Builder

Component, image, and recipe sharing enables resource owners to share software configurations with other Amazon Web Services accounts or within an Amazon organization. You can manage resource sharing centrally, and define a set of accounts with which the configuration can be shared.

In this model, the Amazon Web Services account that owns the component, image, or recipe (owners) shares it with other Amazon Web Services accounts (consumers). Consumers can associate a shared component with their image pipelines to automatically consume updates to the shared component, image, or recipe.

A component, image, or recipe owner can share these resources with:

  • Specific Amazon Web Services accounts inside or outside of its organization in Amazon Organizations.

  • An organizational unit (OU) inside of its organization in Amazon Organizations.

  • Its entire organization in Amazon Organizations.

  • Amazon Organizations or OUs outside of its organization.

Prerequisites for sharing components, images, and recipes

To share an Image Builder component, image, or recipe:

  • You must own the component, image, or recipe in your Amazon Web Services account. You cannot share resources that have been shared with you.

  • The Amazon Key Management Service (Amazon KMS) key associated with encrypted resources must be explicitly shared with the target accounts, organizations, or OUs.

  • If you distribute an image encrypted with Amazon KMS across accounts in different Regions, you must create a KMS key and alias in each target Region. Additionally, the people who will be launching instances in those Regions will need access to the KMS key specified via the Key Policy.

The following resources that Image Builder creates from your pipeline build are not considered Image Builder resources – rather, they are external resources that Image Builder distributes in your account, and to the Amazon Web Services Regions, accounts, and organizations or organizational units (OUs) that you specify in your distribution configuration.

  • Amazon Machine Images (AMIs)

  • Container images that reside in Amazon ECR

For more information about distribution settings for your AMI, see Create and update AMI distribution configurations. For more information about distribution settings for your container image in Amazon ECR, see Create and update distribution settings for container images.

For more information about sharing your AMI, see Shared AMIs.

Amazon Resource Access Manager

Component, image, and recipe sharing integrate with Amazon Resource Access Manager (Amazon RAM). Amazon RAM is a service that enables you to share your Amazon resources with any Amazon account or through Amazon Organizations. With Amazon RAM, you share resources that you own by creating a resource share. A resource share specifies the resources to share and the consumers with whom to share them. Consumers can be individual Amazon Web Services accounts, organizational units, or an entire organization in Amazon Organizations.

Sharing across Regions

Shared components, images, and recipes can be shared only in a specified Amazon Region. When you share these resources, they will not replicate across Regions.

Sharing a component, image, or recipe

To share an Image Builder component, image, or recipe, you must add it to a resource share. A resource share is an Amazon RAM resource that lets you share your resources across Amazon accounts. A resource share specifies the resources to share and the consumers with whom they are shared. To add the component, image, or recipe to a new resource share, you must first create the resource share using the Amazon RAM console.

If you are part of an organization in Amazon Organizations and sharing within your organization is enabled, consumers in your organization are automatically granted access to the shared component, image, or recipe. Otherwise, consumers receive an invitation to join the resource share and are granted access to the shared resource after accepting the invitation.

The following options are available for sharing your resources:.

Option 1: Create a RAM resource share

When you create a RAM resource share, you can share a component, image, or recipe that you own in a single step. Use one of the following methods to create your resource share:

  • Console

    To create your resource share using the Amazon RAM console, see Share Amazon resources owned by you in the Amazon RAM User Guide.

  • Amazon CLI

    To create your resource share using the Amazon RAM command line interface, run the create-resource-share command in the Amazon CLI.

Option 2: Apply a resource policy and promote to a RAM resource share

The second option for sharing your resources involves two steps, running commands in the Amazon CLI for both. The first step uses Image Builder commands in the Amazon CLI to apply resource-based policies to the shared resource. The second step promotes the resource to a RAM resource share using the promote-resource-share-created-from-policy Amazon RAM command in the Amazon CLI to ensure that the resource is visible to all principals with whom you've shared it.

  1. Apply the resource policy

    To successfully apply the resource policy, you must ensure that the account with which you are sharing has permission to access any underlying resources.

    Choose the tab that matches your resource type for the applicable command.

    Image

    You can apply a resource policy to an image, to allow others to use it as the base image in their recipes.

    Run the put-image-policy Image Builder command in the Amazon CLI, to identify the Amazon principals to share the image with.

    aws imagebuilder put-image-policy --image-arn arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-image/2019.12.03/1 --policy '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "123456789012" ] }, "Action": ["imagebuilder:GetImage", "imagebuilder:ListImages"], "Resource": [ "arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-image/2019.12.03/1" ] } ] }'
    Component

    You can apply a resource policy to a build or test component to enable cross-account sharing. This command gives other accounts permission to use your component in their recipes. To successfully apply the resource policy, you must ensure that the account with which you are sharing has permission to access any resources referenced by the shared component, such as files hosted on private repositories.

    Run the put-component-policy Image Builder command in the Amazon CLI, to identify the Amazon principals to share the component with.

    aws imagebuilder put-component-policy --component-arn arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/2019.12.03/1 --policy '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "123456789012" ] }, "Action": [ "imagebuilder:GetComponent", "imagebuilder:ListComponents" ], "Resource": [ "arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/2019.12.03/1" ] } ] }'
    Image recipe

    You can apply a resource policy to an image recipe to enable cross-account sharing. This command gives other accounts permission to use your recipe to create images in their accounts. To successfully apply the resource policy, you must ensure that the account with which you are sharing has permission to access any resources that the recipe references, such as the base image, or selected components.

    Run the put-image-recipe-policy Image Builder command in the Amazon CLI, to identify the Amazon principals to share the image with.

    aws imagebuilder put-image-recipe-policy --image-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-image-recipe/2019.12.03 --policy '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "123456789012" ] }, "Action": [ "imagebuilder:GetImageRecipe", "imagebuilder:ListImageRecipes" ], "Resource": [ "arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-image-recipe/2019.12.03" ] } ] }'
    Container recipe

    You can apply a resource policy to a container recipe to enable cross-account sharing. This command gives other accounts permission to use your recipe to create images in their accounts. To successfully apply the resource policy, you must ensure that the account with which you are sharing has permission to access any resources that the recipe references, such as the base image, or selected components.

    Run the put-container-recipe-policy Image Builder command in the Amazon CLI, to identify the Amazon principals to share the image with.

    aws imagebuilder put-container-recipe-policy --container-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-example-container-recipe/2021.12.03 --policy '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "123456789012" ] }, "Action": [ "imagebuilder:GetContainerRecipe", "imagebuilder:ListContainerRecipes" ], "Resource": [ "arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-example-container-recipe/2021.12.03" ] } ] }'
    Note

    To set the correct policies for sharing and unsharing a resource, the resource owner must have imagebuilder:put* permissions.

  2. Promote as a RAM resource share

    To ensure that the resource is visible to all principals with whom you've shared it, run the promote-resource-share-created-from-policy Amazon RAM command in the Amazon CLI.

Unsharing a shared component, image, or recipe

To unshare a shared component, image, or recipe that you own, you must remove it from the resource share. You can do this using the Amazon Resource Access Manager console or the Amazon CLI.

Note

To unshare a component, image, or recipe, the consumer cannot have any dependencies on them. The consumer must remove any dependencies on the shared resources before the owner can unshare them.

To unshare a shared component, image, or recipe that you own using the Amazon Resource Access Manager console

See Updating a Resource Share in the Amazon RAM User Guide.

To unshare a shared component, image, or recipe that you own using the Amazon CLI

Use the disassociate-resource-share command to stop sharing the resource.

Identifying a shared component, image, or recipe

Owners and consumers can identify shared components, images, and image recipes using Image Builder commands in the Amazon CLI.

Identify a shared component

Run the list-components command to get a list of the components that you own and the components that are shared with you. The get-component command shows the Amazon Web Services account ID of the component owner.

Identify a shared image

Run the list-images command to get a list of the images that you own and images that are shared with you. The get-image command shows the Amazon Web Services account ID of the image owner.

Identify a shared container image

Run the list-images command to get a list of the images that you own and images that are shared with you. The get-image command shows the Amazon Web Services account ID of the image owner.

Identify a shared image recipe

Run the list-image-recipes command to get a list of the image recipes that you own and image recipes that are shared with you. The get-image-recipe command shows the Amazon Web Services account ID of the image recipe owner.

Identify a shared container recipe

Run the list-container-recipes command to get a list of the container recipes that you own and container recipes that are shared with you. The get-container-recipe command shows the Amazon Web Services account ID of the container recipe owner.

Shared component, image, and recipe permissions

Permissions for owners

Owners cannot delete a shared component, image, or image recipe until it is no longer shared. An owner cannot unshare these resources until none of the consumers depend on them.

Permissions for consumers

Consumers can read a component, image, or image recipe, but cannot modify them in any way. They cannot view or modify these resources if they are owned by other consumers or the owner of the resource. Consumers can use shared components and images in image recipes to create custom images. Consumers can use shared image recipes to create their own custom images.

Billing and metering

There is no charge to use EC2 Image Builder.

Resource limits

Shared components, images, and image recipes count toward the corresponding resource limits of the owner only. The resource limits of the consumers are not affected by the resources that have been shared with them.