AWS Compute Blog

Using System Manager Parameter as an alias for AMI ID

This post was authored by Brian Terry, Senior Partner Solutions Architect, Cloud Management Tools Technical Lead.

In this post, I demonstrate how you can use AWS Systems Manager Parameter Store’s, native parameter support for Amazon Machine Image (AMI) IDs while launching Amazon EC2 instances. This removes the need to update all your scripts and templates with a new ID each time the AMI that you want to use in your process changes. Once created, you can reference this parameter in your templates, commands, and scripts. This feature simplifies automation maintenance.

Product Overview

Last year, Amazon EC2 announced native support for Systems Manager Parameter Store parameters in Amazon EC2 API operations for launching instances. Systems Manager Parameter Store allows you to create customer defined identifiers that point to an AMI ID. This makes it easier for you to select and use well-known or standardized resources during an EC2 instance launch, reducing the likelihood of instance misconfiguration and simplifying instance launches.

It’s possible to create parameters in multiple AWS Regions, which have the same name and region specific values. This simplifies implementing change centrally and achieving multi-Region consistency, minimizing the risk of deployment errors. Overall, parameters make it convenient for you to discover standardized resources, like golden AMIs. Golden AMIs enable organizations to easily implement governance and best practices. Automation code, which references these parameters, stays up to date because you’ll do not have to modify the code when you need to update the AMI. This simplifies maintenance of automation and helps drive down deployment costs.

Solution Overview

You can substitute the AMI ID with an AWS Systems Manager Parameter in an EC2 API call or the EC2 Console while launching an instance. EC2 resolves the parameter and uses the current value as the instance’s AMI input value. You can update the parameter’s value and all subsequent instance launches, use that AMI that parameter points to. For example, if you have an AMI that you update and publish weekly, you can now create a parameter and update the value with the new AMI ID. You can then use this parameter in the instance launch API, and you won’t need to update your automation every time the AMI ID changes.

In this blog, I set up the SSM parameter in the following steps:

  • Create a parameter of EC2 image datatype aws:ec2:image
  • Launch an Amazon EC2 instance.

Prerequisites

Before setting up and accessing parameters in Systems Manager Parameter Store, you must have the permissions to perform the actions. For information about theses permissions, visit the System Manager Parameter Store EC2 Alias documentation page.

Create an Amazon EC2 Alias

You can create an Amazon EC2 alias in two ways: 1/ the console and 2/ the AWS CLI.

Using the Console

I start by creating a parameter from the Parameter Store page of the AWS Systems Manager Console.

  1. Open the AWS Systems Manager console.
  2. In the navigation pane, choose Parameter Store.
  3. Choose Create parameter.
  4. In the Name box, enter web-server and enter a description.
    Creating a parameter in the AWS Systems Manager Console
  5. For DataType, I chose aws:ec2:image, and I input the value of my AMI. When I specify aws:ec2:image as the data type for a parameter, Systems Manager does not create the parameter immediately. Instead, it performs an asynchronous validation operation to ensure that the parameter value meets the formatting requirements for an AMI ID, and that the specified AMI is available in your AWS account. I can monitor whether the parameter created successfully in Amazon CloudWatch Events. System Manager sends notifications about whether a parameter operation was successful or not. If an operation fails, the notification includes an error message that indicates the reason for the failure.
    Select the aws:ec2:image data type for the parameter
  6. Then, choose Create parameter.

Alternatively, you can also create an Amazon EC2 alias using the AWS CLI.

Create an Amazon EC2 Alias Using AWS CLI

To create the Amazon EC2 Alias using the AWS CLI, input the following command:

$ aws ssm put-parameter --name "web-server" --value "ami-1234abcd" --type "String" --datatype "aws:ec2:image"

Now that you created an EC2 alias, you can launch an EC2 instance.

Launch EC2 instance

You can launch an Amazon EC2 instance in two ways: 1/ the console and 2/ the AWS CLI.

 Using the Console

  1. Open the Amazon EC2 console.
  2. In the navigation bar at the top of the screen, the current Region is displayed (for example, US East (Ohio)). Select a Region for the instance that meets your needs.
  3. From the Amazon EC2 console, click the Search by System Manager parameter link.
  4. In the pop-up box, I select the web-server I created earlier.
    Use the parameter in the Amazon EC2 console
  5. On the Choose an Instance Type page, I select m5.xlarge
  6. Using the defaults, choose Review and Launch.

Using the AWS CLI

You can also launch an EC2 instance using the AWS CLI. While using a parameter in an EC2 API, it must have a ‘resolve:ssm:’ prefix, such that when you refer to the parameter it looks like ‘resolve:ssm:parameter-name’. For example, I can create and use a parameter for an AMI in a given Region from CLI as follows:

$ aws ec2 run-instances --image-id "resolve:ssm:web-server" --instance-type m5.xlarge

Now your instance is launched.

Use public parameters as aliases

With public parameters, authorized accounts (such as trusted OS partners) can publish parameters in their accounts to allow all external customers to access and use in API calls. This allows you to easily find the latest AMI.

For example, the EC2 Linux team publishes their latest AMI IDs as public parameters so customers can quickly get the latest AMI ID by performing a get operation on a well-known path in the Parameter store.

Amazon EC2 AMI public parameters are available from the following path:

/aws/service/ami-amazon-linux-latest

You can view a list of all Linux AMIs in the current AWS Region by using the following command in the AWS CLI.

$ aws ssm get-parameters-by-path \
--path /aws/service/ami-amazon-linux-latest \
--query 'Parameters[].Name'

The command returns information like the following.

[
“/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-ebs”,
“/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2”,
“/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-s3”,
“/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-hvm-x86_64-s3”,
“/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-pv-x86_64-s3”,
“/aws/service/ami-amazon-linux-latest/amzn-ami-pv-x86_64-s3”,
“/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-arm64-gp2”,
“/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-ebs”,
“/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2”,
“/aws/service/ami-amazon-linux-latest/amzn2-ami-minimal-hvm-arm64-ebs”,
“/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-hvm-x86_64-ebs”,
“/aws/service/ami-amazon-linux-latest/amzn-ami-minimal-pv-x86_64-ebs”,
“/aws/service/ami-amazon-linux-latest/amzn-ami-pv-x86_64-ebs”,
“/aws/service/ami-amazon-linux-latest/amzn2-ami-minimal-hvm-x86_64-ebs”
]

At launch, we onboarded OS-partners Canonical, Debian, Red Hat, FreeBSD, SuSE, CentOS, Fedora, Microsoft, OpenSUSE, and Oracle to public parameters so that they can publish latest AMI IDs for customers to programmatically access.

For example, you can reference latest AMI IDs published by Canonical using path:

$ aws ssm get-parameters-by-path --path /aws/service/canonical --recursive --query 'Parameters[].Name'

The command returns information like the following.

[
“/aws/service/canonical/ubuntu/server-minimal/16.04/meta/end-of-extended-security-maintenance-date”,
“/aws/service/canonical/ubuntu/server-minimal/16.04/meta/end-of-extended security-maintenance-date”,
“/aws/service/canonical/ubuntu/server/18.04/stable/current/amd64/hvm/ebs-gp2/ami-id”,
]

You can launch an instance by substituting the AMI ID with the path to the public parameter.

$ aws ec2 run-instances \
    --image-id resolve:ssm:/aws/service/canonical/ubuntu/server-minimal/16.04/meta/end-of-extended-security-maintenance-date
    --count 1 \
    --instance-type t2.micro \
    --key-name my-key-pair \
    --security-groups my-security-group

In summary, with public parameters, you can easily find and use the latest AMI of a trusted OS partners.

Conclusion

Systems Manager Parameter Store’s Native parameter support for AMI IDs makes it easy for you to implement change centrally, achieve multi-Region consistency, and minimize the risk of deployment errors. Additionally, you can conveniently discover standardized resources, like golden AMIs, and make it easier for your organizations to implement governance and best practices.