Retrieving Amazon ECS-optimized Windows AMI metadata
The AMI ID, image name, operating system, container agent version, and runtime version for each variant of the Amazon ECS-optimized AMIs can be programmatically retrieved by querying the Systems Manager Parameter Store API. For more information about the Systems Manager Parameter Store API, see GetParameters and GetParametersByPath.
Note
Your administrative user must have the following IAM permissions to retrieve the
Amazon ECS-optimized AMI metadata. These permissions have been added to the
AmazonECS_FullAccess
IAM policy.
-
ssm:GetParameters
-
ssm:GetParameter
-
ssm:GetParametersByPath
Systems Manager Parameter Store parameter format
Note
The following Systems Manager Parameter Store API parameters are deprecated and should not be used to retrieve the latest Windows AMIs:
-
/aws/service/ecs/optimized-ami/windows_server/2016/english/full/recommended/image_id
-
/aws/service/ecs/optimized-ami/windows_server/2019/english/full/recommended/image_id
The following is the format of the parameter name for each Amazon ECS-optimized AMI variant.
-
Windows Server 2022 Full AMI metadata:
/aws/service/ami-windows-latest/Windows_Server-2022-English-Full-ECS_Optimized
-
Windows Server 2022 Core AMI metadata:
/aws/service/ami-windows-latest/Windows_Server-2022-English-Core-ECS_Optimized
-
Windows Server 2019 Full AMI metadata:
/aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized
-
Windows Server 2019 Core AMI metadata:
/aws/service/ami-windows-latest/Windows_Server-2019-English-Core-ECS_Optimized
-
Windows Server 2016 Full AMI metadata:
/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-ECS_Optimized
The following parameter name format retrieves the metadata of the latest stable Windows Server 2019 Full AMI
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized
The following is an example of the JSON object that is returned for the parameter value.
{ "Parameters": [ { "Name": "/aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized", "Type": "String", "Value": "{\"image_name\":\"Windows_Server-2019-English-Full-ECS_Optimized-2023.06.13\",\"image_id\":\"ami-0debc1fb48e4aee16\",\"ecs_runtime_version\":\"Docker (CE) version 20.10.21\",\"ecs_agent_version\":\"1.72.0\"}", "Version": 58, "LastModifiedDate": "2023-06-22T19:37:37.841000-04:00", "ARN": "arn:aws:ssm:us-east-1::parameter/aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized", "DataType": "text" } ], "InvalidParameters": [] }
Each of the fields in the output above are available to be queried as sub-parameters. Construct the parameter path for a sub-parameter by appending the sub-parameter name to the path for the selected AMI. The following sub-parameters are available:
-
schema_version
-
image_id
-
image_name
-
os
-
ecs_agent_version
-
ecs_runtime_version
Examples
The following examples show ways in which you can retrieve the metadata for each Amazon ECS-optimized AMI variant.
Retrieving the metadata of the latest stable Amazon ECS-optimized AMI
You can retrieve the latest stable Amazon ECS-optimized AMI using the AWS CLI with the following AWS CLI commands.
-
For the Amazon ECS-optimized Windows Server 2022 Full AMI:
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2022-English-Full-ECS_Optimized --region
us-east-1
-
For the Amazon ECS-optimized Windows Server 2022 Core AMI:
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2022-English-Core-ECS_Optimized --region
us-east-1
-
For the Amazon ECS-optimized Windows Server 2019 Full AMI:
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized --region
us-east-1
-
For the Amazon ECS-optimized Windows Server 2019 Core AMI:
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2019-English-Core-ECS_Optimized --region
us-east-1
-
For the Amazon ECS-optimized Windows Server 2016 Full AMI:
aws ssm get-parameters --names /aws/service/ami-windows-latest/Windows_Server-2016-English-Full-ECS_Optimized --region
us-east-1
Using the latest recommended Amazon ECS-optimized AMI in an AWS CloudFormation template
You can reference the latest recommended Amazon ECS-optimized AMI in an AWS CloudFormation template by referencing the Systems Manager parameter store name.
Parameters: LatestECSOptimizedAMI: Description: AMI ID Type: AWS::SSM::Parameter::Value<AWS::EC2::Image::Id> Default:
/aws/service/ami-windows-latest/Windows_Server-2019-English-Full-ECS_Optimized/image_id