Getting started with the AWS SDK for PowerShell

The AWS SDK (for any language) is awesome and very powerful. Everything you can do in the AWS console you can do programatically which is why the AWS platform is so awesome to work with.

Getting started with using the AWS SDK can be a little daunting, so in this article we will be looking installing and configuring the AWS SDK for PowerShell so that you can get straight into automating your AWS environment.

1. Installation

The first step is to get the AWS SDK for PowerShell installed on your machine. To do this, follow these steps:

1. Download the AWS Tools for Windows. You can find them here >>> AWS Tools for Windows PowerShell.
2. Once downloaded, launch the installation and follow the prompts to install it on your machine.
3. Once the installation is complete, ensure you restart your machine.

2. AWS Access Keys

Next step is to generate a set of AWS access keys for your account. AWS access keys are a public & secret key combination that is used to connect and access your AWS environment from any of the AWS SDKs. These keys are generated and assigned on a per AWS user basis and provide the same level of access as if you were logging into the AWS console with that user. The best way to think of them is like a SDK username and password for the AWS account.

For this reason when generating a new set of AWS access keys, you will only ever see the secret key once. It is up to you to record and store this secret key in a secure location. If you ever lose your secret key, then you will need to delete the AWS access keys and generate a new set.

Here is how you generate a new set of AWS access keys:

1. Log into the AWS console using your AWS account
2. From the AWS console home page, click on Identity & Access Management (IAM)
3. From the left-hand menu, click on Users and then click on the user you want to generate AWS access keys for
4. From the security credentials tab of the user account, click on Create Access Key
5. This will generate a new set of public and secret access keys.

Note: The AWS access keys in the screenshot above are not in use, so you will not be able to access my account if you use them 🙂

3. Initialisation

We are now ready to initialise and configure the AWS SDK for PowerShell so that we can start using it. To do this we will be running the Initialize-AWSDefaults cmdlet. Based on the information provided by AWS, the cmdlet does the following things:

1. Checks for any default AWS credentials (with the name AWS PS Default) already existing on the machine. If so, these will be imported into your current PowerShell environment so that they can be automatically used when executing other AWS cmdlets.
2. If you are running this cmdlet from an EC2 instance (and there are no default AWS credentials present), can a set of credentials be obtained from the EC2 instance role? If so, these credentials are securely stored as the default set of credentials (i.e. AWS PS Default), and again will be imported into the current PowerShell shell so that they can be used with other AWS cmdlets.
3. If no credentials can be found, the cmdlet will then prompt you to create a default set of credentials which will be securely stored on your machine, and as you guessed they will be stored as…. AWS PS Default.

Most likely, when running through this article for the first time you will find yourself in scenario 3 and therefore you will be prompted for credentials.

AWS Region Codes

The Initialize-AWSDefaults cmdlet will also prompt you for your default AWS region code. This should be the region where most of your resources are located. The default region is used on every cmdlet you execute where you have not explicitly specified a region.

Each AWS region has a different code. For example, my default region is Sydney which is the region code of ap-southeast-2. For more information about AWS regions and a full list of region codes, see the article – AWS Regions and Endpoints.

Note: You will need to determine your region code prior to continuing with the steps below. To determine your region code, use the information in link above.

We are now ready to initialise the AWS SDK for PowerShell. To do this, follow these steps:

1. From the Start Menu, find and launch Windows PowerShell for AWS
2. This will launch a new PowerShell session, which will import the AWS PowerShell module and then run the Initialize-AWSDefaults cmdlet
3. When prompted, enter your AWS Access Key (i.e. public key)
4. When prompted, enter your AWS Secret Key
5. Next you will be prompted for a default region
6. Once complete, close the PowerShell window

4. AWS PowerShell Environment

Ok now you are ready to go and start writing scripts and managing your AWS environment via PowerShell. Before you can do this, you will need to ensure the AWSPowerShell module has been imported and that you have loaded your credentials.

To do this, run the following cmdlets at the beginning of each of your scripts or PowerShell sessions:

Import-Module AWSPowerShell
Set-AWSCredentials -ProfileName default

Running the cmdlets above gives you the ability to execute any AWS PowerShell cmdlet without the need for specifying any credentials (as the default credentials have been loaded within your PowerShell session).

Automated AWS PowerShell Environment

It gets a little repetitive constantly having to import the AWSPowerShell module and load your credentials every time you launch a new PowerShell session. This can be automated by adding the lines of code above in your PowerShell profile.

A PowerShell profile is simply a start-up script for your PowerShell environment. Whenever you launch PowerShell, whatever is in your profile will automatically execute.

Your PowerShell profile is found within %USERPROFILE%\Documents\WindowsPowerShell. There is heaps of information about PowerShell profiles on the web. For more information, just do a Google Search.

5. Additional Credentials (optional)

What if you are managing various AWS accounts or are using different IAM users for different scenarios and therefore have the requirement of storing and using more than one set of AWS credentials within your SDK store?

To do this we use the the Set-AWSCredentials cmdlet to create a new set of credentials. We also use the same cmdlet when wanting to retrieve and use these credentials within a specific PowerShell session.

Creating a new set of credentials

Here is how you would go about creating an additional set of credentials. In this example we will be creating a set of credentials and storing them with the name of client–2.

Set-AWSCredentials -AccessKey NEWACCESSKEYHERE -SecretKey NEWSECRETKEYHERE -StoreAs client-2

Accessing a specific set of credentials

Now that you have created and stored multiple AWS credentials, here is how you retrieve them. You would run the following cmdlet whenever you required access to this set of credentials:

Set-AWSCredentials -ProfileName client-2

List of available credentials

If you store many different sets of credentials, they can quickly get out of hand and you might forget the profile names you used for each different set. The following cmdlet will return a complete list of credential profiles available for the user:

Get-AWSCredentials -ListProfiles

Specific credentials for a single cmdlet

What if you needed to use a specific set of AWS credentials within your script to run a single cmdlet and these credentials are different to the credentials used to execute the remainder of the script?

AWS has already thought of this and has therefore added the -ProfileName parameter to every single AWS PowerShell cmdlet. This parameter allows you to specify a credential profile that will be used to execute that cmdlet only.

For example, let’s say we wanted to get all EC2 instances using the client–2 set of credentials we created above. To do this we would run the following:

Get-EC2Instance -ProfileName client-2

AWS PowerShell Cmdlet Reference

You are now ready to start developing and automating your AWS environment. Your next question will most likely be, “how do I know what cmdlets are available to me and how to use them?”

AWS has spent significant effort in documenting all of their SDKs and specifically for PowerShell has documented every single cmdlet available. You can find the complete AWS SDK for PowerShell reference guide here – AWS Tools for Windows PowerShell Cmdlet Reference.

You are now well on your way to developing for AWS using PowerShell. Any questions or suggestions, please let me know in the comments below.