Sharing AMIs with AWS Accounts

This document outlines the procedures for sharing your private Amazon Machine Images (AMIs) with Instruqt's ephemeral AWS accounts. This allows you to use your custom AMIs within Instruqt sandboxes.

There are three primary methods for sharing, depending on the desired scope of access:

Making the AMI Public: This method makes your AMI accessible to all AWS accounts globally. This is generally not recommended for private or sensitive AMIs.
Sharing with the Entire Instruqt Organization: This method makes your AMI accessible to all AWS accounts managed by Instruqt.
Sharing with a Dedicated Organizational Unit (OU) per Team: This method restricts AMI access to a specific set of AWS accounts used by your team within Instruqt.

Prerequisites

You must have the AWS Command Line Interface (AWS CLI) installed and configured with appropriate permissions to modify AMI attributes.
For sharing with Organizations or OUs, you need the Organization ID for the Instruqt AWS Organization or the Organizational Unit (OU) ID for your specific team. Please contact your Instruqt representative to obtain these IDs.

Method 1: Making the AMI Public

This approach makes your AMI launchable by any AWS account globally. This is the simplest way to share but offers no access control.

Warning: Making an AMI public means anyone with an AWS account can find and use your AMI. This is strongly discouraged for AMIs containing proprietary software, sensitive data, or specific configurations not intended for public consumption. Only use this method if the AMI is explicitly meant to be open to the public.

Steps:

Identify your AMI ID: Note the AMI ID (e.g., ami-0123456789abcdef0).

Make the AMI public using AWS CLI: Use the modify-image-attribute command. Replace ami-youramiid with your AMI ID.

aws ec2 modify-image-attribute \
    --image-id ami-youramiid \
    --launch-permission "add=[{Group=all}]"

Considerations:

Global Accessibility: The AMI becomes available to every AWS account worldwide.
Maximum Simplicity: No need for Organization or OU IDs.
Security Risk: Significant security implications if the AMI is not intended for public use.
Instruqt Usage: While Instruqt accounts can technically use a public AMI, this method bypasses the controlled sharing mechanisms typically preferred for managing custom environments. It's advisable to discuss with your Instruqt representative if using a public AMI is appropriate for your tracks, as they might have specific guidelines.

This approach grants launch permissions for your AMI to the entire AWS Organization that Instruqt uses to manage its ephemeral accounts. This is a broader option and means any Instruqt-managed AWS account can potentially use your AMI.

Steps:

Identify your AMI ID: Note the AMI ID of the image you wish to share (e.g., ami-0123456789abcdef0).
Obtain Instruqt's AWS Organization ID: Request this ID from your Instruqt contact.
Share the AMI using AWS CLI: Use the modify-image-attribute command. Replace ami-youramiid with your AMI ID and o-xxxxxxxxxxx with Instruqt's Organization ID.
```
aws ec2 modify-image-attribute \
    --image-id ami-youramiid \
    --launch-permission "add=[{OrganizationArn='arn:aws:organizations::INSTRUQT_AWS_ACCOUNT_ID:organization/o-xxxxxxxxxxx'}]"
```
- INSTRUQT_AWS_ACCOUNT_ID: This is the main Instruqt AWS Account ID.
- o-xxxxxxxxxxx: This is the Instruqt Organization ID.

Considerations:

Broad Access: This method provides access to all accounts within the Instruqt organization.
Simplicity: It's a straightforward way to share if your AMI is intended for general use across any Instruqt environment.

This method provides more granular control, allowing you to share your AMI only with the AWS accounts that belong to a specific Organizational Unit (OU) associated with your team within Instruqt.

Steps:

Identify your AMI ID: Note the AMI ID (e.g., ami-0123456789abcdef0).
Obtain your Team's Dedicated OU ID: Request this OU ID from your Instruqt contact. It will look something like ou-orgid-xxxxxxxx.
Share the AMI using AWS CLI: Use the modify-image-attribute command. Replace ami-youramiid with your AMI ID and ou-orgid-xxxxxxxx with your team's OU ID.
```
aws ec2 modify-image-attribute \
    --image-id ami-youramiid \
    --launch-permission "add=[{OrganizationalUnitArn='arn:aws:organizations::INSTRUQT_AWS_ACCOUNT_ID:ou/o-xxxxxxxxxxx/ou-orgid-xxxxxxxx'}]"
```
- INSTRUQT_AWS_ACCOUNT_ID: This is the main Instruqt AWS Account ID.
- o-xxxxxxxxxxx: This is the Instruqt Organization ID (the parent organization of the OU).
- ou-orgid-xxxxxxxx: This is your team's specific OU ID.

Considerations:

Granular Control: This method ensures that only AWS accounts designated for your team can access the AMI.
Security: It's generally the recommended approach if the AMI contains sensitive configurations or is intended for a specific group.

You can verify that the AMI has been shared correctly by using the describe-image-attribute command:

aws ec2 describe-image-attribute \
    --image-id ami-youramiid \
    --attribute launchPermission

Look for the group: all (for public AMIs), organizationArn, or organizationalUnitArn in the output.

To stop sharing an AMI, you can use the modify-image-attribute command with the --launch-permission "remove=[{...}]" option, specifying the respective sharing grant you want to remove.

Example for Public AMI (Making it Private):

aws ec2 modify-image-attribute \
    --image-id ami-youramiid \
    --launch-permission "remove=[{Group=all}]"

After removing the group=all permission, the AMI will revert to being private to your account. You may then need to explicitly share it with specific accounts, OUs, or Organizations if needed.

Example for Organization:

aws ec2 modify-image-attribute \
    --image-id ami-youramiid \
    --launch-permission "remove=[{OrganizationArn='arn:aws:organizations::INSTRUQT_AWS_ACCOUNT_ID:organization/o-xxxxxxxxxxx'}]"

Example for OU:

aws ec2 modify-image-attribute \
    --image-id ami-youramiid \
    --launch-permission "remove=[{OrganizationalUnitArn='arn:aws:organizations::INSTRUQT_AWS_ACCOUNT_ID:ou/o-xxxxxxxxxxx/ou-orgid-xxxxxxxx'}]"

Important Notes

Region Specificity: AMI sharing is region-specific. If your AMI needs to be available in multiple regions for Instruqt tracks, you must copy the AMI to those regions and share it in each region separately.
Encrypted AMIs: If your AMI is encrypted with a custom AWS Key Management Service (KMS) key, you must also share the KMS key with the Instruqt organization, OU, or make it accessible in a way that allows public AMIs (if applicable, though encrypting public AMIs with custom keys has its own complexities) to be launched. Refer to the AWS documentation on sharing CMKs.
Communication: Always coordinate with your Instruqt representative to ensure you have the correct Organization or OU IDs (if using those methods) and to confirm when the AMI is accessible for track development. Discuss the implications if you are considering making an AMI public for use on their platform.
Security Best Practices: For proprietary or sensitive AMIs, always prefer sharing with specific OUs or the entire Instruqt Organization over making an AMI public. Public AMIs should only be used for content explicitly designed for unrestricted public access.

Prerequisites

Method 1: Making the AMI Public

Method 2: Sharing with the Entire Instruqt Organization

Method 3: Sharing with a Dedicated Organizational Unit (OU) per Team

Verifying Sharing

Stopping AMI Sharing

Important Notes

Further Reading