DEV Community

Cover image for Finding public SSM parameters for AMIs with the EC2 DescribeImages API
Aparna Krishnamoorthy
Aparna Krishnamoorthy

Posted on

Finding public SSM parameters for AMIs with the EC2 DescribeImages API

#aws #parameterstore #ec2

Services like EC2 and ECS require an AMI ID at launch time, which pins the instance to a specific OS image. AMIs from AWS and its partners get patched often, and each patch ships as a new ID. If you hardcode that ID, it goes stale quickly and your infrastructure drifts behind the latest patches.

The standard fix is to use a public SSM parameter — a well-known path that always resolves to the current AMI in a given family. That works great for new deployments, but what about existing code where the AMI ID is already baked in? Finding the right parameter used to mean navigating cryptic /aws/service/ hierarchies, guessing naming conventions, and making dozens of GetParametersByPathcalls. This tedious process not only slowed down workflows but also introduced the risk of selecting the wrong parameter, potentially leading to deployment issues.

A new EC2 feature eliminates that friction: the DescribeImages API now includes a PublicSsmParameterName field that tells you exactly which parameter maps to a given AMI.

Finding the SSM parameter for a public AMI in DescribeImages

You can avoid the manual search by retrieving the parameter name from DescribeImages.

aws ec2 describe-images \
 --region us-east-1 \
 --image-ids ami-1234567890abcdef0 \
 --query 'Images[*].{ImageId:ImageId,PublicSsmParameterName:PublicSsmParameterName}'

[
 {
 "ImageId": "ami-1234567890abcdef0",
 "PublicSsmParameterName": "aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64"
 }
]
Enter fullscreen mode Exit fullscreen mode

The parameter will now resolve to the updated AMI than the one you described if the publisher has released a newer version.

Adding the leading slash before using the parameter

When you copy the parameter name from the EC2 DescribeImages API, note that it doesn't have the leading slash required by Parameter Store.

aws ssm get-parameter \
 --region us-east-1 \
 --name "aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64"
Enter fullscreen mode Exit fullscreen mode 

ValidationException: Parameter name: can't be prefixed with "ssm"...
Enter fullscreen mode Exit fullscreen mode

Add a leading / to avoid the error.

aws ssm get-parameter \
 --region us-east-1 \
 --name "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64"
Enter fullscreen mode Exit fullscreen mode

Using a parameter instead of a hardcoded AMI ID

Reference the parameter returned by DescribeImages directly in your infrastructure code.

In the following CloudFormation example, you define a parameter of type AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>, and use it for the ImageId property.

Parameters:
 LatestAmiId:
 Type: AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>
 Default: /aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64
Enter fullscreen mode Exit fullscreen mode 
Resources:
 Instance:
 Type: AWS::EC2::Instance
 Properties:
 ImageId: !Ref LatestAmiId
 InstanceType: t3.micro
Enter fullscreen mode Exit fullscreen mode

In the following CDK example, you pass the same parameter name to MachineImage.fromSsmParameter().

const machineImage = ec2.MachineImage.fromSsmParameter(
'/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64'
);
Enter fullscreen mode Exit fullscreen mode 
new ec2.Instance(this, 'Instance', {
 vpc,
 instanceType: ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.MICRO),
 machineImage,
});
Enter fullscreen mode Exit fullscreen mode

Both approaches resolve the parameter when you create or update the stack, not on every new instance launch, so an update is still reviewable and tied to your normal deployment process.

In the following example, you use the resolve:ssm: prefix on the ImageId. New instances resolve the parameter at launch time, so they can use the current AMI in that AMI family without a redeploy.

aws ec2 create-launch-template \
 --region us-east-1 \
 --launch-template-name my-template \
 --version-description version1 \
 --launch-template-data '{"ImageId":"resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64","InstanceType":"t3.micro"}'
Enter fullscreen mode Exit fullscreen mode

Summary

DescribeImages returns the public SSM parameter associated with a public AMI family. Reference that parameter in your launch and deployment code to avoid manually searching for it. Remember to add the leading slash to the parameter name when retrieving it from Parameter Store.

Top comments (1)

Collapse
 
merbayerp profile image
Mustafa ERBAY •

This is a really useful bridge from a hardcoded AMI to a maintainable AMI family.

One operational detail I’d be careful with is where the SSM parameter gets resolved.

Resolving “latest” during a controlled CloudFormation/CDK deployment gives you a natural approval point. Resolving it at instance launch is more dynamic, but it also means two instances created from the same logical configuration at different times may boot different AMI versions.

That can turn image drift into reproducibility drift.

For production environments, I like the pattern of using the public SSM parameter for discovery, then resolving and recording the resulting AMI ID as part of the deployment artifact. You still get automated discovery of patched images, but promotion remains explicit and rollback points remain deterministic.

It would also make a nice CI gate: detect when the public parameter changes, test the new AMI, then promote the resolved ID after validation.

So perhaps the interesting distinction isn’t simply hardcoded AMI vs SSM parameter, but “automatic discovery” vs “automatic adoption.”