Version 5 (V5) of the AWS Tools for PowerShell has been released\$1 For information about breaking changes and migrating your applications, see the [migration topic](https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html). [https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html](https://docs.aws.amazon.com/powershell/v5/userguide/migrating-v5.html) # 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 [Authenticating with AWS](creds-idc.md) and [AWS Region](pstools-installing-specifying-region.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/v5/reference/items/Get-EC2Image.html) cmdlet to find the current Windows AMIs and get their IDs. ## 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 ``` **Note** Version 4 of the AWS Tools for PowerShell provided the `Get-EC2ImageByName` cmdlet to filter the list of AMIs by name patterns. For version 5 of the tools, use the [Get-SSMLatestEC2Image](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-SSMLatestEC2Image.html) cmdlet instead. # 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 ```