AWS Developer Tools Blog

Introducing AWS Tools for PowerShell Core Edition

Today Microsoft announced PowerShell support on Windows, Linux and OS X platforms (read the blog announcement here). We’re pleased to also announce support for PowerShell on these new platforms with a new module, the AWS Tools for PowerShell Core Edition or “AWSPowerShell.NetCore” to give it its module name. Just like PowerShell itself, this new module can be used on Windows, Linux, and OS X platforms.

The AWSPowerShell.NetCore module is built on top of the .NET Core version of the AWS SDK for .NET, which is in beta while we finish up testing and port a few more features from the .NET Framework version of the AWS SDK for .NET. Note that updates to the new module for new service features may lag a little behind the sister AWS Tools for Windows PowerShell (“AWSPowerShell”) module while the .NET Core version of the AWS SDK for .NET is in beta.

We hope to publish the new module to the PowerShell Gallery in a few days, after we finish final testing against the PowerShell libraries that Microsoft released today. We will update this blog post, together with a link to the new module on the gallery, once we have done so.

Update August 23rd 2016

The first beta release of the new module is now available on the PowerShell gallery. The version number is currently 3.2.7.0 to match the underlying AWS SDK for .NET product version. The services and service APIs supported in this release correspond to the 3.1.94.0 release of the AWSPowerShell module.

Some users are reporting issues with the Install-Module cmdlet built into PowerShell Core with errors related to semantic versioning (see GitHub Issue 202). Using the NuGet provider appears to resolve the issue currently. To install using this provider run this command, setting an appropriate destination folder (on Linux for example try -Destination ~/.local/share/powershell/Modules):

Install-Package -Name AWSPowerShell.NetCore -Source https://www.powershellgallery.com/api/v2/ -ProviderName NuGet -ExcludeVersion -Destination destfolder

What Happens to AWS Tools for Windows PowerShell?

Nothing! We will continue to update this module just as we have being doing as new service features and new services are launched. The version number of this module will remain at 3.1.* for the time being (AWSPowerShell.NetCore is v3.2.* to match the .NET SDK Core beta, which also has a version of 3.2.*).

Once the .NET Core version of the AWS SDK for .NET exits beta status, so will the AWSPowerShell.NetCore module. At that point, both the AWSPowerShell and AWSPowerShell.NetCore modules will version bump to 3.3.*. Again, this corresponds to the underlying SDK product version. From then on, both modules will update in lockstep with the underlying SDK just as we have being doing with the AWSPowerShell module, with updates being pushed to the gallery.

One small difference is that we currently plan to distribute the AWSPowerShell.NetCore module only through the gallery. The AWSPowerShell module will continue to be distributed to the gallery and through a downloadable Windows Installer that also contains the SDK and AWS Toolkit for Visual Studio. If you would like the new module to also be included in this installer, please let us know in the comments.

Module Compatibility

There is a high degree of compatibility between the two modules.

All cmdlets that map to service APIs are present and function in the same way between the two modules, with the exception that cmdlets for the deprecated Amazon Elastic Compute Cloud (Amazon EC2) import APIs, Import-EC2Instance and Import-EC2Volume, are not present in AWSPowerShell.NetCore. If you currently use these cmdlets in the AWSPowerShell module, we encourage you to investigate their replacements, Import-EC2Image and Import-EC2Snapshot, because the new Amazon EC2 import APIs are faster and more convenient (see blog post for more detail).

A small number of cmdlets are currently still being ported to the new module and have been removed from the first release to the gallery. We hope to add these back as soon as we can, but for now, the following are the cmdlets that are currently unavailable in the AWSPowerShell.NetCore module.

Proxy cmdlets:

  • Set-AWSProxy
  • Clear-AWSProxy

Logging cmdlets:

  • Add-AWSLoggingListener
  • Remove-AWSLoggingListener
  • Set-AWSResponseLogging
  • Enable-AWSMetricsLogging
  • Disable-AWSMetricsLogging

SAML federated credentials cmdlets:

  • Set-AWSSamlEndpoint
  • Set-AWSSamlRoleProfile

Note that credential profiles holding regular AWS Access and Secret keys can be used, and you can also obtain credentials from Instance Profiles when running the new module on Amazon EC2 instances, even on Linux instances.

Credential Handling

All cmdlets accept AWS Access and Secret keys or the names of credential profiles when they run, the same as you use them today with the current AWSPowerShell module. When running on Windows, both modules have access to the AWS SDK for .NET credential store file (stored per-user AppDataLocalAWSToolkitRegisteredAccounts.json file). This file stores your keys in encrypted format and cannot be used on a different machine. This file is the first to be inspected for the AWSPowerShell module when looking for a credential profile, and is also where it stores new credential profiles. (The AWSPowerShell module does not currently support writing credentials to other files or locations.)

Both modules can also read profiles from the ini-format shared credentials file that is used by other AWS SDKs and the AWS CLI. On Windows, the default location for this file is ”’C:Users”userid”.awscredentials”’. On non-Windows platforms, it is at ”’~/.aws/credentials”’. The -ProfilesLocation parameter can be used to point to a non-default file name or file location.

The SDK credential store holds your credentials in encrypted form by using Windows crypto APIs. These APIs are not available on other platforms, so the AWSPowerShell.NetCore module uses the ini-format shared credentials file exclusively and also supports writing new credential profiles to the shared credential file. This support will be extended to the AWSPowerShell module in a future release.

These example commands that use the Set-AWSCredentials cmdlet show the options for handling credential profiles on Windows with either the AWSPowerShell or AWSPowerShell.NetCore modules:

# Writes a new (or updates existing) profile with name "myProfileName"
# in the encrypted SDK store file
Set-AWSCredentials -AccessKey akey -SecretKey skey -StoreAs myProfileName

# Checks the encrypted SDK credential store for the profile and then
# falls back to the shared credentials file in the default location
Set-AWSCredentials -ProfileName myProfileName

# Bypasses the encrypted SDK credential store and attempts to load the
# profile from the ini-format credentials file "mycredentials" in the
# folder C:MyCustomPath
Set-AWSCredentials -ProfileName myProfileName -ProfilesLocation C:MyCustomPathmycredentials

These examples show the behavior of the AWSPowerShell.NetCore module on Linux or OS X:

# Writes a new (or updates existing) profile with name "myProfileName"
# in the default shared credentials file ~/.aws/credentials
Set-AWSCredentials -AccessKey akey -SecretKey skey -StoreAs myProfileName

# Writes a new (or updates existing) profile with name "myProfileName"
# into an ini-format credentials file "~/mycustompath/mycredentials"
Set-AWSCredentials -AccessKey akey -SecretKey skey -StoreAs myProfileName -ProfilesLocation ~/mycustompath/mycredentials

# Reads the default shared credential file looking for the profile "myProfileName"
Set-AWSCredentials -ProfileName myProfileName

# Reads the specified credential file looking for the profile "myProfileName"
Set-AWSCredentials -ProfileName myProfileName -ProfilesLocation ~/mycustompath/mycredentials

Watch this space!

We’ll continue to update this post as new information becomes available and we finalize the publishing of the new module to the PowerShell Gallery. We hope you’re as excited about the ability to use PowerShell on platforms other than Windows as we are!