AWS Tools for PowerShell

(1)

AWS Tools for PowerShell

User Guide

AWS Tools for PowerShell: User Guide

(2)

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What are the AWS Tools for PowerShell?

The AWS Tools for PowerShell are a set of PowerShell modules that are built on the functionality exposed by the AWS SDK for .NET. The AWS Tools for PowerShell enable you to script operations on your AWS resources from the PowerShell command line..

The cmdlets provide an idiomatic PowerShell experience for specifying parameters and handling results even though they are implemented using the various AWS service HTTP query APIs. For example, the cmdlets for the AWS Tools for PowerShell support PowerShell pipelining—that is, you can pipe PowerShell objects in and out of the cmdlets.

The AWS Tools for PowerShell are ﬂexible in how they enable you to handle credentials, including support for the AWS Identity and Access Management (IAM) infrastructure. You can use the tools with IAM user credentials, temporary security tokens, and IAM roles.

The AWS Tools for PowerShell support the same set of services and AWS Regions that are supported by the SDK. You can install the AWS Tools for PowerShell on computers running Windows, Linux, or macOS operating systems.

NoteAWS Tools for PowerShell version 4 is the latest major release, and is a backward-compatible update to AWS Tools for PowerShell version 3.3. It adds signiﬁcant improvements while maintaining existing cmdlet behavior. Your existing scripts should continue to work after upgrading to the new version, but we do recommend that you test them thoroughly before upgrading. For more information about the changes in version 4, see Migrating from AWS Tools for PowerShell Version 3.3 to Version 4 (p. 18).

The AWS Tools for PowerShell are available as the following three distinct packages:

• AWS.Tools (p. 1)

• AWSPowerShell.NetCore (p. 2)

• AWSPowerShell (p. 2)

Maintenance and support for SDK major versions

For information about maintenance and support for SDK major versions and their underlying dependencies, see the following in the AWS SDKs and Tools Reference Guide:

• AWS SDKs and tools maintenance policy

• AWS SDKs and tools version support matrix

AWS.Tools - A modularized version of the AWS

Tools for PowerShell

(7)

AWSPowerShell.NetCore

This version of AWS Tools for PowerShell is the recommended version for any computer running PowerShell in a production environment. Because it's modularized, you need to download and load only the modules for the services you want to use. This reduces download times, memory usage, and enables auto-importing of AWS.Tools cmdlets with the need to manually call Import-Module ﬁrst.

This is the latest version of AWS Tools for PowerShell and runs on all supported operating systems, including Windows, Linux, and macOS. This package provides one installation module, AWS.Tools.Installer, one common module, AWS.Tools.Common, and one module for each AWS service, for example, AWS.Tools.EC2, AWS.Tools.IAM, AWS.Tools.S3, and so on.

The AWS.Tools.Installer module provides cmdlets that enable you to install, update, and remove the modules for each of the AWS services. The cmdlets in this module automatically ensure that you have all the dependent modules required to support the modules you want to use.

The AWS.Tools.Common module provides cmdlets for conﬁguration and authentication that are not service speciﬁc. To use the cmdlets for an AWS service, you just run the command. PowerShell automatically imports the AWS.Tools.Common module and the module for the AWS service whose cmdlet you want to run. This module is automatically installed if you use the AWS.Tools.Installer module to install the service modules.

You can install this version of AWS Tools for PowerShell on computers that are running:

• PowerShell Core 6.0 or later on Windows, Linux, or macOS.

• Windows PowerShell 5.1 or later on Windows with the .NET Framework 4.7.2 or later.

Throughout this guide, when we need to specify this version only, we refer to it by its module name:

AWS.Tools.

AWSPowerShell.NetCore - A single-module version of the AWS Tools for PowerShell

This version consists of a single, large module that contains support for all AWS services. Before you can use this module, you must manually import it.

You can install this version of AWS Tools for PowerShell on computers that are running:

• PowerShell Core 6.0 or later on Windows, Linux, or macOS.

• Windows PowerShell 3.0 or later on Windows with the .NET Framework 4.7.2 or later.

AWSPowerShell.NetCore.

AWSPowerShell - A single-module version for

Windows PowerShell

(8)

How to use this guide

This version of AWS Tools for PowerShell is compatible with and installable on only Windows computers that are running Windows PowerShell versions 2.0 through 5.1. It is not compatible with PowerShell Core 6.0 or later, or any other operating system (Linux or macOS). This version consists of a single, large module that contains support for all AWS services.

AWSPowerShell.

How to use this guide

The guide is divided into the following major sections.

Installing the AWS Tools for PowerShell (p. 4)

This section explains how to install the AWS Tools for PowerShell. It includes how to sign up for AWS if you don't already have an account, and how to create an IAM user that you can use to run the cmdlets.

Getting Started with the AWS Tools for Windows PowerShell (p. 24)

This section describes the fundamentals of using the AWS Tools for PowerShell, such as specifying credentials and AWS Regions, ﬁnding cmdlets for a particular service, and using aliases for cmdlets.

Using the AWS Tools for PowerShell (p. 51)

This section includes information about using the AWS Tools for PowerShell to perform some of the most common AWS tasks.

(9)

Prerequisites

Installing the AWS Tools for PowerShell

To successfully install and use the AWS Tools for PowerShell cmdlets, see the steps in the following topics.

Topics

• Prerequisites for Setting up the AWS Tools for PowerShell (p. 4)

• Installing the AWS Tools for PowerShell on Windows (p. 5)

• Installing AWS Tools for PowerShell on Linux or macOS (p. 12)

• Migrating from AWS Tools for PowerShell Version 3.3 to Version 4 (p. 18)

• AWS Account and Access Keys (p. 22)

Prerequisites for Setting up the AWS Tools for PowerShell

To use the AWS Tools for PowerShell, you must ﬁrst complete the following steps.

1. Sign up for an AWS account.

If you don't have an AWS account, see the following topic for complete instructions on how to sign up:

https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/

2. Create an IAM user.

After you sign up for your account, you must create users in the AWS Identity and Access

Management (IAM) service. Each user has its own credentials and permissions. The credentials are used to authenticate the user making a request. The permissions determine which AWS resources and operations are authorized for that user.

Creating a user is outside the scope of this topic. But if you're new to AWS, we recommend that you read the following:

• To understand user credentials and best practices for managing them, see AWS Security Credentials in the Amazon Web Services General Reference.

• For a step-by-step tutorial on creating a user with "administrator" permissions that you can use to run AWS Tools for PowerShell commands, see Creating Your First IAM Admin User and Group in the IAM User Guide.

3. Create an access key for your IAM user.

The AWS Tools for PowerShell require that each cmdlet is sent using appropriate security

credentials. To do this, you typically must create an access key for each user that needs to use the AWS Tools for PowerShell cmdlets. An access key consists of an access key ID and secret access key.

These are used to sign (encrypt for the purpose of authentication) programmatic requests that you make to AWS services. If you don't have an access key, you can create it by using the IAM console at https://console.aws.amazon.com/iam/. As described in AWS Security Credentials, we recommend

(10)

Installing on Windows

that you use access keys for IAM users instead of AWS root account access keys. IAM lets you securely control access to AWS services and resources in your AWS account.

As with any AWS operation, creating access keys requires that you have permissions to perform the related IAM actions. For more information, see Permissions for Administering IAM Identities in the IAM User Guide.

After you create the access key for your ﬁrst user in the AWS console, you can use that user and its access key to run AWS Tools for PowerShell cmdlets to create access keys for your other users. The following example shows how to use the New-IAMAccessKey cmdlet to create an access key and secret key for an IAM user.

PS > New-IAMAccessKey -UserName alice AccessKeyId : AKIAIOSFODNN7EXAMPLE CreateDate : 9/4/19 12:46:18 PM

SecretAccessKey : wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Status : Active

UserName : alice

Save these credentials in a safe place. You need them to conﬁgure the AWS Tools for PowerShell credentials ﬁle later. For more information, see Using AWS Credentials (p. 24).

Important

The only time you can see the secret access key (the equivalent of a password) is when you create the access key. You cannot retrieve it later. If you lose the secret key, you must delete the access key/secret key pair and recreate them.

An IAM user can have only two access keys at any one time. If you attempt to create a third set, the New-IAMAccessKey cmdlet returns an error. To create another, you must ﬁrst delete one of the existing two.

You can use the Remove-IAMAccessKey cmdlet to delete a set of credentials for an IAM user. You must specify both the UserName and the AccessKeyId.

PS > Remove-IAMAccessKey -UserName alice -AccessKeyId -AccessKeyId AKIAIOSFODNN7EXAMPLE Confirm

Are you sure you want to perform this action?

Performing the operation "Remove-IAMAccessKey (DeleteAccessKey)" on target "AKIAIOSFODNN7EXAMPLE".

[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y

Installing the AWS Tools for PowerShell on Windows

A Windows-based computer can run any of the AWS Tools for PowerShell package options:

• AWS.Tools (p. 6) - The modularized version of AWS Tools for PowerShell. Each AWS service is

supported by its own individual, small module, with shared support modules AWS.Tools.Common and AWS.Tools.Installer.

• AWSPowerShell.NetCore (p. 7) - The single, large-module version of AWS Tools for PowerShell.

All AWS services are supported by this single, large module.

• AWSPowerShell (p. 8) - The legacy Windows-speciﬁc, single, large-module version of AWS Tools for PowerShell. All AWS services are supported by this single, large module.

(11)

Prerequisites

The package you choose depends on the release and edition of Windows that you're running.

NoteThe Tools for Windows PowerShell (AWSPowerShell module) are installed by default on all Windows-based Amazon Machine Images (AMIs).

Setting up the AWS Tools for PowerShell involves the following high-level tasks, described in detail in this topic.

1. Install the AWS Tools for PowerShell package option that's appropriate for your environment.

2. Verify that script execution is enabled by running the Get-ExecutionPolicy cmdlet.

3. Import the AWS Tools for PowerShell module into your PowerShell session.

Prerequisites

Ensure that you meet the requirements listed in Prerequisites for Setting up the AWS Tools for PowerShell (p. 4).

Newer versions of PowerShell, including PowerShell Core, are available as downloads from Microsoft at Installing various versions of PowerShell on Microsoft's Web site.

Install AWS.Tools on Windows

You can install the modularized version of AWS Tools for PowerShell on computers that are running Windows with Windows PowerShell 5.1, or PowerShell Core 6.0 or later. For information about how to install PowerShell Core, see Installing various versions of PowerShell on Microsoft's Web site.

You can install AWS.Tools in one of three ways:

• Using the cmdlets in the AWS.Tools module. The AWS.Tools.Installer module simpliﬁes the installation and update of other AWS.Tools modules. The AWS.Tools.Installer requires, automatically downloads and installs, an updated version of PowerShellGet. The AWS.Tools.Installer module and automatically keeps your module versions in sync. When you install or update to a newer version of one module, the cmdlets in the AWS.Tools.Installer automatically update all of your other AWS.Tools modules to the same version.

• Downloading the modules from AWS.Tools.zip and extracting them in one of the module folders.

You can discover your module folders by printing the value of the $Env:PSModulePath variable.

• Installing each service module from the PowerShell Gallery using the Install-Module cmdlet, as described in the following procedure.

To install AWS.Tools on Windows using the Install-Module cmdlet 1. Start a PowerShell session.

Note

We recommend that you don't run PowerShell as an administrator with elevated permissions except when required by the task at hand. This is because of the potential security risk and is inconsistent with the principle of least privilege.

2. To install the modularized AWS.Tools package, run the following command.

PS > Install-Module -Name AWS.Tools.Installer Untrusted repository

You are installing the modules from an untrusted repository. If you trust this repository, change its InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure

(12)

Install AWSPowerShell.NetCore

you want to install the modules from 'PSGallery'?

[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): y

If you are notiﬁed that the repository is "untrusted", it asks you if you want to install anyway. Enter y to allow PowerShell to install the module. To avoid the prompt and install the module without trusting the repository, you can run the command with the -Force parameter.

PS > Install-Module -Name AWS.Tools.Installer -Force

3. You can now install the module for each AWS service that you want to use by using the Install- AWSToolsModule cmdlet. For example, the following command installs the IAM module. This command also installs any dependent modules that are required for the speciﬁed module to work. For example, when you install your ﬁrst AWS.Tools service module, it also installs AWS.Tools.Common. This is a shared module required by all AWS service modules. It also removes older versions of the modules, and updates other modules to the same newer version.

PS > Install-AWSToolsModule AWS.Tools.EC2,AWS.Tools.S3 -CleanUp Confirm

Performing the operation "Install-AWSToolsModule" on target "AWS Tools version 4.0.0.0".

[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"):

Installing module AWS.Tools.Common version 4.0.0.0 Installing module AWS.Tools.EC2 version 4.0.0.0 Installing module AWS.Tools.Glacier version 4.0.0.0 Installing module AWS.Tools.S3 version 4.0.0.0 Uninstalling AWS.Tools version 3.3.618.0 Uninstalling module AWS.Tools.Glacier Uninstalling module AWS.Tools.S3

Uninstalling module AWS.Tools.SimpleNotificationService Uninstalling module AWS.Tools.SQS

Uninstalling module AWS.Tools.Common

NoteThe Install-AWSToolsModule cmdlet downloads all requested modules from the PSRepository named PSGallery (https://www.powershellgallery.com/) and considers it a trusted source. Use the command Get-PSRepository -Name PSGallery for more information about this PSRepository.

By default, this command installs modules into the $home\Documents\PowerShell\Modules folder. To install the AWS Tools for PowerShell for all users of a computer, you must run the following command in a PowerShell session that you started as an administrator. This installs modules to the $env:ProgramFiles\PowerShell\Modules folder that is accessible by all users.

PS > Install-AWSToolsModule AWS.Tools.IdentityManagement -Scope AllUsers

Install AWSPowerShell.NetCore on Windows

You can install the AWSPowerShell.NetCore on computers that are running Windows with PowerShell version 3 through 5.1, or PowerShell Core 6.0 or later. For information about how to install PowerShell Core, see Installing various versions of PowerShell on the Microsoft PowerShell website.

You can install AWSPowerShell.NetCore in one of two ways

(13)

Install AWSPowerShell

• Downloading the module from AWSPowerShell.NetCore.zip and extracting it in one of the module directories. You can discover your module directories by printing the value of the

$Env:PSModulePath variable.

• Installing from the PowerShell Gallery using the Install-Module cmdlet, as described in the following procedure.

To install AWSPowerShell.NetCore from the PowerShell Gallery using the Install-Module cmdlet To install the AWSPowerShell.NetCore from the PowerShell Gallery, your computer must be running PowerShell 5.0 or later, or running PowerShellGet on PowerShell 3 or later. Run the following command.

PS > Install-Module -name AWSPowerShell.NetCore

If you're running PowerShell as administrator, the previous command installs AWS Tools for PowerShell for all users on the computer. If you're running PowerShell as a standard user without administrator permissions, that same command installs AWS Tools for PowerShell for only the current user.

To install for only the current user when that user has administrator permissions, run the command with the -Scope CurrentUser parameter set, as follows.

PS > Install-Module -name AWSPowerShell.NetCore -Scope CurrentUser

Although PowerShell 3.0 and later releases typically load modules into your PowerShell session the ﬁrst time you run a cmdlet in the module, the AWSPowerShell.NetCore module is too large to support this functionality. You must instead explicitly load the AWSPowerShell.NetCore Core module into your PowerShell session by running the following command.

PS > Import-Module AWSPowerShell.NetCore

To load the AWSPowerShell.NetCore module into a PowerShell session automatically, add that command to your PowerShell profile. For more information about editing your PowerShell profile, see About Profiles in the PowerShell documentation.

Install AWSPowerShell on Windows PowerShell

You can install the AWS Tools for Windows PowerShell in one of three ways:

• Downloading the module from AWSPowerShell.zip and extracting it in one of the module directories.

You can discover your module directories by printing the value of the $Env:PSModulePath variable.

• Running the Tools for Windows PowerShell installer. This method of installing AWSPowerShell is deprecated and we recommend that you use Install-Module instead.

• Installing from the PowerShell Gallery using the Install-Module cmdlet as described in the following procedure.

To install AWSPowerShell from the PowerShell Gallery using the Install-Module cmdlet

You can install the AWSPowerShell from the PowerShell Gallery if you're running PowerShell 5.0 or later, or have installed PowerShellGet on PowerShell 3 or later. You can install and update AWSPowerShell from Microsoft's PowerShell Gallery by running the following command.

PS > Install-Module -Name AWSPowerShell

(14)

Enable Script Execution

To load the AWSPowerShell module into a PowerShell session automatically, add the previous import- module cmdlet to your PowerShell profile. For more information about editing your PowerShell profile, see About Profiles in the PowerShell documentation.

NoteThe Tools for Windows PowerShell are installed by default on all Windows-based Amazon Machine Images (AMIs).

Enable Script Execution

To load the AWS Tools for PowerShell modules, you must enable PowerShell script execution. To enable script execution, run the Set-ExecutionPolicy cmdlet to set a policy of RemoteSigned. For more information, see About Execution Policies on the Microsoft Technet website.

NoteThis is a requirement only for computers that are running Windows. The ExecutionPolicy security restriction is not present on other operating systems.

To enable script execution

1. Administrator rights are required to set the execution policy. If you are not logged in as a user with administrator rights, open a PowerShell session as Administrator. Choose Start, and then choose All Programs. Choose Accessories, and then choose Windows PowerShell. Right-click Windows PowerShell, and on the context menu, choose Run as administrator.

2. At the command prompt, enter the following.

PS > Set-ExecutionPolicy RemoteSigned

NoteOn a 64-bit system, you must do this separately for the 32-bit version of PowerShell, Windows PowerShell (x86).

If you don't have the execution policy set correctly, PowerShell shows the following error whenever you try to run a script, such as your proﬁle.

File C:\Users\username\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 cannot be loaded because the execution

of scripts is disabled on this system. Please see "get-help about_signing" for more details.

At line:1 char:2

+ . <<<< 'C:\Users\username\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1' + CategoryInfo : NotSpecified: (:) [], PSSecurityException

+ FullyQualifiedErrorId : RuntimeException

The Tools for Windows PowerShell installer automatically updates the PSModulePath to include the location of the directory that contains the AWSPowerShell module.

Because the PSModulePath includes the location of the AWS module's directory, the Get-Module - ListAvailable cmdlet shows the module.

PS > Get-Module -ListAvailable

ModuleType Name ExportedCommands --- ---- --- Manifest AppLocker {}

Manifest BitsTransfer {}

Manifest PSDiagnostics {}

Manifest TroubleshootingPack {}

(15)

Versioning

Manifest AWSPowerShell {Update-EBApplicationVersion, Set-DPStatus, Remove- IAMGroupPol...

Versioning

AWS releases new versions of the AWS Tools for PowerShell periodically to support new AWS services and features. To determine the version of the Tools that you have installed, run the Get- AWSPowerShellVersion cmdlet.

PS > Get-AWSPowerShellVersion Tools for PowerShell

Version 4.1.11.0

Amazon Web Services SDK for .NET Core Runtime Version 3.7.0.12

Release notes: https://github.com/aws/aws-tools-for-powershell/blob/master/CHANGELOG.md This software includes third party software subject to the following copyrights:

- Logging from log4net, Apache License

[http://logging.apache.org/log4net/license.html]

You can also add the -ListServiceVersionInfo parameter to a Get-AWSPowerShellVersion command to see a list of the AWS services that are supported in the current version of the tools. If you use the modularized AWS.Tools.* option, only the modules that you currently have imported are displayed.

PS > Get-AWSPowerShellVersion -ListServiceVersionInfo ...

Service Noun Prefix Module Name SDK Assembly Version --- --- ---

---

Alexa For Business ALXB AWS.Tools.AlexaForBusiness 3.7.0.11 Amplify Backend AMPB AWS.Tools.AmplifyBackend 3.7.0.11 Amazon API Gateway AG AWS.Tools.APIGateway 3.7.0.11 Amazon API Gateway Management API AGM AWS.Tools.ApiGatewayManagementApi 3.7.0.11 Amazon API Gateway V2 AG2 AWS.Tools.ApiGatewayV2 3.7.0.11 Amazon Appflow AF AWS.Tools.Appflow 3.7.1.4 Amazon Route 53 R53 AWS.Tools.Route53 3.7.0.12 Amazon Route 53 Domains R53D AWS.Tools.Route53Domains 3.7.0.11 Amazon Route 53 Resolver R53R AWS.Tools.Route53Resolver 3.7.1.5 Amazon Simple Storage Service (S3) S3 AWS.Tools.S3 3.7.0.13 ...

To determine the version of PowerShell that you are running, enter $PSVersionTable to view the contents of the $PSVersionTable automatic variable.

PS > $PSVersionTable

Name Value ---- --- PSVersion 6.2.2 PSEdition Core GitCommitId 6.2.2

(16)

Updating AWS Tools for PowerShell

OS Darwin 18.7.0 Darwin Kernel Version 18.7.0: Tue Aug 20 16:57:14 PDT 2019; root:xnu-4903.271.2~2/RELEASE_X86_64

Platform Unix

PSCompatibleVersions {1.0, 2.0, 3.0, 4.0…}

PSRemotingProtocolVersion 2.3 SerializationVersion 1.1.0.1 WSManStackVersion 3.0

Updating the AWS Tools for PowerShell on Windows

Periodically, as updated versions of the AWS Tools for PowerShell are released, you should update the version that you are running locally.

Update the Modularized AWS.Tools

To upgrade your AWS.Tools modules to the latest version, run the following command.

PS > Update-AWSToolsModule -CleanUp

This command updates all of the currently installed AWS.Tools modules and, after a successful update, removes other installed versions.

NoteThe Update-AWSToolsModule cmdlet downloads all modules from the PSRepository named PSGallery (https://www.powershellgallery.com/) and considers it a trusted source.

Use the command: Get-PSRepository -Name PSGallery for more information on this PSRepository.

Update the Tools for PowerShell Core

Run the Get-AWSPowerShellVersion cmdlet to determine the version that you are running, and compare that with the version of Tools for Windows PowerShell that is available on the PowerShell Gallery website. We suggest you check every two to three weeks. Support for new commands and AWS services is available only after you update to a version with that support.

Before you install a newer release of AWSPowerShell.NetCore, uninstall the existing module. Close any open PowerShell sessions before you uninstall the existing package. Run the following command to uninstall the package.

PS > Uninstall-Module -Name AWSPowerShell.NetCore -AllVersions

After the package is uninstalled, install the updated module by running the following command.

PS > Install-Module -Name AWSPowerShell.NetCore

After installation, run the command Import-Module AWSPowerShell.NetCore to load the updated cmdlets into your PowerShell session.

Update the Tools for Windows PowerShell

• If you installed by using the Install-Module cmdlet, run the following commands.

(17)

Installing on Linux or macOS

PS > Uninstall-Module -Name AWSPowerShell -AllVersions PS > Install-Module -Name AWSPowerShell

• If you installed by using the .msi package installer or by using a downloaded ZIP ﬁle:

1. Download the most recent version from the Tools for PowerShell web site. Compare the package version number in the downloaded ﬁle name with the version number you get when you run the Get-AWSPowerShellVersion cmdlet.

2. If the download version is a higher number than the version you have installed, close all Tools for Windows PowerShell consoles.

3. Install the newer version of the Tools for Windows PowerShell.

After installation, run Import-Module AWSPowerShell to load the updated cmdlets into your PowerShell session. Or run the custom AWS Tools for PowerShell console from your Start menu.

Installing AWS Tools for PowerShell on Linux or macOS

This topic provides instructions on how to install the AWS Tools for PowerShell on Linux or macOS.

Overview of Setup

To install AWS Tools for PowerShell on a Linux or macOS computer, you can choose from two package options:

• AWS.Tools (p. 13) – The modularized version of AWS Tools for PowerShell. Each AWS service is supported by its own individual, small module, with shared support modules AWS.Tools.Common.

• AWSPowerShell.NetCore (p. 14) – The single, large-module version of AWS Tools for PowerShell.

All AWS services are supported by this single, large module.

Setting either of these up on a computer running Linux or macOS involves the following tasks, described in detail later in this topic:

1. Install PowerShell Core 6.0 or later on a supported system.

2. After installing PowerShell Core, start PowerShell by running pwsh in your system shell.

3. Install either AWS.Tools or AWSPowerShell.NetCore.

4. Run the appropriate Import-Module cmdlet to import the module into your PowerShell session.

5. Run the Initialize-AWSDefaultConﬁguration cmdlet to provide your AWS credentials.

Prerequisites

Ensure that you meet the requirements listed on Prerequisites for Setting up the AWS Tools for PowerShell (p. 4).

To run the AWS Tools for PowerShell Core, your computer must be running PowerShell Core 6.0 or later.

• For a list of supported Linux platform releases and for information about how to install the latest version of PowerShell on a Linux-based computer, see Installing PowerShell on Linux on Microsoft's website. Some Linux-based operating systems, such as Arch, Kali, and Raspbian, are not oﬃcially supported, but have varying levels of community support.

(18)

Install AWS.Tools

• For information about supported macOS versions and about how to install the latest version of PowerShell on macOS, see Installing PowerShell on macOS on Microsoft's website.

Install AWS.Tools on Linux or macOS

You can install the modularized version of AWS Tools for PowerShell on computers that are running PowerShell Core 6.0 or later. For information about how to install PowerShell Core, see Installing various versions of PowerShell on the Microsoft PowerShell website.

You can install AWS.Tools in one of three ways:

• Using the cmdlets in the AWS.Tools.Installer module. The AWS.Tools.Installer module simpliﬁes the installation and update of other AWS.Tools modules. AWS.Tools.Installer requires, automatically downloads and installs, an updated version of PowerShellGet. The AWS.Tools.Installer module also automatically keeps your module versions in sync. When you install or update to a newer version of one module, the cmdlets in the AWS.Tools.Installer automatically update all of your other AWS.Tools modules to the same version.

• Downloading the modules from AWS.Tools.zip and extracting them in one of the module directories. You can discover your module directories by printing the value of the

• Installing each service module from the PowerShell Gallery using the Install-Module cmdlet, as described in the following procedure.

To install AWS.Tools on Linux or macOS using the Install-Module cmdlet 1. Start a PowerShell Core session by running the following command.

$ pwsh

NoteWe recommend that you don't run PowerShell as an administrator with elevated permissions except when required by the task at hand. This is because of the potential security risk and is inconsistent with the principle of least privilege.

2. To install the modularized AWS.Tools package using the AWS.Tools.Installer module, run the following command.

PS > Install-Module -Name AWS.Tools.Installer Untrusted repository

You are installing the modules from an untrusted repository. If you trust this repository, change its InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure

you want to install the modules from 'PSGallery'?

[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): y

If you are notiﬁed that the repository is "untrusted", you're asked if you want to install anyway. Enter y to allow PowerShell to install the module. To avoid the prompt and install the module without trusting the repository, you can run the following command.

PS > Install-Module -Name AWS.Tools.Installer -Force

3. You can now install the module for each service that you want to use. For example, the following command installs the IAM module. This command also installs any dependent modules that are required for the speciﬁed module to work. For example, when you install your ﬁrst AWS.Tools

(19)

Install AWSPowerShell.NetCore

service module, it also installs AWS.Tools.Common. This is a shared module required by all AWS service modules. It also removes older versions of the modules, and updates other modules to the same newer version.

PS > Install-AWSToolsModule AWS.Tools.EC2,AWS.Tools.S3 -CleanUp Confirm

Performing the operation "Install-AWSToolsModule" on target "AWS Tools version 4.0.0.0".

[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"):

Installing module AWS.Tools.Common version 4.0.0.0 Installing module AWS.Tools.EC2 version 4.0.0.0 Installing module AWS.Tools.Glacier version 4.0.0.0 Installing module AWS.Tools.S3 version 4.0.0.0 Uninstalling AWS.Tools version 3.3.618.0 Uninstalling module AWS.Tools.Glacier Uninstalling module AWS.Tools.S3

Uninstalling module AWS.Tools.SimpleNotificationService Uninstalling module AWS.Tools.SQS

Uninstalling module AWS.Tools.Common

NoteThe Install-AWSToolsModule cmdlet downloads all requested modules from the PSRepository named PSGallery (https://www.powershellgallery.com/) and considers the repository as a trusted source. Use the command Get-PSRepository -Name PSGallery for more information about this PSRepository.

By default, this installs modules into the $home\Documents\PowerShell\Modules folder.

To install the AWS.Tools module for all users of a computer, you must run the following

command in a PowerShell session that you started as an administrator. This installs modules to the

$env:ProgramFiles\PowerShell\Modules folder that is accessible by all users.

PS > Install-AWSToolsModule -Name AWS.Tools.IdentityManagement -Scope AllUsers

Install AWSPowerShell.NetCore on Linux or macOS

To upgrade to a newer release of AWSPowerShell.NetCore, follow the instructions in Updating the AWS Tools for PowerShell on Linux or macOS (p. 17). Uninstall earlier versions of AWSPowerShell.NetCore ﬁrst.

You can install AWSPowerShell.NetCore in one of two ways:

• Downloading the module from AWSPowerShell.NetCore.zip and extracting it in one of the module directories. You can discover your module directories by printing the value of the

• Installing from the PowerShell Gallery using the Install-Module cmdlet as described in the following procedure.

To install AWSPowerShell.NetCore on Linux or macOS using the Install-Module cmdlet Start a PowerShell Core session by running the following command.

$ pwsh

(20)

Script Execution

NoteWe recommend that you don't start PowerShell by running sudo pwsh to run PowerShell with elevated, administrator rights. This is because of the potential security risk and is inconsistent with the principle of least privilege.

To install the AWSPowerShell.NetCore single-module package from the PowerShell Gallery, run the following command.

PS > Install-Module -Name AWSPowerShell.NetCore Untrusted repository

You are installing the modules from an untrusted repository. If you trust this repository, change its InstallationPolicy value by running the Set-PSRepository cmdlet. Are you sure you want to install the modules from 'PSGallery'?

[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): y

If you are notiﬁed that the repository is "untrusted", you're asked if you want to install anyway. Enter y to allow PowerShell to install the module. To avoid the prompt without trusting the repository, you can run the following command.

PS > Install-Module -Name AWSPowerShell.NetCore -Force

You don't have to run this command as root, unless you want to install the AWS Tools for PowerShell for all users of a computer. To do this, run the following command in a PowerShell session that you have started with sudo pwsh.

PS > Install-Module -Scope AllUsers -Name AWSPowerShell.NetCore -Force

Script Execution

The Set-ExecutionPolicy command isn't available on non-Windows systems. You can run Get- ExecutionPolicy, which shows that the default execution policy setting in PowerShell Core running on non-Windows systems is Unrestricted. For more information, see About Execution Policies on the Microsoft Technet website.

Because the PSModulePath includes the location of the AWS module's directory, the Get-Module - ListAvailable cmdlet shows the module that you installed.

AWS.Tools

Directory: /Users/username/.local/share/powershell/Modules

ModuleType Version Name PSEdition ExportedCommands --- --- ---- --- --- Binary 3.3.563.1 AWS.Tools.Common Desk {Clear-AWSHistory, Set- AWSHistoryConfiguration, Initialize-AWSDefaultConfiguration, Clear-AWSDefaultConfigurat…

AWSPowerShell.NetCore

Directory: /Users/username/.local/share/powershell/Modules

ModuleType Version Name ExportedCommands --- --- ---- ---

(21)

Conﬁguring the PowerShell Console

Binary 3.3.563.1 AWSPowerShell.NetCore

Conﬁgure a PowerShell Console to Use the AWS Tools for PowerShell Core (AWSPowerShell.NetCore Only)

PowerShell Core typically loads modules automatically whenever you run a cmdlet in the module.

But this doesn't work for AWSPowerShell.NetCore because of its large size. To start running

AWSPowerShell.NetCore cmdlets, you must ﬁrst run the Import-Module AWSPowerShell.NetCore command. This isn't required for cmdlets in AWS.Tools modules.

Initialize Your PowerShell Session

When you start PowerShell on a Linux-based or macOS-based system after you have installed the AWS Tools for PowerShell, you must run Initialize-AWSDefaultConﬁguration to specify which AWS access key to use. For more information about Initialize-AWSDefaultConfiguration, see Using AWS Credentials (p. 24).

NoteIn earlier (before 3.3.96.0) releases of the AWS Tools for PowerShell, this cmdlet was named Initialize-AWSDefaults.

Versioning

AWS releases new versions of the AWS Tools for PowerShell periodically to support new AWS services and features. To determine the version of the AWS Tools for PowerShell that you have installed, run the Get-AWSPowerShellVersion cmdlet.

PS > Get-AWSPowerShellVersion Tools for PowerShell

Version 4.0.123.0

Amazon Web Services SDK for .NET Core Runtime Version 3.3.103.22

Release notes: https://github.com/aws/aws-tools-for-powershell/blob/master/CHANGELOG.md This software includes third party software subject to the following copyrights:

- Logging from log4net, Apache License

[http://logging.apache.org/log4net/license.html]

To see a list of the supported AWS services in the current version of the tools, add the - ListServiceVersionInfo parameter to a Get-AWSPowerShellVersion cmdlet.

To determine the version of PowerShell that you are running, enter $PSVersionTable to view the contents of the $PSVersionTable automatic variable.

PS > $PSVersionTable

Name Value ---- --- PSVersion 6.2.2 PSEdition Core

(22)

Updating the AWS Tools for PowerShell on Linux or macOS

GitCommitId 6.2.2

OS Darwin 18.7.0 Darwin Kernel Version 18.7.0: Tue Aug 20 16:57:14 PDT 2019; root:xnu-4903.271.2~2/RELEASE_X86_64

Platform Unix

PSCompatibleVersions {1.0, 2.0, 3.0, 4.0…}

PSRemotingProtocolVersion 2.3 SerializationVersion 1.1.0.1 WSManStackVersion 3.0

Updating the AWS Tools for PowerShell on Linux or macOS

Periodically, as updated versions of the AWS Tools for PowerShell are released, you should update the version that you're running locally.

Update the Modularized AWS.Tools.*

To upgrade your AWS.Tools modules to the latest version, run the following command.

PS > Update-AWSToolsModule -CleanUp

This command updates all of the currently installed AWS.Tools modules and, for those modules that were successfully updated, removes the earlier versions.

NoteThe Update-AWSToolsModule cmdlet downloads all modules from the PSRepository named PSGallery (https://www.powershellgallery.com/) and considers it a trusted source.

Use the command Get-PSRepository -Name PSGallery for more information about this PSRepository.

Update the Tools for PowerShell Core

Before you install a newer release of AWSPowerShell.NetCore, uninstall the existing module. Close any open PowerShell sessions before you uninstall the existing package. Run the following command to uninstall the package.

PS > Uninstall-Module -Name AWSPowerShell.NetCore -AllVersions

After the package is uninstalled, install the updated module by running the following command.

PS > Install-Module -Name AWSPowerShell.NetCore

After installation, run the command Import-Module AWSPowerShell.NetCore to load the updated cmdlets into your PowerShell session.

Related Information

• Getting Started with the AWS Tools for Windows PowerShell (p. 24)

• Using the AWS Tools for PowerShell (p. 51)

(23)

Migrating from AWS Tools for PowerShell Version 3.3 to Version 4

• AWS Account and Access Keys (p. 22)

Migrating from AWS Tools for PowerShell Version 3.3 to Version 4

AWS Tools for PowerShell version 4 is a backward-compatible update to AWS Tools for PowerShell version 3.3. It adds signiﬁcant improvements while maintaining existing cmdlet behavior.

Your existing scripts should continue to work after upgrading to the new version, but we do recommend that you test them thoroughly before upgrading your production environments.

This section describes the changes and explains how they might impact your scripts.

New Fully Modularized AWS.Tools Version

The AWSPowerShell.NetCore and AWSPowerShell packages were "monolithic". This meant that all of the AWS services were supported in the same module, making it very large, and growing larger as each new AWS service and feature was added. The new AWS.Tools package is broken up into smaller modules that give you the ﬂexibility to download and install only those that you require for the AWS services that you use. The package includes a shared AWS.Tools.Common module that is required by all of the other modules, and an AWS.Tools.Installer module that simpliﬁes installing, updating, and removing modules as needed.

This also enables auto-importing of cmdlets on ﬁrst call, without having to ﬁrst call Import-module.

However, to interact with the associated .NET objects before calling a cmdlet, you must still call Import- Module to let PowerShell know about the relevant .NET types.

For example, the following command has a reference to Amazon.EC2.Model.Filter. This type of reference can't trigger auto-importing, so you must call Import-Module ﬁrst or the command fails.

PS > $filter = [Amazon.EC2.Model.Filter]@{Name="vpc-id";Values="vpc-1234abcd"}

InvalidOperation: Unable to find type [Amazon.EC2.Model.Filter].

PS > Import-Module AWS.Tools.EC2

PS > $filter = [Amazon.EC2.Model.Filter]@{Name="vpc-id";Values="vpc-1234abcd"}

PS > Get-EC2Instance -Filter $filter -Select Reservations.Instances.InstanceId i-0123456789abcdefg

i-0123456789hijklmn

New Get-AWSService cmdlet

To help you discover the names of the modules for each AWS service in the AWS.Tools collection of modules, you can use the Get-AWSService cmdlet.

PS > Get-AWSService Service : ACMPCA CmdletNounPrefix : PCA ModuleName : AWS.Tools.ACMPCA SDKAssemblyVersion : 3.3.101.56

ServiceName : Certificate Manager Private Certificate Authority Service : AlexaForBusiness

CmdletNounPrefix : ALXB

ModuleName : AWS.Tools.AlexaForBusiness

(24)

New -Select Parameter to Control the Object Returned by a Cmdlet SDKAssemblyVersion : 3.3.106.26

ServiceName : Alexa For Business ...

New -Select Parameter to Control the Object Returned by a Cmdlet

Most cmdlets in version 4 support a new -Select parameter. Each cmdlet calls the AWS service APIs for you using the AWS SDK for .NET. Then the AWS Tools for PowerShell client converts the response into an object that you can use in your PowerShell scripts and pipe to other commands. Sometimes the final PowerShell object has more fields or properties in the original response than you need, and other times you might want the object to include fields or properties of the response that are not there by default. The -Select parameter enables you to specify what is included in the .NET object returned by the cmdlet.

For example, the Get-S3Object cmdlet invokes the Amazon S3 SDK operation ListObjects. That operation returns a ListObjectsResponse object. However, by default, the Get-S3Object cmdlet returns only the S3Objects element of the SDK response to the PowerShell user. In the following example, that object is an array with two elements.

PS > Get-S3Object -BucketName mybucket ETag : "01234567890123456789012345678901111"

BucketName : mybucket Key : file1.txt

LastModified : 9/30/2019 1:31:40 PM Owner : Amazon.S3.Model.Owner Size : 568

StorageClass : STANDARD

ETag : "01234567890123456789012345678902222"

BucketName : mybucket Key : file2.txt

LastModified : 7/15/2019 9:36:54 AM Owner : Amazon.S3.Model.Owner Size : 392

StorageClass : STANDARD

In AWS Tools for PowerShell version 4, you can specify -Select * to return the complete .NET response object returned by the SDK API call.

PS > Get-S3Object -BucketName mybucket -Select * IsTruncated : False

NextMarker :

S3Objects : {file1.txt, file2.txt}

Name : mybucket Prefix :

MaxKeys : 1000 CommonPrefixes : {}

Delimiter :

You can also specify the path to the speciﬁc nested property you want. The following example returns only the Key property of each element in the S3Objects array.

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key file1.txt

file2.txt

(25)

More Consistent Limiting of the Number of Items in the Output

In certain situations it can be useful to return a cmdlet parameter. You can do this with -Select

^ParameterName. This feature supplants the -PassThru parameter, which is still available but deprecated.

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key |

>> Write-S3ObjectTagSet -Select ^Key -BucketName mybucket -Tagging_TagSet @{ Key='key';

Value='value'}

file1.txt file2.txt

The reference topic for each cmdlet identiﬁes whether it supports the -Select parameter.

More Consistent Limiting of the Number of Items in the Output

Earlier versions of AWS Tools for PowerShell enabled you to use the -MaxItems parameter to specify the maximum number of objects returned in the ﬁnal output.

This behavior is removed from AWS.Tools.

This behavior is deprecated in AWSPowerShell.NetCore and AWSPowerShell, and will be removed from those versions in a future release.

If the underlying service API supports a MaxItems parameter, it's still available and functions as the API speciﬁes. But it no longer has the added behavior of limiting the number of items returned in the output of the cmdlet.

To limit the number of items returned in the ﬁnal output, pipe the output to the Select-Items cmdlet and specify the -First n parameter, where n is the maximum number of items to include in the ﬁnal output.

PS > Get-S3Object -BucketName mybucket -Select S3Objects.Key | select -first 1*

file1.txt

Not all AWS services supported -MaxItems in the same way, so this removes that inconsistency and the unexpected results that sometimes occurred. Also, -MaxItems combined with the new - Select (p. 19) parameter could sometimes result in confusing results.

Easier to Use Stream Parameters

Parameters of type Stream or byte[] can now accept string, string[], or FileInfo values.

For example, you can use any of the following examples.

PS > Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream '{

>> "some": "json"

>> }'

PS > Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream (ls .\some.json)

PS > Invoke-LMFunction -FunctionName MyTestFunction -PayloadStream @('{', '"some": "json"', '}')

AWS Tools for PowerShell converts all strings to byte[] using UTF-8 encoding.

(26)

Extending the Pipe by Property Name

To make the user experience more consistent, you can now pass pipeline input by specifying the property name for any parameter.

In the following example, we create a custom object with properties that have names that match the parameter names of the target cmdlet. When the cmdlet runs, it automatically consumes those properties as its parameters.

PS > [pscustomobject] @{ BucketName='myBucket'; Key='file1.txt'; PartNumber=1 } | Get- S3ObjectMetadata

NoteSome properties supported this in earlier versions of AWS Tools for PowerShell. Version 4 makes this more consistent by enabling it for all parameters.

Static Common Parameters

To improve consistency in version 4.0 of AWS Tools for PowerShell, all parameters are static.

In earlier versions of AWS Tools for PowerShell, some common parameters such as

AccessKey,SecretKey, ProfileName, or Region, were dynamic, while all other parameters were static. This could create problems because PowerShell binds static parameters before dynamic ones. For example, let's say you ran the following command.

PS > Get-EC2Region -Region us-west-2

Earlier versions of PowerShell bound the value us-west-2 to the -RegionName static parameter instead of the -Region dynamic parameter. Likely, this could confuse users.

AWS.Tools Declares and Enforces Manadatory Parameters

The AWS.Tools.* modules now declare and enforce mandatory cmdlet parameters. When an AWS Service declares that a parameter of an API is required, PowerShell prompts you for the corresponding cmdlet parameter if you didn't specify it. This applies only to AWS.Tools. To ensure backward compatibility, this does not apply to AWSPowerShell.NetCore or AWSPowerShell.

All Parameters Are Nullable

You can now assign $null to value type parameters (numbers and dates). This change should not aﬀect existing scripts. This enables you to bypass the prompt for a mandatory parameter. Mandatory parameters are enforced in AWS.Tools only.

If you run the following example using version 4, it eﬀectively bypasses client-side validation because you provide a "value" for each mandatory parameter. However, the Amazon EC2 API service call fails because the AWS service still requires that information.

PS > Get-EC2InstanceAttribute -InstanceId $null -Attribute $null

WARNING: You are passing $null as a value for parameter Attribute which is marked as required.

In case you believe this parameter was incorrectly marked as required, report this by opening

an issue at https://github.com/aws/aws-tools-for-powershell/issues.

(27)

Removing Previously Deprecated Features

WARNING: You are passing $null as a value for parameter InstanceId which is marked as required.

In case you believe this parameter was incorrectly marked as required, report this by opening

an issue at https://github.com/aws/aws-tools-for-powershell/issues.

Get-EC2InstanceAttribute : The request must contain the parameter instanceId

Removing Previously Deprecated Features

The following features were deprecated in previous releases of AWS Tools for PowerShell and are removed in version 4:

• Removed the -Terminate parameter from the Stop-EC2Instance cmdlet. Use Remove- EC2Instance instead.

• Removed the -ProfileName parameter from the Clear-AWSCredential cmdlet. Use Remove- AWSCredentialProfile instead.

• Removed cmdlets Import-EC2Instance and Import-EC2Volume.

AWS Account and Access Keys

To access AWS, you will need to sign up for an AWS account.

Access keys consist of an access key ID and secret access key, which are used to sign programmatic requests that you make to AWS. If you don't have access keys, you can create them by using the IAM console at https://console.aws.amazon.com/iam/. We recommend that you use IAM access keys instead of AWS root account access keys. IAM lets you securely control access to AWS services and resources in your AWS account.

Note

To create access keys, you must have permissions to perform the required IAM actions. For more information, see Granting IAM User Permission to Manage Password Policy and Credentials in the IAM User Guide.

To get your access key ID and secret access key

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. On the navigation menu, choose Users.

3. Choose your IAM user name (not the check box).

4. Open the Security credentials tab, and then choose Create access key.

5. To see the new access key, choose Show. Your credentials resemble the following:

• Access key ID: AKIAIOSFODNN7EXAMPLE

• Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

6. To download the key pair, choose Download .csv ﬁle. Store the .csv ﬁle with keys in a secure location.

Important

• Keep the keys conﬁdential to protect your AWS account, and never email them. Do not share them outside your organization, even if an inquiry appears to come from AWS or Amazon.com. No one who legitimately represents Amazon will ever ask you for your secret key.

• You can retrieve the secret access key only when you initially create the key pair. Like a password, you can't retrieve it later. If you lose it, you must create a new key pair.

(28)

To get your access key ID and secret access key

Related topics

• What Is IAM? in the IAM User Guide.

• AWS Security Credentials in the Amazon Web Services General Reference.

(29)

AWS Credentials

Getting Started with the AWS Tools for Windows PowerShell

This section describes fundamentals of using the Tools for Windows PowerShell. For example, it explains how to specify which credentials and AWS Region the Tools for Windows PowerShell should use when interacting with AWS. This section also provides guidance for using standard PowerShell cmdlets such as Get-Command to discover AWS cmdlets.

Topics

• Using AWS Credentials (p. 24)

• Shared Credentials in AWS Tools for PowerShell (p. 29)

• Specifying AWS Regions (p. 33)

• Cmdlet Discovery and Aliases (p. 34)

• Pipelining and $AWSHistory (p. 41)

• Conﬁguring Federated Identity with the AWS Tools for PowerShell (p. 43)

Using AWS Credentials

Each AWS Tools for PowerShell command must include a set of AWS credentials, which are used to cryptographically sign the corresponding web service request. You can specify credentials per command, per session, or for all sessions.

As a best practice, to avoid exposing your credentials, do not put literal credentials in a command.

Instead, create a profile for each set of credentials that you want to use, and store the profile in either of two credential stores. Specify the correct profile by name in your command, and the AWS Tools for PowerShell retrieves the associated credentials. For a general discussion of how to safely manage AWS credentials, see Best Practices for Managing AWS Access Keys in the Amazon Web Services General Reference.

Note

You need an AWS account to get credentials and use the AWS Tools for PowerShell. For information about how to sign up for an account, see AWS Account and Access Keys (p. 22).

Topics

• Credentials Store Locations (p. 24)

• Managing Proﬁles (p. 25)

• Specifying Credentials (p. 26)

• Credentials Search Order (p. 28)

• Credential Handling in AWS Tools for PowerShell Core (p. 28)

Credentials Store Locations

The AWS Tools for PowerShell can use either of two credentials stores:

• The AWS SDK store, which encrypts your credentials and stores them in your home folder.

In Windows, this store is located at: C:\Users\username\AppData\Local\AWSToolkit

\RegisteredAccounts.json.

The AWS SDK for .NET and Toolkit for Visual Studio can also use the AWS SDK store.

(30)

Managing Proﬁles

• The shared credentials ﬁle, which is also located in your home folder, but stores credentials as plain text.

By default, the credentials ﬁle is stored here:

• On Windows: C:\Users\username\.aws\credentials

• On Mac/Linux: ~/.aws/credentials

The AWS SDKs and the AWS Command Line Interface can also use the credentials ﬁle. If you're running a script outside of your AWS user context, be sure that the ﬁle that contains your credentials is copied to a location where all user accounts (local system and user) can access your credentials.

Managing Proﬁles

Profiles enable you to reference different sets of credentials with AWS Tools for PowerShell. You can use AWS Tools for PowerShell cmdlets to manage your profiles in the AWS SDK store. You can also manage profiles in the AWS SDK store by using the Toolkit for Visual Studio or programmatically by using the AWS SDK for .NET. For directions about how to manage profiles in the credentials file, see Best Practices for Managing AWS Access Keys.

Add a New proﬁle

To add a new profile to the AWS SDK store, run the command Set-AWSCredential. It stores your access key and secret key in your default credentials file under the profile name you specify.

PS > Set-AWSCredential `

-AccessKey AKIA0123456787EXAMPLE `

-SecretKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ` -StoreAs MyNewProfile

• -AccessKey– The access key ID.

• -SecretKey– The secret key.

• -StoreAs– The proﬁle name, which must be unique. To specify the default proﬁle, use the name default.

Update a Proﬁle

The AWS SDK store must be maintained manually. If you later change credentials on the service—for example, by using the IAM console—running a command with the locally stored credentials fails with the following error message:

The Access Key Id you provided does not exist in our records.

You can update a proﬁle by repeating the Set-AWSCredential command for the proﬁle, and passing it the new access and secret keys.

List Proﬁles

You can check the current list of names with the following command. In this example, a user named Shirley has access to three proﬁles that are all stored in the shared credentials ﬁle (~/.aws/

credentials).

PS > Get-AWSCredential -ListProfileDetail

(31)

Specifying Credentials

ProfileName StoreTypeName ProfileLocation --- --- ---

default SharedCredentialsFile /Users/shirley/.aws/credentials production SharedCredentialsFile /Users/shirley/.aws/credentials test SharedCredentialsFile /Users/shirley/.aws/credentials

Remove a Proﬁle

To remove a proﬁle that you no longer require, use the following command.

PS > Remove-AWSCredentialProfile -ProfileName an-old-profile-I-do-not-need

The -ProfileName parameter speciﬁes the proﬁle that you want to delete.

The deprecated command Clear-AWSCredential is still available for backward compatibility, but Remove- AWSCredentialProfile is preferred.

Specifying Credentials

There are several ways to specify credentials. The preferred way is to identify a proﬁle instead of incorporating literal credentials into your command line. AWS Tools for PowerShell locates the proﬁle using a search order that is described in Credentials Search Order (p. 28).

On Windows, AWS credentials stored in the AWS SDK store are encrypted with the logged-in Windows user identity. They cannot be decrypted by using another account, or used on a device that's different from the one on which they were originally created. To perform tasks that require the credentials of another user, such as a user account under which a scheduled task will run, set up a credential profile, as described in the preceding section, that you can use when you log in to the computer as that user. Log in as the task-performing user to complete the credential setup steps, and create a profile that works for that user. Then log out and log in again with your own credentials to set up the scheduled task.

Note

Use the -ProfileName common parameter to specify a proﬁle. This parameter is equivalent to the -StoredCredentials parameter in earlier AWS Tools for PowerShell releases. For backward compatibility, -StoredCredentials is still supported.

Default Proﬁle (Recommended)

All AWS SDKs and management tools can find your credentials automatically on your local computer if the credentials are stored in a profile named default. For example, if you have a profile named default on the local computer, you don't have to run either the Initialize- AWSDefaultConfiguration cmdlet or the Set-AWSCredential cmdlet. The tools automatically use the access and secret key data stored in that profile. To use an AWS Region other than your default Region (the results of Get-DefaultAWSRegion), you can run Set-DefaultAWSRegion and specify a Region.

If your profile is not named default, but you want to use it as the default profile for the current session, run Set-AWSCredential to set it as the default profile.

Although running Initialize-AWSDefaultConfiguration lets you specify a default profile for every PowerShell session, the cmdlet loads credentials from your custom-named profile, but overwrites the default profile with the named profile.

We recommend that you do not run Initialize-AWSDefaultConfiguration unless you are running a PowerShell session on an Amazon EC2 instance that was not launched with an instance profile, and you want to set up the credential profile manually. Note that the credential profile in this scenario would not contain credentials. The credential profile that results from running Initialize- AWSDefaultConfiguration on an EC2 instance doesn't directly store credentials, but instead

AWS Tools for PowerShell