Control the discovery and use of AMIs in Amazon EC2 with Allowed AMIs - Amazon Elastic Compute Cloud
How Allowed AMIs worksBest practices for implementing Allowed AMIsRequired IAM permissionsEnable audit mode and specify criteriaEnable Allowed AMIsDisable Allowed AMIsUpdate Allowed AMIs criteriaIdentify Allowed AMIs state and criteriaIdentify AMIs that meet the Allowed AMIs criteriaIdentify whether instances were launched with AMIs that aren't allowed
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).

Control the discovery and use of AMIs in Amazon EC2 with Allowed AMIs

To control the discovery and use of Amazon Machine Images (AMIs) by users in your Amazon Web Services account, you can use the Allowed AMIs feature. This feature allows you to specify criteria that AMIs must meet to be visible and available within your account. When the criteria are enabled, users launching instances will only see and have access to AMIs that comply with the specified criteria. For example, you can specify a list of trusted AMI providers as the criteria, and only AMIs from these providers will be visible and available for use.

Before enabling the Allowed AMIs settings, you can enable audit mode to preview which AMIs will or won't be visible and available for use. This lets you refine the criteria as needed to ensure that only the intended AMIs are visible and available to users in your account. Additionally, you can run the describe-instance-image-metadata command and filter the response to identify any instances that were launched with AMIs that don't meet the specified criteria. This information can guide your decision to either update your launch configurations to use compliant AMIs (for example, specifying a different AMI in a launch template) or adjust your criteria to allow these AMIs.

You specify the Allowed AMIs settings at the account level, either directly in the account or by using a declarative policy. These settings must be configured in each Amazon Web Services Region where you want to control the discovery and use of AMIs. Using a declarative policy allows you to apply the settings across multiple Regions simultaneously, as well as across multiple accounts simultaneously. When a declarative policy is in use, you can't modify the settings directly within an account. This topic describes how to configure the settings directly within an account. For information about using declarative policies, see Declarative policies in the Amazon Organizations User Guide.

Note

The Allowed AMIs feature only controls the discovery and use of public AMIs or AMIs shared with your account. It does not restrict the AMIs owned by your account. Regardless of the criteria you set, the AMIs created by your account will always be discoverable and usable by users in your account.

Key benefits of Allowed AMIs

  • Compliance and security: Users can only discover and use AMIs that meet the specified criteria, reducing the risk of non-compliant AMI usage.

  • Efficient management: By reducing the number of allowed AMIs, managing the remaining ones becomes easier and more efficient.

  • Centralized account-level implementation: Configure the Allowed AMIs settings at the account level, either directly within the account or through a declarative policy. This provides a centralized and efficient way to control AMI usage across the entire account.

How Allowed AMIs works

You specify criteria that automatically filter and determine which AMIs can be discovered and used in your account. You specify the criteria in JSON configuration, and then enable the criteria by running the enable API operation.

JSON configuration for the Allowed AMIs criteria

The core configuration for Allowed AMIs is the JSON configuration that defines the criteria for allowed AMIs.

Currently, the only supported criteria are AMI providers. Valid values are aliases that are defined by Amazon, and Amazon Web Services account IDs, as follows:

  • amazon – An alias that identifies AMIs created by Amazon

  • aws-marketplace – An alias that identifies AMIs created by verified providers in the Amazon Web Services Marketplace

  • aws-backup-vault – An alias that identifies backup AMIs that reside in logically air-gapped Amazon Backup vault accounts. If you use the Amazon Backup logically air-gapped vault feature, ensure this alias is included as an AMI provider.

  • Amazon Web Services account IDs – One or more 12-digit Amazon Web Services account IDs

  • none – Indicates that only AMIs created by your account can be discovered and used. Public or shared AMIs can't be discovered and used. If you specify none, you can't specify an alias or account ID.

The AMI criteria are specified in JSON format. Here's an example that specifies two aliases and three Amazon Web Services account IDs:

{
    "ImageCriteria": [
        {
            "ImageProviders": [
                "amazon",
                "aws-marketplace",
                "123456789012",
                "112233445566",
                "009988776655"
            ]
        }
    ]
}
Limits for the JSON configuration

  • ImageCriteria objects: Maximum of 10 ImageCriteria objects can be specified in a single configuration.

  • ImageProviders values: Maximum of 200 values across all ImageCriteria objects.

Example of limits

Consider the following example to illustrate these limits, where different ImageProviders lists are used to group the AMI provider accounts: 

{
    "ImageCriteria": [
        {
            "ImageProviders": ["amazon", "aws-marketplace"]
        },
        {
            "ImageProviders": ["123456789012", "112233445566", "121232343454"]
        },
        {
            "ImageProviders": ["998877665555", "987654321098"]
        }
        // Up to 7 more ImageCriteria objects can be added
        // Up to 193 more ImageProviders values can be added
    ]
}

In this example:

  • There are 3 imageCriteria objects (up to 7 more can be added to reach the limit of 10).

  • There are 7 total imageProviders values across all objects (up to 193 more can be added to reach the limit of 200).

In this example, AMIs are allowed from any of the specified AMI providers in all of the ImageCriteria objects.

Allowed AMIs operations

The Allowed AMIs feature has three operational modes for managing the image criteria: enabled, disabled, and audit mode. These allow you to enable or disable the image criteria, or review them as needed.

Enabled

When Allowed AMIs is enabled:

  • The ImageCriteria are applied.

  • Only allowed AMIs are discoverable in the EC2 console and by APIs that use images (for example, that describe, copy, store, or perform other actions that use images).

  • Instances can only be launched using allowed AMIs.

Disabled

When Allowed AMIs is disabled:

  • The ImageCriteria are not applied.

  • No restrictions are placed on AMI discoverability or usage.

Audit mode

In audit mode:

  • The ImageCriteria are applied, but no restrictions are placed on AMI discoverability or usage.

  • In the EC2 console, for each AMI, the Allowed image field displays either Yes or No to indicate whether the AMI will be discoverable and available to users in the account when Allowed AMIs is enabled.

  • In the command line, the response for the describe-image operation includes "ImageAllowed": true or "ImageAllowed": false to indicate whether the AMI will be discoverable and available to users in the account when Allowed AMIs is enabled.

  • In the EC2 console, the AMI Catalog displays Not allowed next to AMIs that won't be discoverable or available to users in the account when Allowed AMIs is enabled.

Best practices for implementing Allowed AMIs

When implementing Allowed AMIs, consider these best practices to ensure a smooth transition and minimize potential disruptions to your Amazon environment.

  1. Enable audit mode

    Begin by enabling Allowed AMIs in audit mode. This mode allows you to see which AMIs would be affected by your criteria without actually restricting access, providing a risk-free evaluation period.

  2. Set Allowed AMIs criteria

    Carefully establish which AMI providers align with your organization's security policies, compliance requirements, and operational needs.

    Note

    We recommend specifying the amazon alias to allow AMIs created by Amazon, ensuring that Amazon managed services you use can continue to launch EC2 instances in your account.

  3. Check for impact on expected business processes

    Run the describe-instance-image-metadata command and filter the response to identify any instances that were launched with AMIs that don't meet the specified criteria. This information can guide your decision to either update your launch configurations to use compliant AMIs (for example, specifying a different AMI in a launch template) or adjust your criteria to allow these AMIs.

  4. Enable Allowed AMIs

    Once you've confirmed that the criteria will not adversely affect expected business processes, enable Allowed AMIs.

  5. Monitor instance launches

    Continue to monitor instance launches from AMIs across your applications and the Amazon managed services you use, such as Amazon EMR, Amazon ECR, Amazon EKS, and Amazon Elastic Beanstalk. Check for any unexpected issues and make necessary adjustments to the Allowed AMIs criteria.

  6. Pilot new AMIs

    To test third-party AMIs that do not comply with your current Allowed AMIs settings, Amazon recommends the following approaches:

    • Use a separate Amazon Web Services account: Create an account with no access to your business-critical resources. Ensure that the Allowed AMIs setting is not enabled in this account, or that the AMIs you want to test are explicitly allowed, so that you can test them.

    • Test in another Amazon Web Services Region: Use a Region where the third-party AMIs are available, but where you have not yet enabled the Allowed AMIs settings.

    These approaches help ensure your business-critical resources remain secure while you test new AMIs.

Required IAM permissions

To use the Allowed AMIs feature, you need the following IAM permissions:

  • GetAllowedImagesSettings

  • EnableAllowedImagesSettings

  • DisableAllowedImagesSettings

  • ReplaceImageCriteriaInAllowedImagesSettings

Enable audit mode and specify criteria

Use the following procedures to enable the audit mode for Allowed AMIs and specify the Allowed AMIs criteria in your account for the specified Region.

Console
To enable audit mode and specify criteria for Allowed AMIs

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Dashboard.

  3. Under Account attributes (top right), choose Allowed AMIs.

  4. On the Allowed AMIs page, do the following:

    1. Choose Manage.

    2. For Allowed AMIs settings, choose Audit mode.

    3. For AMI criteria, specify the criteria in JSON format. Currently, only image providers can be specified as criteria.

      For the correct configuration and valid values, see JSON configuration for the Allowed AMIs criteria.

    4. Choose Update.

Amazon CLI
To enable audit mode and specify criteria for Allowed AMIs

  1. Enable audit mode

    Use the enable-allowed-images-settings command and specify audit-mode in the specified Region.

    aws ec2 enable-allowed-images-settings \
    --region us-east-1 \
    --allowed-images-settings-state audit-mode

    Expected output

    {
"AllowedImagesSettingsState": "audit-mode"
}

  2. Specify the criteria

    Use the replace-image-criteria-in-allowed-images-settings command and reference a JSON file with the image criteria.

    Currently, only image providers are supported for image criteria. For the correct configuration and valid values, see JSON configuration for the Allowed AMIs criteria.

    aws ec2 replace-image-criteria-in-allowed-images-settings \
    --region us-east-1 \
    --cli-input-json file://path/to/image-criteria.json

Enable Allowed AMIs

Use the following procedures to enable Allowed AMIs in your account for the specified Region.

Console
To enable Allowed AMIs

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Dashboard.

  3. Under Account attributes (top right), choose Allowed AMIs.

  4. On the Allowed AMIs page, do the following:

    1. Choose Manage.

    2. For Allowed AMIs settings, choose Enabled.

    3. For AMI criteria, specify the criteria in JSON format. Currently, only image providers can be specified as criteria.

      For the correct configuration and valid values, see JSON configuration for the Allowed AMIs criteria.

    4. Choose Update.

Amazon CLI
To enable Allowed AMIs and specify criteria for Allowed AMIs

  1. Enable Allowed AMIs

    Use the enable-allowed-images-settings command and specify enable in the specified Region.

    aws ec2 enable-allowed-images-settings \
    --region us-east-1 \
    --allowed-images-settings-state enabled

    Expected output

    {
"AllowedImagesSettingsState": "enabled"
}

  2. Specify the criteria

    Use the replace-image-criteria-in-allowed-images-settings command and reference a JSON file with the image criteria.

    Currently, only image providers are supported for image criteria. For the correct configuration and valid values, see JSON configuration for the Allowed AMIs criteria.

    aws ec2 replace-image-criteria-in-allowed-images-settings \
    --region us-east-1 \
    --cli-input-json file://path/to/image-criteria.json

Disable Allowed AMIs

Use the following procedures to disable Allowed AMIs in your account for the specified Region.

Console
To disable Allowed AMIs

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Dashboard.

  3. Under Account attributes (top right), choose Allowed AMIs.

  4. On the Allowed AMIs page, do the following:

    1. Choose Manage.

    2. For Allowed AMIs settings, choose Disabled.

    3. Choose Update.

Amazon CLI
To disable Allowed AMIs

Use the disable-allowed-images-settings command to disable Allowed AMIs in the specified Region.

aws ec2 disable-allowed-images-settings \
    --region us-east-1

Expected output

{
"AllowedImagesSettingsState": "disabled"
}

Update Allowed AMIs criteria

Use the following procedures to update the Allowed AMIs criteria in your account for the specified Region.

Console
To update the Allowed AMIs criteria

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Dashboard.

  3. Under Account attributes (top right), choose Allowed AMIs.

  4. On the Allowed AMIs page, do the following:

    1. Choose Manage.

    2. For Allowed AMIs settings, choose either Enabled or Audit mode.

    3. For AMI criteria, specify the criteria in JSON format. Currently, only image providers can be specified as criteria.

      For the configuration and valid values, see JSON configuration for the Allowed AMIs criteria.

    4. Choose Update.

Amazon CLI
To update the Allowed AMIs criteria

Use the replace-image-criteria-in-allowed-images-settings command and reference a JSON file with the image criteria. Currently, only image providers are supported for image criteria. For the JSON configuration and valid values, see JSON configuration for the Allowed AMIs criteria.

aws ec2 replace-image-criteria-in-allowed-images-settings \
    --region us-east-1 \
    --cli-input-json file://path/to/image-criteria.json

Identify Allowed AMIs state and criteria

Use the following procedures to identify the current state of the Allowed AMIs setting and the Allowed AMIs criteria.

Console
To identify the Allowed AMIs state and criteria

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Dashboard.

  3. Under Account attributes (top right), choose Allowed AMIs.

  4. On the Allowed AMIs page, do the following:

    1. Choose Manage.

    2. For Allowed AMIs settings, check the current selection. It is either Enabled, Disabled, or Audit mode.

    3. For AMI criteria, check the criteria in JSON format. If the state is Disabled, the criteria are not displayed. To display the criteria, choose either Enabled or Audit mode.

    4. Choose Cancel to close the screen without making any changes.

Amazon CLI
To identify the Allowed AMIs state and criteria

Use the get-allowed-images-settings command to get the current state and list of the Allowed AMIs criteria in the specified Region.

aws ec2 get-allowed-images-settings \
    --region us-east-1

In the following example output, the state is audit-mode and the AMI provider list includes one provider (amazon).

The ManagedBy field indicates the entity that configured the Allowed AMIs settings. In this example, account indicates that the settings were configured within the account itself. A value of declarative-policy would mean the settings were configured by a declarative policy. For more information, see Declarative policies in the Amazon Organizations User Guide.

{
    "State": "audit-mode",
    "ImageCriteria": [
        {
            "ImageProviders": [
                "amazon"
            ]
        }
    ],
    "ManagedBy": "account"
}

Identify AMIs that meet the Allowed AMIs criteria

Use the following procedures to identify the AMIs that are allowed or not allowed for the account.

Note

The following can only be done when Allowed AMIs is in audit mode.

Console
To identify the AMIs that meet the Allowed AMIs criteria

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose AMIs.

  3. Select an AMI you want to check.

  4. On the Details tab (if you selected the checkbox) or in the summary area (if you selected the AMI ID), find the Allowed image field.

    • A value of Yes indicates an AMI that meets the Allowed AMIs criteria. This AMI will be visible and available to users in your account when Allowed AMIs is enabled.

    • A value of No indicates an AMI that does not meet the Allowed AMIs criteria. This AMI won't be visible or available to users in your account when Allowed AMIs is enabled.

  5. In the navigation pane, choose AMI Catalog.

    An AMI marked Not allowed indicates an AMI that does not meet the Allowed AMIs criteria. This AMI won't be visible or available to users in your account when Allowed AMIs is enabled.

Amazon CLI
To identify whether an AMI meets the Allowed AMIs criteria

Use the describe-images command and specify the AMI ID.

aws ec2 describe-images \
    --region us-east-1 \
    --image-id ami-1234567890example

Expected output - ImageAllowed is either true or false

{
    "Images": [{
        "Architecture": "x86_64",
        "CreationDate": "2022-09-21T17:11:12.000Z",
        "ImageId": "ami-1234567890example",
        "ImageLocation": "232700224022/ami_copy_test",
        "ImageType": "machine",
        "Public": false,
        "OwnerId": "111111111111",
        "PlatformDetails": "Linux/UNIX",
        "UsageOperation": "RunInstances",
        "State": "available",
        "BlockDeviceMappings": [{
            "DeviceName": "/dev/xvda",
            "Ebs": {
                "DeleteOnTermination": true,
                "SnapshotId": "snap-1234567890example",
                "VolumeSize": 8,
                "VolumeType": "gp2",
                "Encrypted": false
            }
        }],
        "Description": "ami_copy_test",
        "EnaSupport": true,
        "Hypervisor": "xen",
        "Name": "ami_copy_test",
        "RootDeviceName": "/dev/xvda",
        "RootDeviceType": "ebs",
        "SriovNetSupport": "simple",
        "VirtualizationType": "hvm",
        "ImageAllowed": false
    }]
}
To filter to AMIs that meet the Allowed AMIs criteria

Use the describe-images command and specify the image-allowed filter set to true.

aws ec2 describe-images \
    --region us-east-1 \
    --filters "Name=image-allowed,Values=true" \
    --max-result 10

Identify whether instances were launched with AMIs that aren't allowed

Use the following procedures to identify the instances that were launched with an AMI that does not meet the Allowed AMIs criteria.

Console
To identify whether an instance was launched with an AMI that isn't allowed

  1. Open the Amazon EC2 console at https://console.amazonaws.cn/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select an instance you want to check.

  4. On the Details tab, under Instance details, find the Allowed image field.

    • A value of Yes indicates an AMI that meets the Allowed AMIs criteria.

    • A value of No indicates an AMI that does not meet the Allowed AMIs criteria.

Amazon CLI
To identify whether instances were launched with AMIs that aren't allowed

Use the describe-instance-image-metadata command with the image-allowed filter set to false to identify instances that were launched with AMIs that are not allowed.

aws ec2 describe-instance-image-metadata \
    --region us-east-1 \
    --filters "Name=image-allowed,Values=false" \
    --max-result 10

Example output

{
    "InstanceImageMetadata": [
    {
        "InstanceId": "i-1234567890example",
        "InstanceType": "t3.nano",
        "LaunchTime": "2024-10-10T15:55:37+00:00",
        "AvailabilityZone": "USMA62",
        "State": {
            "Code": 16,
            "Name": "running"
            },
        "OwnerId": "111111111111",,
        "ImageMetadata": {
            "ImageId": "ami-1234567890example",
            ...
            "ImageAllowed": false,
            "IsPublic": false
            }
        }
    ],
    "NextToken": "..."
}