AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Outputs a collection of one or more Amazon Machine Images using either a set of supplied service-pack independent'logical' name pattern(s), or a set of custom name patterns. The set of service-pack independent logical names can be viewed using the -ShowFilters switch.

Syntax

Get-EC2ImageByName
-Name <String[]>
-ShowFilters <SwitchParameter>
-AllAvailable <SwitchParameter>
-ClientConfig <AmazonEC2Config>

Description

Outputs a collection of one or more Amazon Machine Images using either a set of supplied service-pack independent 'logical' name pattern(s), or a set of custom name patterns. The set of service-pack independent logical names can be viewed using the -ShowFilters switch. If more than one name pattern is supplied (built-in or custom) then all available machine images that match the pattern are output. If only a single name pattern is supplied and it corresponds to one of the built-in service-pack independent names, then only the very latest machine image that matches is output. To see all versions of a machine image that correspond to a built-in name, use the -AllAvailable switch. This cmdlet is deprecated and will be removed in a future version. Use Get-SSMLatestEC2Image instead.

Parameters

-AllAvailable <SwitchParameter>
Amazon Web Services periodically refreshes machine images and 'deprecates' the prior versions. For a time it is possible for more than one image to correspond to a given logical filter.If this switch is specified and the name filter(s) supplied to the cmdlet are recognized as service pack independent 'logical' filters (i.e. the filter names shown if the -ShowFilters switch is supplied) then the cmdlet will emit all of the images corresponding to the filter. By default, the older images are suppressed and only the very latest image corresponding to the filter is output.If the supplied name filter(s) are not recognized (i.e. they are custom naming patterns of your own construction) then this switch is ignored and all matching images are returned.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ClientConfig <AmazonEC2Config>
Amazon.PowerShell.Cmdlets.EC2.AmazonEC2ClientCmdlet.ClientConfig
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Name <String[]>
A collection of one or more name patterns to use as filters to select an image. If this parameter is not specified, the set of built-in service-pack independent names are output.If the name supplied is recognized as one of the built-in service pack independent 'logical' names, it will be replaced internally by the corresponding pattern mapped by the logical name and used to query EC2 to find the latest available image corresponding to that name pattern. Using independent names means your script will continue to work even after AMIs are deprecated as new service packs are released. Names containing service pack/RTM designations can be deprecated as machine images are periodically refresh and eventually removed from the set of Amazon-published AMIs.If more than one value is supplied for this parameter, all machine images matching the name pattern are output, irrespective of whether the names supplied are from the built-in service-pack independent set or are custom name patterns of your own making.If a single value is supplied and it matches one of the built-in service-pack independent 'logical' names then only the very latest machine image corresponding to that name is output. Use the -AllAvailable switch to obtain the latest plus prior versions of the AMI.
Required?False
Position?1
Accept pipeline input?True (ByValue, ByPropertyName)
AliasesFilterNames, Names
-ShowFilters <SwitchParameter>
If set, the cmdlet emits the actual name pattern used to filter the machine images.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)

Common Credential and Region Parameters

-AccessKey <String>
The AWS access key for the user account. This can be a temporary access key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAK
-Credential <AWSCredentials>
An AWSCredentials object instance containing access and secret key information, and optionally a token for session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-EndpointUrl <String>
The endpoint to make the call against.Note: This parameter is primarily for internal AWS use and is not required/should not be specified for normal usage. The cmdlets normally determine which endpoint to call based on the region specified to the -Region parameter or set as default in the shell (via Set-DefaultAWSRegion). Only specify this parameter if you must direct the call to a specific custom endpoint.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-NetworkCredential <PSCredential>
Used with SAML-based authentication when ProfileName references a SAML role profile. Contains the network credentials to be supplied during authentication with the configured identity provider's endpoint. This parameter is not required if the user's default network identity can or should be used during authentication.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-ProfileLocation <String>
Used to specify the name and location of the ini-format credential file (shared with the AWS CLI and other AWS SDKs)If this optional parameter is omitted this cmdlet will search the encrypted credential file used by the AWS SDK for .NET and AWS Toolkit for Visual Studio first. If the profile is not found then the cmdlet will search in the ini-format credential file at the default location: (user's home directory)\.aws\credentials.If this parameter is specified then this cmdlet will only search the ini-format credential file at the location given.As the current folder can vary in a shell or during script execution it is advised that you use specify a fully qualified path instead of a relative path.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAWSProfilesLocation, ProfilesLocation
-ProfileName <String>
The user-defined name of an AWS credentials or SAML-based role profile containing credential information. The profile is expected to be found in the secure credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. You can also specify the name of a profile stored in the .ini-format credential file used with the AWS CLI and other AWS SDKs.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesStoredCredentials, AWSProfileName
-Region <Object>
The system name of an AWS region or an AWSRegion instance. This governs the endpoint that will be used when calling service operations. Note that the AWS resources referenced in a call are usually region-specific.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesRegionToCall
-SecretKey <String>
The AWS secret key for the user account. This can be a temporary secret key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSK, SecretAccessKey
-SessionToken <String>
The session token if the access and secret keys are temporary session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesST

Outputs

Amazon.EC2.Model.Image
This cmdlet returns one or more Amazon Machine Image objects that correspond to a set of one or more name patterns. If a single value is supplied for the -Name parameter, and it matches one of the built-in name patterns, only the latest machine image corresponding to the name is output. To see all available versions of the image matching the name, use the -AllAvailable switch. If more than one value is supplied to the -Name parameter, all images matching the set of name patterns are output (irrespective of whether the names are built-in or custom). The service calls(s) made by the cmdlet to obtain the Image collection (type Amazon.EC2.Model.DescribeImagesResponse) are added to the cmdlet entry in the $AWSHistory stack.
string
If no parameters are supplied the cmdlet emits the built-in logical names that can be used with the -Name parameter.

Examples

Example 1

Get-EC2ImageByName
    
WINDOWS_2012R2_BASE
WINDOWS_2012R2_SQL_SERVER_EXPRESS_2014
WINDOWS_2012R2_SQL_SERVER_STANDARD_2014
WINDOWS_2012R2_SQL_SERVER_WEB_2014
WINDOWS_2012_BASE
WINDOWS_2012_SQL_SERVER_EXPRESS_2014
WINDOWS_2012_SQL_SERVER_STANDARD_2014
WINDOWS_2012_SQL_SERVER_WEB_2014
WINDOWS_2012_SQL_SERVER_EXPRESS_2012
WINDOWS_2012_SQL_SERVER_STANDARD_2012
WINDOWS_2012_SQL_SERVER_WEB_2012
WINDOWS_2012_SQL_SERVER_EXPRESS_2008
WINDOWS_2012_SQL_SERVER_STANDARD_2008
WINDOWS_2012_SQL_SERVER_WEB_2008
WINDOWS_2008R2_BASE
WINDOWS_2008R2_SQL_SERVER_EXPRESS_2012
WINDOWS_2008R2_SQL_SERVER_STANDARD_2012
WINDOWS_2008R2_SQL_SERVER_WEB_2012
WINDOWS_2008R2_SQL_SERVER_EXPRESS_2008
WINDOWS_2008R2_SQL_SERVER_STANDARD_2008
WINDOWS_2008R2_SQL_SERVER_WEB_2008
WINDOWS_2008RTM_BASE
WINDOWS_2008RTM_SQL_SERVER_EXPRESS_2008
WINDOWS_2008RTM_SQL_SERVER_STANDARD_2008
WINDOWS_2008_BEANSTALK_IIS75
WINDOWS_2012_BEANSTALK_IIS8
VPC_NAT
This example describes the complete set of filter names that are currently supported.

Example 2

Get-EC2ImageByName -Names WINDOWS_2012R2_BASE
    
Architecture        : x86_64
BlockDeviceMappings : {/dev/sda1, xvdca, xvdcb, xvdcc...}
CreationDate        : yyyy.mm.ddThh:mm:ss.000Z
Description         : Microsoft Windows Server 2012 R2 RTM 64-bit Locale English AMI provided by Amazon
Hypervisor          : xen
ImageId             : ami-xxxxxxxx
ImageLocation       : amazon/Windows_Server-2012-R2_RTM-English-64Bit-Base-yyyy.mm.dd
ImageOwnerAlias     : amazon
ImageType           : machine
KernelId            :
Name                : Windows_Server-2012-R2_RTM-English-64Bit-Base-yyyy.mm.dd
OwnerId             : 801119661308
Platform            : Windows
ProductCodes        : {}
Public              : True
RamdiskId           :
RootDeviceName      : /dev/sda1
RootDeviceType      : ebs
SriovNetSupport     : simple
State               : available
StateReason         :
Tags                : {}
VirtualizationType  : hvm
This example describes the specified AMI. Using this command to locate an AMI is helpful because AWS releases new Windows AMIs with the latest updates each month. You can specify the 'ImageId' to New-EC2Instance to launch an instance using the current AMI for the specified filter.
User Guide
Service API Reference
Microsoft Windows Guide
VPC User Guide
AWS Tools for PowerShell User Guide

Supported Version

AWS Tools for PowerShell: 2.x.y.z