AWS Tools for PowerShell V4 has entered maintenance mode.
We recommend that you migrate to [AWS Tools for PowerShell V5](https://docs.aws.amazon.com/powershell/v5/userguide/). For additional details and information on how to migrate, please refer to our [maintenance mode announcement](https://aws.amazon.com/blogs/developer/aws-tools-for-powershell-v4-maintenance-mode-announcement/).
# Amazon EC2 and Tools for Windows PowerShell
You can perform common tasks related to Amazon EC2 using the AWS Tools for PowerShell.
The example commands shown here assume that you have set default credentials and a default region for your PowerShell session. Therefore, we don't include credentials or region when we invoke the cmdlets. For more information, see [Get started with the AWS Tools for Windows PowerShell](pstools-getting-started.md).
**Topics**
+ [Create a Key Pair](pstools-ec2-keypairs.md)
+ [Create a Security Group](pstools-ec2-sg.md)
+ [Find an AMI](pstools-ec2-get-amis.md)
+ [Launch an Instance](pstools-ec2-launch.md)
# Creating a Key Pair
The following `New-EC2KeyPair` example creates a key pair and stores in the PowerShell variable `$myPSKeyPair`
```
PS > $myPSKeyPair = New-EC2KeyPair -KeyName myPSKeyPair
```
Pipe the key pair object into the `Get-Member` cmdlet to see the object's structure.
```
PS > $myPSKeyPair | Get-Member
TypeName: Amazon.EC2.Model.KeyPair
Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.Object obj)
GetHashCode Method int GetHashCode()
GetType Method type GetType()
ToString Method string ToString()
KeyFingerprint Property System.String KeyFingerprint {get;set;}
KeyMaterial Property System.String KeyMaterial {get;set;}
KeyName Property System.String KeyName {get;set;}
```
Pipe the key pair object into the `Format-List` cmdlet to view values of the `KeyName`, `KeyFingerprint`, and `KeyMaterial` members. (The output has been truncated for readability.)
```
PS > $myPSKeyPair | Format-List KeyName, KeyFingerprint, KeyMaterial
KeyName : myPSKeyPair
KeyFingerprint : 09:06:70:8e:26:b6:e7:ef:8f:fe:4a:1d:bc:9c:6a:63:11:ac:ad:3c
KeyMaterial : ----BEGIN RSA PRIVATE KEY----
MIIEogIBAAKCAQEAkK+ANYUS9c7niNjYfaCn6KYj/D0I6djnFoQE...
Mz6btoxPcE7EMeH1wySUp8nouAS9xbl9l7+VkD74bN9KmNcPa/Mu...
Zyn4vVe0Q5il/MpkrRogHqOB0rigeTeV5Yc3lvO0RFFPu0Kz4kcm...
w3Jg8dKsWn0plOpX7V3sRC02KgJIbejQUvBFGi5OQK9bm4tXBIeC...
daxKIAQMtDUdmBDrhR1/YMv8itFe5DiLLbq7Ga+FDcS85NstBa3h...
iuskGkcvgWkcFQkLmRHRoDpPb+OdFsZtjHZDpMVFmA9tT8EdbkEF...
3SrNeqZPsxJJIxOodb3CxLJpg75JU5kyWnb0+sDNVHoJiZCULCr0...
GGlLfEgB95KjGIk7zEv2Q7K6s+DHclrDeMZWa7KFNRZuCuX7jssC...
xO98abxMr3o3TNU6p1ZYRJEQ0oJr0W+kc+/8SWb8NIwfLtwhmJEy...
1BX9X8WFX/A8VLHrT1elrKmLkNECgYEAwltkV1pOJAFhz9p7ZFEv...
vvVsPaF0Ev9bk9pqhx269PB5Ox2KokwCagDMMaYvasWobuLmNu/1...
lmwRx7KTeQ7W1J3OLgxHA1QNMkip9c4Tb3q9vVc3t/fPf8vwfJ8C...
63g6N6rk2FkHZX1E62BgbewUd3eZOS05Ip4VUdvtGcuc8/qa+e5C...
KXgyt9nl64pMv+VaXfXkZhdLAdY0Khc9TGB9++VMSG5TrD15YJId...
gYALEI7m1jJKpHWAEs0hiemw5VmKyIZpzGstSJsFStERlAjiETDH...
YAtnI4J8dRyP9I7BOVOn3wNfIjk85gi1/0Oc+j8S65giLAfndWGR...
9R9wIkm5BMUcSRRcDy0yuwKBgEbkOnGGSD0ah4HkvrUkepIbUDTD...
AnEBM1cXI5UT7BfKInpUihZi59QhgdK/hkOSmWhlZGWikJ5VizBf...
drkBr/vTKVRMTi3lVFB7KkIV1xJxC5E/BZ+YdZEpWoCZAoGAC/Cd...
TTld5N6opgOXAcQJwzqoGa9ZMwc5Q9f4bfRc67emkw0ZAAwSsvWR...
x3O2duuy7/smTwWwskEWRK5IrUxoMv/VVYaqdzcOajwieNrblr7c...
-----END RSA PRIVATE KEY-----
```
The `KeyMaterial` member stores the private key for the key pair. The public key is stored in AWS. You can't retrieve the public key from AWS, but you can verify the public key by comparing the `KeyFingerprint` for the private key to that returned from AWS for the public key.
## Viewing the Fingerprint of Your Key Pair
You can use the `Get-EC2KeyPair` cmdlet to view the fingerprint for your key pair.
```
PS > Get-EC2KeyPair -KeyName myPSKeyPair | format-list KeyName, KeyFingerprint
KeyName : myPSKeyPair
KeyFingerprint : 09:06:70:8e:26:b6:e7:ef:8f:fe:4a:1d:bc:9c:6a:63:11:ac:ad:3c
```
## Storing Your Private Key
To store the private key to a file, pipe the `KeyFingerMaterial` member to the `Out-File` cmdlet.
```
PS > $myPSKeyPair.KeyMaterial | Out-File -Encoding ascii myPSKeyPair.pem
```
You must specify `-Encoding ascii` when writing the private key to a file. Otherwise, tools such as `openssl` might not be able to read the file correctly. You can verify that the format of the resulting file is correct by using a command such as the following:
```
PS > openssl rsa -check < myPSKeyPair.pem
```
(The `openssl` tool is not included with the AWS Tools for PowerShell or the AWS SDK for .NET.)
## Removing Your Key Pair
You need your key pair to launch and connect to an instance. When you are done using a key pair, you can remove it. To remove the public key from AWS, use the `Remove-EC2KeyPair` cmdlet. When prompted, press `Enter` to remove the key pair.
```
PS > Remove-EC2KeyPair -KeyName myPSKeyPair
Confirm
Performing the operation "Remove-EC2KeyPair (DeleteKeyPair)" on target "myPSKeyPair".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"):
```
The variable, `$myPSKeyPair`, still exists in the current PowerShell session and still contains the key pair information. The `myPSKeyPair.pem` file also exists. However, the private key is no longer valid because the public key for the key pair is no longer stored in AWS.
# Create a Security Group Using Windows PowerShell
You can use the AWS Tools for PowerShell to create and configure a security group. The response is the ID of the security group.
If you need to connect to your instance, you must configure the security group to allow SSH traffic (Linux) or RDP traffic (Windows).
**Topics**
+ [Prerequisites](#sg-prerequisites)
+ [Creating a Security Group for EC2-VPC](#new-ec2securitygroup-vpc)
## Prerequisites
You need the public IP address of your computer, in CIDR notation. You can get the public IP address of your local computer using a service. For example, Amazon provides the following service: [http://checkip.amazonaws.com/](http://checkip.amazonaws.com/) or [https://checkip.amazonaws.com/](https://checkip.amazonaws.com/). To locate another service that provides your IP address, use the search phrase "what is my IP address". If you are connecting through an ISP or from behind your firewall without a static IP address, you need to find the range of IP addresses that can be used by your client computers.
**Warning**
If you specify `0.0.0.0/0`, you are enabling traffic from any IP addresses in the world. For the SSH and RDP protocols, you might consider this acceptable for a short time in a test environment, but it's unsafe for production environments. In production, be sure to authorize access only from the appropriate individual IP address or range of addresses.
## Creating a Security Group for EC2-VPC
**Warning**
EC2-Classic was retired on August 15, 2022. We recommend that you migrate from EC2-Classic to a VPC. For more information, see the blog post [EC2-Classic Networking is Retiring – Here's How to Prepare](https://aws.amazon.com/blogs/aws/ec2-classic-is-retiring-heres-how-to-prepare/).
The following `New-EC2SecurityGroup` example adds the `-VpcId` parameter to create a security group for the specified VPC.
```
PS > $groupid = New-EC2SecurityGroup `
-VpcId "vpc-da0013b3" `
-GroupName "myPSSecurityGroup" `
-GroupDescription "EC2-VPC from PowerShell"
```
To view the initial configuration of the security group, use the `Get-EC2SecurityGroup` cmdlet. By default, the security group for a VPC contains a rule that allows all outbound traffic. Notice that you can't reference a security group for EC2-VPC by name.
```
PS > Get-EC2SecurityGroup -GroupId sg-5d293231
OwnerId : 123456789012
GroupName : myPSSecurityGroup
GroupId : sg-5d293231
Description : EC2-VPC from PowerShell
IpPermissions : {}
IpPermissionsEgress : {Amazon.EC2.Model.IpPermission}
VpcId : vpc-da0013b3
Tags : {}
```
To define the permissions for inbound traffic on TCP port 22 (SSH) and TCP port 3389, use the `New-Object` cmdlet. The following example script defines permissions for TCP ports 22 and 3389 from a single IP address, `203.0.113.25/32`.
```
$ip1 = new-object Amazon.EC2.Model.IpPermission
$ip1.IpProtocol = "tcp"
$ip1.FromPort = 22
$ip1.ToPort = 22
$ip1.IpRanges.Add("203.0.113.25/32")
$ip2 = new-object Amazon.EC2.Model.IpPermission
$ip2.IpProtocol = "tcp"
$ip2.FromPort = 3389
$ip2.ToPort = 3389
$ip2.IpRanges.Add("203.0.113.25/32")
Grant-EC2SecurityGroupIngress -GroupId $groupid -IpPermissions @( $ip1, $ip2 )
```
To verify the security group has been updated, use the `Get-EC2SecurityGroup` cmdlet again.
```
PS > Get-EC2SecurityGroup -GroupIds sg-5d293231
OwnerId : 123456789012
GroupName : myPSSecurityGroup
GroupId : sg-5d293231
Description : EC2-VPC from PowerShell
IpPermissions : {Amazon.EC2.Model.IpPermission}
IpPermissionsEgress : {Amazon.EC2.Model.IpPermission}
VpcId : vpc-da0013b3
Tags : {}
```
To view the inbound rules, you can retrieve the `IpPermissions` property from the collection object returned by the previous command.
```
PS > (Get-EC2SecurityGroup -GroupIds sg-5d293231).IpPermissions
IpProtocol : tcp
FromPort : 22
ToPort : 22
UserIdGroupPairs : {}
IpRanges : {203.0.113.25/32}
IpProtocol : tcp
FromPort : 3389
ToPort : 3389
UserIdGroupPairs : {}
IpRanges : {203.0.113.25/32}
```
# Find an Amazon Machine Image Using Windows PowerShell
When you launch an Amazon EC2 instance, you specify an Amazon Machine Image (AMI) to serve as a template for the instance. However, the IDs for the AWS Windows AMIs change frequently because AWS provides new AMIs with the latest updates and security enhancements. You can use the [Get-EC2Image](https://docs.aws.amazon.com/powershell/v4/reference/items/Get-EC2Image.html) and [Get-EC2ImageByName](https://docs.aws.amazon.com/powershell/v4/reference/items/Get-EC2ImageByName.html) cmdlets to find the current Windows AMIs and get their IDs.
**Topics**
+ [Get-EC2Image](#pstools-ec2-get-image)
+ [Get-EC2ImageByName](#pstools-ec2-get-ec2imagebyname)
## Get-EC2Image
The `Get-EC2Image` cmdlet retrieves a list of AMIs that you can use.
Use the `-Owner` parameter with the array value `amazon, self` so that `Get-EC2Image` retrieves only AMIs that belong to Amazon or to you. In this context, *you* refers to the user whose credentials you used to invoke the cmdlet.
```
PS > Get-EC2Image -Owner amazon, self
```
You can scope the results using the `-Filter` parameter. To specify the filter, create an object of type `Amazon.EC2.Model.Filter`. For example, use the following filter to display only Windows AMIs.
```
$platform_values = New-Object 'collections.generic.list[string]'
$platform_values.add("windows")
$filter_platform = New-Object Amazon.EC2.Model.Filter -Property @{Name = "platform"; Values = $platform_values}
Get-EC2Image -Owner amazon, self -Filter $filter_platform
```
The following is an example of one of the AMIs returned by the cmdlet; the actual output of the previous command provides information for many AMIs.
```
Architecture : x86_64
BlockDeviceMappings : {/dev/sda1, xvdca, xvdcb, xvdcc…}
CreationDate : 2019-06-12T10:41:31.000Z
Description : Microsoft Windows Server 2019 Full Locale English with SQL Web 2017 AMI provided by Amazon
EnaSupport : True
Hypervisor : xen
ImageId : ami-000226b77608d973b
ImageLocation : amazon/Windows_Server-2019-English-Full-SQL_2017_Web-2019.06.12
ImageOwnerAlias : amazon
ImageType : machine
KernelId :
Name : Windows_Server-2019-English-Full-SQL_2017_Web-2019.06.12
OwnerId : 801119661308
Platform : Windows
ProductCodes : {}
Public : True
RamdiskId :
RootDeviceName : /dev/sda1
RootDeviceType : ebs
SriovNetSupport : simple
State : available
StateReason :
Tags : {}
VirtualizationType : hvm
```
## Get-EC2ImageByName
The `Get-EC2ImageByName` cmdlet enables you to filter the list of AWS Windows AMIs based on the type of server configuration you are interested in.
When run with no parameters, as follows, the cmdlet emits the complete set of current filter names:
```
PS > Get-EC2ImageByName
WINDOWS_2016_BASE
WINDOWS_2016_NANO
WINDOWS_2016_CORE
WINDOWS_2016_CONTAINER
WINDOWS_2016_SQL_SERVER_ENTERPRISE_2016
WINDOWS_2016_SQL_SERVER_STANDARD_2016
WINDOWS_2016_SQL_SERVER_WEB_2016
WINDOWS_2016_SQL_SERVER_EXPRESS_2016
WINDOWS_2012R2_BASE
WINDOWS_2012R2_CORE
WINDOWS_2012R2_SQL_SERVER_EXPRESS_2016
WINDOWS_2012R2_SQL_SERVER_STANDARD_2016
WINDOWS_2012R2_SQL_SERVER_WEB_2016
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
```
To narrow the set of images returned, specify one or more filter names using the `Names` parameter.
```
PS > Get-EC2ImageByName -Names WINDOWS_2016_CORE
Architecture : x86_64
BlockDeviceMappings : {/dev/sda1, xvdca, xvdcb, xvdcc…}
CreationDate : 2019-08-16T09:36:09.000Z
Description : Microsoft Windows Server 2016 Core Locale English AMI provided by Amazon
EnaSupport : True
Hypervisor : xen
ImageId : ami-06f2a2afca06f15fc
ImageLocation : amazon/Windows_Server-2016-English-Core-Base-2019.08.16
ImageOwnerAlias : amazon
ImageType : machine
KernelId :
Name : Windows_Server-2016-English-Core-Base-2019.08.16
OwnerId : 801119661308
Platform : Windows
ProductCodes : {}
Public : True
RamdiskId :
RootDeviceName : /dev/sda1
RootDeviceType : ebs
SriovNetSupport : simple
State : available
StateReason :
Tags : {}
VirtualizationType : hvm
```
# Launch an Amazon EC2 Instance Using Windows PowerShell
To launch an Amazon EC2 instance, you need the key pair and security group that you created in the previous sections. You also need the ID of an Amazon Machine Image (AMI). For more information, see the following documentation:
+ [Creating a Key Pair](pstools-ec2-keypairs.md)
+ [Create a Security Group Using Windows PowerShell](pstools-ec2-sg.md)
+ [Find an Amazon Machine Image Using Windows PowerShell](pstools-ec2-get-amis.md)
**Important**
If you launch an instance that is not within the Free Tier, you are billed after you launch the instance and charged for the time that the instance is running even if it remains idle.
**Topics**
+ [Launching an Instance in a VPC](#new-ec2instance-vpc)
+ [Launching a Spot Instance in a VPC](#new-ec2instance-spot)
## Launching an Instance in a VPC
**Warning**
EC2-Classic was retired on August 15, 2022. We recommend that you migrate from EC2-Classic to a VPC. For more information, see the blog post [EC2-Classic Networking is Retiring – Here's How to Prepare](https://aws.amazon.com/blogs/aws/ec2-classic-is-retiring-heres-how-to-prepare/).
The following command creates a single `m1.small` instance in the specified private subnet. The security group must be valid for the specified subnet.
```
PS > New-EC2Instance `
-ImageId ami-c49c0dac `
-MinCount 1 -MaxCount 1 `
-KeyName myPSKeyPair `
-SecurityGroupId sg-5d293231 `
-InstanceType m1.small `
-SubnetId subnet-d60013bf
ReservationId : r-b70a0ef1
OwnerId : 123456789012
RequesterId :
Groups : {}
GroupName : {}
Instances : {}
```
Your instance is in the `pending` state initially, but is in the `running` state after a few minutes. To view information about your instance, use the `Get-EC2Instance` cmdlet. If you have more than one instance, you can filter the results on the reservation ID using the `Filter` parameter. First, create an object of type `Amazon.EC2.Model.Filter`. Next, call `Get-EC2Instance` that uses the filter, and then displays the `Instances` property.
```
PS > $reservation = New-Object 'collections.generic.list[string]'
PS > $reservation.add("r-b70a0ef1")
PS > $filter_reservation = New-Object Amazon.EC2.Model.Filter -Property @{Name = "reservation-id"; Values = $reservation}
PS > (Get-EC2Instance -Filter $filter_reservation).Instances
AmiLaunchIndex : 0
Architecture : x86_64
BlockDeviceMappings : {/dev/sda1}
ClientToken :
EbsOptimized : False
Hypervisor : xen
IamInstanceProfile :
ImageId : ami-c49c0dac
InstanceId : i-5203422c
InstanceLifecycle :
InstanceType : m1.small
KernelId :
KeyName : myPSKeyPair
LaunchTime : 12/2/2018 3:38:52 PM
Monitoring : Amazon.EC2.Model.Monitoring
NetworkInterfaces : {}
Placement : Amazon.EC2.Model.Placement
Platform : Windows
PrivateDnsName :
PrivateIpAddress : 10.25.1.11
ProductCodes : {}
PublicDnsName :
PublicIpAddress : 198.51.100.245
RamdiskId :
RootDeviceName : /dev/sda1
RootDeviceType : ebs
SecurityGroups : {myPSSecurityGroup}
SourceDestCheck : True
SpotInstanceRequestId :
SriovNetSupport :
State : Amazon.EC2.Model.InstanceState
StateReason :
StateTransitionReason :
SubnetId : subnet-d60013bf
Tags : {}
VirtualizationType : hvm
VpcId : vpc-a01106c2
```
## Launching a Spot Instance in a VPC
The following example script requests a Spot Instance in the specified subnet. The security group must be one you created for the VPC that contains the specified subnet.
```
$interface1 = New-Object Amazon.EC2.Model.InstanceNetworkInterfaceSpecification
$interface1.DeviceIndex = 0
$interface1.SubnetId = "subnet-b61f49f0"
$interface1.PrivateIpAddress = "10.0.1.5"
$interface1.Groups.Add("sg-5d293231")
Request-EC2SpotInstance `
-SpotPrice 0.007 `
-InstanceCount 1 `
-Type one-time `
-LaunchSpecification_ImageId ami-7527031c `
-LaunchSpecification_InstanceType m1.small `
-Region us-west-2 `
-LaunchSpecification_NetworkInterfaces $interface1
```