Identify your resources referencing specified AMIs - Amazon Elastic Compute Cloud
Supported resourcesHow AMI reference checks workRequired IAM permissionsSteps for checking AMI references

Identify your resources referencing specified AMIs

You can identify your AWS resources that reference specified Amazon Machine Images (AMIs), regardless of whether the AMIs are public or private, or who owns them. This visibility helps you ensure your resources use the latest compliant AMIs.

Key benefits

Checking AMI references helps you:

  • Audit the use of AMIs in your account.

  • Check where specific AMIs are being referenced.

  • Maintain compliance by updating your resources to reference the latest AMIs.

 

Supported resources

AMI references can be checked in:

  • EC2 instances

  • Launch templates

  • SSM parameters

  • Image Builder image recipes

  • Image Builder container recipes

How AMI reference checks work

Basic operation

When you run an AMI reference check, you:

  • Specify which AMIs to check.

  • Choose which resource types to scan.

  • Receive a list of your resources that reference the specified AMIs.

Resource type selection

In the console, you select the resource types to scan.

In the CLI, you specify resource types to scan using one or both of the following CLI parameters:

  • IncludeAllResourceTypes: Scans all supported resource types.

  • ResourceTypes: Scans your specified resource types.

Response scoping

You can scope the response for EC2 instances and launch templates by customizing the ResourceTypeOptions values using the ResourceTypes parameter. The console and IncludeAllResourceTypes parameter both use default option values. When ResourceTypes and IncludeAllResourceTypes are used together, the ResourceTypes option values take precedence over the defaults.

The following are the default values:

Resource type Scoping option (OptionName) Purpose Default values for OptionValue and console
EC2 instances state-name Filter by instance state pending, running, shutting-down, terminated, stopping, stopped (all states)
Launch templates version-depth Specify the number of launch template versions to check (starting from the most recent version) 10 (most recent versions)

Required IAM permissions

To use the DescribeImageReferences API to identify your resources that are referencing specified AMIs, you need the following IAM permissions to describe the resources:

  • ec2:DescribeInstances

  • ec2:DescribeLaunchTemplates

  • ec2:DescribeLaunchTemplateVersions

  • ssm:DescribeParameters

  • ssm:GetParameters

  • imagebuilder:ListImageRecipes

  • imagebuilder:ListContainerRecipes

  • imagebuilder:GetContainerRecipe

Example IAM policy for using the DescribeImageReferences API

The following example policy grants you the permissions to use the DescribeImageReferences API, which includes the permissions to describe EC2 instances, launch templates, Systems Manager parameters, Image Builder image recipes, and Image Builder container recipes.

JSON
{
	"Version": "2012-10-17"		 	 	 ,
	"Statement": [
		{
			"Effect": "Allow",
			"Action": "ec2:DescribeImageReferences",
			"Resource": "*"
		},
		{
			"Effect": "Allow",
			"Action": [
				"ec2:DescribeInstances",
				"ec2:DescribeLaunchTemplates",
				"ec2:DescribeLaunchTemplateVersions",
				"ssm:DescribeParameters",
				"ssm:GetParameters",
				"imagebuilder:ListImageRecipes",
				"imagebuilder:ListContainerRecipes",
				"imagebuilder:GetContainerRecipe"
			],
			"Resource": "*",
			"Condition": {
				"ForAnyValue:StringEquals": {
					"aws:CalledVia": [
						"ec2-images.amazonaws.com"
					]
				}
			}
		}
	]
}
Important

We strongly recommend using the AWS managed policy AmazonEC2ImageReferencesAccessPolicy instead of creating the policy yourself. Creating a custom IAM policy that provides only the required permissions requires time and expertise, and will require updates as new resource types become available.

The AmazonEC2ImageReferencesAccessPolicy managed policy:

  • Grants all the permissions needed to use the DescribeImageReferences API (these include the permissions to describe EC2 instances, launch templates, Systems Manager parameters, and Image Builder container and image recipes).

  • Automatically supports new resource types as they become available (especially important when using the IncludeAllResourceTypes parameter).

You can attach the AmazonEC2ImageReferencesAccessPolicy policy to your IAM identities (users, groups, and roles).

To view the permissions included in this policy, see AmazonEC2ImageReferencesAccessPolicy in the AWS Managed Policy Reference.

Steps for checking AMI references

Use the following procedures to identify which of your AWS resources are referencing specified AMIs.

Console
To identify resources referencing specified AMIs

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose AMIs.

  3. Select one or more AMIs to check for references.

  4. Choose Actions, AMI usage, View referenced resources.

  5. On the View resources referencing selected AMIs page:

    1. For Resource types, select one or more resource types.

    2. Choose View resources.

  6. The Resources referencing selected AMIs section appears. The list displays the resources referencing the specified AMIs. Each row provides the following information:

    • AMI ID – The ID of the referenced AMI.

    • Resource type – The resource type of the resource referencing the AMI.

    • Resource ID – The ID of the resource referencing the AMI.

AWS CLI
To check AMI references for specific resource types

Use the describe-image-references command with the --resource-types parameter. The following example checks EC2 instances (scoping by instance state), launch templates (scoping to the 20 most recent launch template versions), and other specific resource types.

aws ec2 describe-image-references \
    --image-ids ami-0abcdef1234567890 ami-1234567890abcdef0 \
    --resource-types \
        'ResourceType=ec2:Instance,ResourceTypeOptions=[{OptionName=state-name,OptionValues=[running,pending]}]' \
        'ResourceType=ec2:LaunchTemplate,ResourceTypeOptions=[{OptionName=version-depth,OptionValues=[20]}]' \
        'ResourceType=ssm:Parameter' \
        'ResourceType=imagebuilder:ImageRecipe' \
        'ResourceType=imagebuilder:ContainerRecipe'

The following is example output.

{
    "ImageReferences": [
        {
            "ImageId": "ami-0abcdef1234567890",
            "ResourceType": "ec2:Instance",
            "Arn": "arn:aws:ec2:us-east-1:123456789012:instance/i-1234567890abcdef0"
        },
        {
            "ImageId": "ami-1234567890abcdef0",
            "ResourceType": "ec2:LaunchTemplate",
            "Arn": "arn:aws:ec2:us-east-1:123456789012:launch-template/lt-1234567890abcdef0"
        }
    ]
}
To check AMI references for all the supported resource types

Use the describe-image-references command with the --include-all-resource-types parameter.

aws ec2 describe-image-references \
    --image-ids ami-0abcdef1234567890 ami-1234567890abcdef0 \
    --include-all-resource-types
To check AMI references for all supported resource types and specific options

Use the describe-image-references command with both the --include-all-resource-types and --resource-types parameters. This example checks all resource types while scoping the response for EC2 instances to running or pending instances.

aws ec2 describe-image-references \
    --image-ids ami-0abcdef1234567890 ami-1234567890abcdef0 \
    --include-all-resource-types \
    --resource-types 'ResourceType=ec2:Instance,ResourceTypeOptions=[{OptionName=state-name,OptionValues=[running,pending]}]'
PowerShell
To check AMI references for specific resource types

Use the Get-EC2ImageReference cmdlet with the -ResourceType parameter. The following example checks EC2 instances (scoping by instance state), launch templates (scoping to the 20 most recent launch template versions), and other specific resource types.

Get-EC2ImageReference `
    -ImageId 'ami-0abcdef1234567890', 'ami-1234567890abcdef0' `
    -ResourceType @(
        @{
            ResourceType = 'ec2:Instance'
            ResourceTypeOptions = @(
                @{
                    OptionName = 'state-name'
                    OptionValues = @('running', 'pending')
                }
            )
        },
        @{
            ResourceType = 'ec2:LaunchTemplate'
            ResourceTypeOptions = @(
                @{
                    OptionName = 'version-depth'
                    OptionValues = @('20')
                }
            )
        },
        @{
            ResourceType = 'ssm:Parameter'
        },
        @{
            ResourceType = 'imagebuilder:ImageRecipe'
        },
        @{
            ResourceType = 'imagebuilder:ContainerRecipe'
        }
    )
To check AMI references for all the supported resource types

Use the Get-EC2ImageReference cmdlet with the -IncludeAllResourceTypes parameter.

Get-EC2ImageReference `
    -ImageId 'ami-0abcdef1234567890', 'ami-1234567890abcdef0' `
    -IncludeAllResourceTypes
To check AMI references for all supported resource types and specific options

Use the Get-EC2ImageReference cmdlet with both the -IncludeAllResourceTypes and -ResourceType parameters. This example checks all resource types while scoping the response for EC2 instances to running or pending instances.

Get-EC2ImageReference `
    -ImageId 'ami-0abcdef1234567890', 'ami-1234567890abcdef0' `
    -IncludeAllResourceTypes `
    -ResourceType @(
        @{
            ResourceType = 'ec2:Instance'
            ResourceTypeOptions = @(
                @{
                    OptionName = 'state-name'
                    OptionValues = @('running', 'pending')
                }
            )
        }
    )