# Share an AMI with organizations and organizational units [AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_integrate_services_list.html) is an account management service that enables you to consolidate multiple AWS accounts into an organization that you create and centrally manage. You can share an AMI with an organization or an organizational unit (OU) that you have created, in addition to [sharing it with specific accounts](sharingamis-explicit.md). An organization is an entity that you create to consolidate and centrally manage your AWS accounts. You can organize the accounts in a hierarchical, tree-like structure, with a [root](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started_concepts.html#root) at the top and [organizational units](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started_concepts.html#organizationalunit) nested under the organization root. Each account can be added directly to the root, or placed in one of the OUs in the hierarchy. For more information, see [AWS Organizations terminology and concepts](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started_concepts.html) in the *AWS Organizations User Guide*. When you share an AMI with an organization or an OU, all of the children accounts gain access to the AMI. For example, in the following diagram, the AMI is shared with a top-level OU (indicated by the arrow at the number **1**). All of the OUs and accounts that are nested underneath that top-level OU (indicated by the dotted line at number **2**) also have access to the AMI. The accounts in the organization and OU outside the dotted line (indicated by the number **3**) do not have access to the AMI because they are not children of the OU that the AMI is shared with. ![\[The AMI is shared with an OU, and all children OUs and accounts get access to the AMI.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/ami-share-with-orgs-and-ous.png) **Topics** + [ ## Considerations ](#considerations-org-ou) + [ # Get the ARN of an organization or organizational unit ](get-org-ou-ARN.md) + [ # Allow organizations and OUs to use a KMS key ](allow-org-ou-to-use-key.md) + [ # Manage AMI sharing with an organization or OU ](share-amis-org-ou-manage.md) ## Considerations Consider the following when sharing AMIs with specific organizations or organizational units. + **Ownership** – To share an AMI, your AWS account must own the AMI. + **Sharing limits** – The AMI owner can share an AMI with any organization or OU, including organizations and OUs that they’re not a member of. For the maximum number of entities to which an AMI can be shared within a Region, see the [Amazon EC2 service quotas](https://docs.aws.amazon.com//general/latest/gr/ec2-service.html#limits_ec2). + **Tags** – You can't share user-defined tags (tags that you attach to an AMI). When you share an AMI, your user-defined tags are not available to any AWS account in an organization or OU with which the AMI is shared. + **ARN format** – When you specify an organization or OU in a command, make sure to use the correct ARN format. You'll get an error if you specify only the ID, for example, if you specify only `o-123example` or `ou-1234-5example`. Correct ARN formats: + Organization ARN: `arn:aws:organizations::111122223333:organization/organization-id` + OU ARN: `arn:aws:organizations::111122223333:ou/organization-id/ou-id` Where: + *`111122223333`* is an example of the 12-digit account ID for the management account. If you don't know the management account number, you can describe the organization or the organizational unit to get the ARN, which includes the management account number. For more information, see [Get the ARN of an organization or organizational unit](get-org-ou-ARN.md). + *`organization-id`* is the organization ID, for example, `o-123example`. + *`ou-id`* is the organizational unit ID, for example, `ou-1234-5example`. For more information about the format of ARNs, see [Amazon Resource Names (ARNs)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) in the *IAM User Guide*. + **Encryption and keys** – You can share AMIs that are backed by unencrypted and encrypted snapshots. + The encrypted snapshots must be encrypted with a customer managed key. You can’t share AMIs that are backed by snapshots that are encrypted with the default AWS managed key. + If you share an AMI that is backed by encrypted snapshots, you must allow the organizations or OUs to use the customer managed keys that were used to encrypt the snapshots. For more information, see [Allow organizations and OUs to use a KMS key](allow-org-ou-to-use-key.md). + **Region** – AMIs are a Regional resource. When you share an AMI, it is available only in the Region from which you shared it. To make an AMI available in a different Region, copy the AMI to the Region and then share it. For more information, see [Copy an Amazon EC2 AMI](CopyingAMIs.md). + **Usage** – When you share an AMI, users can only launch instances from the AMI. They can’t delete, share, or modify it. However, after they have launched an instance using your AMI, they can then create an AMI from the instance they launched. + **Billing** – You are not billed when your AMI is used by other AWS accounts to launch instances. The accounts that launch instances using the AMI are billed for the instances that they launch. # Get the ARN of an organization or organizational unit The organization and the organizational unit ARNs contain the 12-digit management account number. If you don't know the management account number, you can describe the organization and the organizational unit to get the ARN for each. In the following examples, `123456789012` is the account ID of the management account. **Required permissions** Before you can get the ARNs, you must have the permission to describe organizations and organizational units. The following policy provides the necessary permission. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "organizations:Describe*" ], "Resource": "*" } ] } ``` ------ ------ #### [ AWS CLI ] **To get the ARN of an organization** Use the [https://docs.aws.amazon.com/cli/latest/reference/organizations/describe-organization.html](https://docs.aws.amazon.com/cli/latest/reference/organizations/describe-organization.html) command. Add the `--query` option to return only the organization ARN. ``` aws organizations describe-organization --query 'Organization.Arn' ``` The following is example output. ``` "arn:aws:organizations::123456789012:organization/o-1234567abc" ``` **To get the ARN of an organizational unit** Use the [https://docs.aws.amazon.com/cli/latest/reference/organizations/describe-organizational-unit.html](https://docs.aws.amazon.com/cli/latest/reference/organizations/describe-organizational-unit.html) command. Use the `--query` parameter to return only the organizational unit ARN. ``` aws organizations describe-organizational-unit \ --organizational-unit-id ou-a123-b4567890 \ --query 'OrganizationalUnit.Arn' ``` The following is example output. ``` "arn:aws:organizations::123456789012:ou/o-1234567abc/ou-a123-b4567890" ``` ------ #### [ PowerShell ] **To get the ARN of an organization** Use the [Get-ORGOrganization](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-ORGOrganization.html) cmdlet. ``` (Get-ORGOrganization).Arn ``` The following is example output. ``` arn:aws:organizations::123456789012:organization/o-1234567abc ``` **To get the ARN of an organizational unit** Use the [Get-ORGOrganizationalUnit](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-ORGOrganizationalUnit.html) cmdlet. ``` (Get-ORGOrganizationalUnit -OrganizationalUnitId "ou-a123-b4567890").Arn ``` The following is example output. ``` arn:aws:organizations::123456789012:ou/o-1234567abc/ou-a123-b4567890 ``` ------ # Allow organizations and OUs to use a KMS key If you share an AMI that is backed by encrypted snapshots, you must also allow the organizations or organizational units (OUs) to use the KMS keys that were used to encrypt the snapshots. **Note** The encrypted snapshots must be encrypted with a *customer managed* key. You can’t share AMIs that are backed by snapshots that are encrypted with the default AWS managed key. To control access to the KMS key, in the [key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) you can use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalorgid](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalorgid) and [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalorgpaths](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalorgpaths) condition keys to allow only specific principals permission to the specified actions. A principal can be a user, IAM role, federated user, or AWS account root user. The condition keys are used as follows: + `aws:PrincipalOrgID` – Allows any principal belonging to the organization represented by the specified ID. + `aws:PrincipalOrgPaths` – Allows any principal belonging to the OUs represented by the specified paths. To give an organization (including the OUs and accounts that belong to it) permission to use a KMS key, add the following statement to the key policy. ``` { "Sid": "Allow access for organization root", "Effect": "Allow", "Principal": "*", "Action": [ "kms:Describe*", "kms:List*", "kms:Get*", "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:CreateGrant" ], "Resource": "*", "Condition": { "StringEquals": { "aws:PrincipalOrgID": "o-123example" } } } ``` To give specific OUs (and the accounts that belong to it) permission to use a KMS key, you can use a policy similar to the following example. ``` { "Sid": "Allow access for specific OUs and their descendants", "Effect": "Allow", "Principal": "*", "Action": [ "kms:Describe*", "kms:List*", "kms:Get*", "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:CreateGrant" ], "Resource": "*", "Condition": { "StringEquals": { "aws:PrincipalOrgID": "o-123example" }, "ForAnyValue:StringLike": { "aws:PrincipalOrgPaths": [ "o-123example/r-ab12/ou-ab12-33333333/*", "o-123example/r-ab12/ou-ab12-22222222/*" ] } } } ``` For more example condition statements, see [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalorgid](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalorgid) and [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalorgpaths](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-principalorgpaths) in the *IAM User Guide*. For information about cross-account access, see [Allowing users in other accounts to use a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html) in the *AWS Key Management Service Developer Guide*. # Manage AMI sharing with an organization or OU You can manage AMI sharing with organizations and organization units (OU) to control whether they can launch Amazon EC2 instances. ## View the organizations and OUs with which an AMI is shared You can find the organizations and OUs with which you've shared your AMI. ------ #### [ Console ] **To check with which organizations and OUs you've shared your AMI** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **AMIs**. 1. Select your AMI in the list, choose the **Permissions** tab, and scroll down to **Shared organizations/OUs**. To find AMIs that are shared with you, see [Find shared AMIs to use for Amazon EC2 instances](usingsharedamis-finding.md). ------ #### [ AWS CLI ] **To check with which organizations and OUs you've shared your AMI** Use the [https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-image-attribute.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-image-attribute.html) command with the `launchPermission` attribute. ``` aws ec2 describe-image-attribute \ --image-id ami-0abcdef1234567890 \ --attribute launchPermission ``` The following is an example response. ``` { "ImageId": "ami-0abcdef1234567890", "LaunchPermissions": [ { "OrganizationalUnitArn": "arn:aws:organizations::111122223333:ou/o-123example/ou-1234-5example" } ] } ``` ------ #### [ PowerShell ] **To check with which organizations and OUs you've shared your AMI** Use the [Get-EC2ImageAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2ImageAttribute.html) cmdlet. ``` Get-EC2ImageAttribute ` -ImageId ami-0abcdef1234567890 ` -Attribute launchPermission ``` ------ ## Share an AMI with an organization or OU You can share an AMI with an organization or OU. **Note** You do not need to share the Amazon EBS snapshots that an AMI references in order to share the AMI. Only the AMI itself needs to be shared, and the system automatically provides the instance with access to the referenced EBS snapshots for the launch. However, you do need to share the KMS keys used to encrypt snapshots that the AMI references. For more information, see [Allow organizations and OUs to use a KMS key](allow-org-ou-to-use-key.md). ------ #### [ Console ] **To share an AMI with an organization or an OU** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **AMIs**. 1. Select your AMI in the list, and then choose **Actions**, **Edit AMI permissions**. 1. Under **AMI availability**, choose **Private**. 1. Next to **Shared organizations/OUs**, choose **Add organization/OU ARN**. 1. For **Organization/OU ARN**, enter the organization ARN or OU ARN with which you want to share the AMI, and then choose **Share AMI**. Note that you must specify the full ARN, not just the ID. To share this AMI with multiple organizations or OUs, repeat this step until you have added all of the required organizations or OUs. 1. Choose **Save changes** when you're done. 1. (Optional) To view the organizations or OUs with which you have shared the AMI, select the AMI in the list, choose the **Permissions** tab, and scroll down to **Shared organizations/OUs**. To find AMIs that are shared with you, see [Find shared AMIs to use for Amazon EC2 instances](usingsharedamis-finding.md). ------ #### [ AWS CLI ] **To share an AMI with an organization** Use the [https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) command to grant launch permissions for the specified AMI to the specified organization. ``` aws ec2 modify-image-attribute \ --image-id ami-0abcdef1234567890 \ --launch-permission "Add=[{OrganizationArn=arn:aws:organizations::123456789012:organization/o-123example}]" ``` **To share an AMI with an OU** The [modify-image-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) command grants launch permissions for the specified AMI to the specified OU. Note that you must specify the full ARN, not just the ID. ``` aws ec2 modify-image-attribute \ --image-id ami-0abcdef1234567890 \ --launch-permission "Add=[{OrganizationalUnitArn=arn:aws:organizations::123456789012:ou/o-123example/ou-1234-5example}]" ``` ------ #### [ PowerShell ] Use the [https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2ImageAttribute.html](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2ImageAttribute.html) command (Tools for Windows PowerShell) to share an AMI as shown in the following examples. **To share an AMI with an organization or an OU** The following command grants launch permissions for the specified AMI to the specified organization. ``` Edit-EC2ImageAttribute ` -ImageId ami-0abcdef1234567890 ` -Attribute launchPermission ` -OperationType add ` -OrganizationArn "arn:aws:organizations::123456789012:organization/o-123example" ``` **To stop sharing an AMI with an organization or OU** The following command removes launch permissions for the specified AMI from the specified organization: ``` Edit-EC2ImageAttribute ` -ImageId ami-0abcdef1234567890 ` -Attribute launchPermission ` -OperationType remove ` -OrganizationArn "arn:aws:organizations::123456789012:organization/o-123example" ``` **To stop sharing an AMI with all organizations, OUs, and AWS accounts** The following command removes all public and explicit launch permissions from the specified AMI. Note that the owner of the AMI always has launch permissions and is therefore unaffected by this command. ``` Reset-EC2ImageAttribute ` -ImageId ami-0abcdef1234567890 ` -Attribute launchPermission ``` ------ ## Stop sharing an AMI with an organization or OU You can stop sharing an AMI with an organization or OU. **Note** You can't stop sharing an AMI with a specific account if it's in an organization or OU with which an AMI is shared. If you try to stop sharing the AMI by removing launch permissions for the account, Amazon EC2 returns a success message. However, the AMI continues to be shared with the account. ------ #### [ Console ] **To stop sharing an AMI with an organization or OU** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **AMIs**. 1. Select your AMI in the list, and then choose **Actions**, **Edit AMI permissions**. 1. Under **Shared organizations/OUs**, select the organizations or OUs with which you want to stop sharing the AMI, and then choose **Remove selected**. 1. Choose **Save changes** when you're done. 1. (Optional) To confirm that you have stopped sharing the AMI with the organizations or OUs, select the AMI in the list, choose the **Permissions** tab, and scroll down to **Shared organizations/OUs**. ------ #### [ AWS CLI ] **To stop sharing an AMI with an organization or OU** Use the [modify-image-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) command. This example removes launch permissions for the specified AMI from the specified organization. ``` aws ec2 modify-image-attribute \ --image-id ami-0abcdef1234567890 \ --launch-permission "Remove=[{OrganizationArn=arn:aws:organizations::123456789012:organization/o-123example}]" ``` **To stop sharing an AMI with all organizations, OUs, and AWS accounts** Use the [https://docs.aws.amazon.com/cli/latest/reference/ec2/reset-image-attribute.html](https://docs.aws.amazon.com/cli/latest/reference/ec2/reset-image-attribute.html) command. This example removes all public and explicit launch permissions from the specified AMI. Note that the owner of the AMI always has launch permissions and is therefore unaffected by this command. ``` aws ec2 reset-image-attribute \ --image-id ami-0abcdef1234567890 \ --attribute launchPermission ``` ------ #### [ PowerShell ] **To stop sharing an AMI with an organization or OU** Use the [Edit-EC2ImageAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2ImageAttribute.html) cmdlet. This example removes launch permissions for the specified AMI from the specified organization. ``` Edit-EC2ImageAttribute ` -ImageId ami-0abcdef1234567890 ` -Attribute launchPermission ` -OperationType remove ` -OrganizationArn "arn:aws:organizations::123456789012:organization/o-123example" ``` **To stop sharing an AMI with all organizations, OUs, and AWS accounts** Use the [Reset-EC2ImageAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Reset-EC2ImageAttribute.html) cmdlet. This example removes all public and explicit launch permissions from the specified AMI. Note that the owner of the AMI always has launch permissions and is therefore unaffected by this command. ``` Reset-EC2ImageAttribute ` -ImageId ami-0abcdef1234567890 ` -Attribute LaunchPermission ``` ------