# Share Image Builder resources with AWS RAM EC2 Image Builder integrates with AWS Resource Access Manager (AWS RAM) so that you can share the following types of Image Builder resources with any AWS account or through AWS Organizations. + Components + Images + Recipes To share resources through AWS RAM, you must create a resource share. A resource share specifies the resources to share and the consumers with whom to share them. Consumers can be individual AWS accounts, organizational units, or an entire organization in AWS Organizations. The following list includes the types of accounts and organizations that you can share with. + Specific AWS accounts inside or outside of its organization in AWS Organizations. + An organizational unit (OU) inside of its organization in AWS Organizations. + Its entire organization in AWS Organizations. + AWS Organizations or OUs outside of its organization. In this model, the AWS account that owns the resource (owner) shares it with other AWS accounts or through AWS Organizations (consumers) within the same Region. When a shared resource is updated, consumers get those updates automatically. **Note** 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 are shared with them. **Topics** + [Resource owners](#share-ib-resources-owners) + [Resource consumers](#share-ib-resources-comsumers) + [Create an AWS RAM resource share for your Image Builder resources](manage-shared-resources-share.md) + [Unshare an Image Builder resource from AWS RAM](manage-shared-resources-unshare.md) ## Resource owners Image Builder resources can only be shared in the AWS Region where they are created. When you share these resources, they will not replicate across Regions. To get a list of the Image Builder resources that you own and can share, specify the ownership filter in the console or when you run the command in the AWS CLI. + [List Image Builder components](component-details.md#list-components) + [List images](image-details-list.md#list-images) + [List and view image recipe details](image-recipe-details.md) + [List and view container recipe details](container-recipe-details.md) For more information about AWS RAM, see the [https://docs.aws.amazon.com/ram/latest/userguide/what-is.html](https://docs.aws.amazon.com/ram/latest/userguide/what-is.html). ### Prerequisites for sharing Image Builder resources To share an Image Builder resource, such as a component, image, or recipe: + Your AWS account must own the Image Builder resource that you want to share. You cannot share resources that have been shared with you. + The AWS Key Management Service (AWS KMS) key associated with encrypted resources must be explicitly shared with the target accounts, organizations, or OUs. + In order to share your Image Builder resources with AWS Organizations and OUs using AWS RAM, you must enable sharing. For more information, see [Enable Sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*. + If you distribute an image encrypted with AWS 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 AWS 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](cr-upd-ami-distribution-settings.md). For more information about distribution settings for your container image in Amazon ECR, see [Create and update distribution settings for container images](cr-upd-container-distribution-settings.md). For more information about sharing your AMI with AWS Organizations and OUs, see [Share an AMI with organizations or OUs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/share-amis-with-organizations-and-OUs.html). ## Resource consumers Consumers can use a shared resource, but cannot modify it in any way. When they create Image Builder recipes, they can specify a shared image as the base image, and they can add shared components. They can also specify a shared recipe when they create an Image Builder image pipeline, or when they use the **create-image** command in the AWS CLI. If you belong to an organization in AWS Organizations, and sharing within your organization is enabled, consumers in your organization are automatically granted access to the shared resource. Otherwise, consumers receive an invitation to join the resource share and are granted access to the shared resource after accepting the invitation. # Create an AWS RAM resource share for your Image Builder resources To share an Image Builder component, image, or recipe, you must add it to an AWS Resource Access Manager resource share. The resource share specifies the resources to share and the consumers with whom they are shared. 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 AWS RAM console, see [Share AWS resources owned by you](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*. + **AWS CLI** To create your resource share using the AWS RAM command line interface, run the **[create-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html)** command in the AWS CLI. ## Option 2: Apply a resource policy and promote to an existing resource share The second option for sharing your resources involves two steps, running commands in the AWS CLI for both. The first step uses Image Builder commands in the AWS 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](https://docs.aws.amazon.com/cli/latest/reference/ram/promote-resource-share-created-from-policy.html)** AWS RAM command in the AWS 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](https://docs.aws.amazon.com/cli/latest/reference//imagebuilder/put-image-policy.html)** Image Builder command in the AWS CLI, to identify the AWS 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](https://docs.aws.amazon.com/cli/latest/reference//imagebuilder/put-component-policy.html)** Image Builder command in the AWS CLI, to identify the AWS 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](https://docs.aws.amazon.com/cli/latest/reference//imagebuilder/put-image-recipe-policy.html)** Image Builder command in the AWS CLI, to identify the AWS 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](https://docs.aws.amazon.com/cli/latest/reference//imagebuilder/put-container-recipe-policy.html)** Image Builder command in the AWS CLI, to identify the AWS 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. 1. **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](https://docs.aws.amazon.com/cli/latest/reference/ram/promote-resource-share-created-from-policy.html)** AWS RAM command in the AWS CLI. # Unshare an Image Builder resource from AWS RAM To unshare an Image Builder resource that you own, such as a shared component, image, or recipe, you must remove it from the AWS Resource Access Manager resource share. You can do this using the AWS RAM console or the AWS CLI. **Note** Owners cannot delete a shared resource until it is no longer shared. An owner cannot unshare these resources until none of the consumers depend on them. **To unshare a shared component, image, or recipe that you own using the AWS Resource Access Manager console** See [Updating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*. **To unshare a shared component, image, or recipe that you own using the AWS CLI** Use the **[disassociate-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html)** command to stop sharing the resource.