PowerShell SDK provides the following features and benefits:

  • Increased interoperability with the latest APIs
  • OAuth2 security authentication
  • Faster batch processing
  • Pipeline support
  • Cross-platform operating system capability
  • Overall reduction and consolidation of cmdlets to streamline automation scripts 
  • Compatibility with older versions of the SDK

Let’s take a quick look at how easy it is to install, followed by some examples and additional resources.

Simple Installation

The new SDK supports multiple operating system platforms that are able to run PowerShell, including Windows, MacOS, and Linux. Please be sure to view the included Release Notes to ensure version compatibility with your operating system and PowerShell.

Like previous versions, the SDK comes as either an installable module from the PowerShell Gallery (PSGallery) for Windows, MacOS, and Linux operating systems, or as a downloadable standalone MSI installer for just the Windows OS. As a best practice, the PSGallery installation method is preferred to ensure you get the latest version revisions. It should also be noted that you can run both version 1.x and version 2.x SDKs side-by-side on your Windows computer, either in the same PowerShell 5.1 session or in separate PowerShell 7.x sessions. This ensures backward compatibility when you’re testing and upgrading scripts. Version 1.x of the SDK isn’t officially supported yet on Linux or MacOS with PowerShell version 7.x.

Installing from the PSGallery (Windows, MacOS, Linux)

Installing the module from the PSGallery is as easy as running the Install-Module cmdlet and Import-Module cmdlet shown here:

Installing from the MSI (Windows only)

Download the MSI installer and run the installation. By default, the module will be installed to the %ProgramFiles%\PureStorage\PowerShell\Modules folder.

Download the MSI installer and run the installation

When using the MSI to install the SDK, the path to the module is appended to your environment path for simplified loading.

When using the MSI to install the SDK, the path to the module is appended to your environment path

After Installation

Now, if you type in a Get-Command -Module PureStoragePowerShellSDK2 command, you’ll see that the cmdlet names have changed since the previous versions by adding the number “2” at the end of the “Pfa” string. This delineates the difference in versioning between SDK v1.x and v2.x. As previously mentioned, you can run both the SDK v1.x and v2.x modules together on the same machine, allowing for full version compatibility. Eventually, you should start altering your existing scripts to accommodate the version 2.x naming and parameter changes moving forward to guarantee future compatibility.

Array Authentication

One of the security changes from the previous SDK is the ability to authenticate to an array using either a user-specific API token or a more secure method of OAuth2 authentication token exchange. The FlashArray Purity API version 2.0 and later support OAuth2 authentication. Here’s how you’d implement them to match your security posture. 

Using OAuth2

The latest changes to the FlashArray Purity API have included the integrated security enhancement of using OAuth 2.0 as an optional authentication mechanism. I won’t go into the deep details of this technology in this post, but basically, it allows you to grant authentication tokens and exchange them for JSON Web Tokens, which are created by the API and can be used to securely authenticate to the array. 

Here’s a simplified example of the authentication process:Simplified example of the Purity authentication processTo authenticate using OAuth, you’ll need to create the proper variables based on predefined parameters you provide for the New-Pfa2ArrayAuth cmdlet, and then pass the tokens for authentication using the Connect-Pfa2Array cmdlet, as shown below. Be sure to define the variables before executing this command. Note that the -Password parameter will only accept a secure-string data type, so you’ll have to convert your plain text password to a secure-string before defining the variable. Also, the -APIClientName parameter must be unique to the array, and once it’s set, it can be deleted, but not changed.

The following command will create the required variables and certificate files based on the properties obtained from the above statement. The certificate files will be placed in the .ssh folder in your $HOME directory location depending on which operating system you’re using.

You should now be able to use the $clientID and $keyID variables in the following command to authenticate to the array. Please note that you must provide a -PrivateKeyPassword parameter either passed as a “secure-string” or you’ll be prompted for it on connection.

The $array variable is now set, and if you’re working with a single array, you don’t need to specify the -Array parameter with any other cmdlet that’s executed within the current PowerShell session. If you’re working with multiple arrays, you must use the variable to distinguish which array to execute a command against. You can test this by issuing a Get-Pfa2Array command with no parameters. You should see the details of the current array that you’re authenticated to.

Using API User Tokens

You may also authenticate to an array by using the API token for a specific API-enabled user. While this is less secure than using the OAuth2 method, it’s still a viable alternative if you’re connecting from a secure environment. FlashArray Purity API versions 1.x and 2.2 or later provide API token authentication.

Use the Connect-Pfa2Array cmdlet, prompt for the credentials of the API user, and store it as a variable as shown here:

Examples

Now that you’re authenticated, here are two examples of how you can use the SDK’s new functionality. 

A simple example to view all volumes on an array and output in table format:

A query for accounts that have an API token assigned:

You can find more examples in the README.md file that’s included in the distribution, on our Open-Connect GitHub repository, and in our Pure/Code() Slack Team.

Pipelining and Filtering

Pipelining in PowerShell commands makes complex statements much more efficient to write and execute by combining them into a single statement of code. However, be sure to exercise caution when using pipelines. For example, if you create a query for specific volume names and destroy them all in one pipeline without testing first, you could end up having a very bad day. If something like that happens, you can recover them easily within the retention period. 

In addition to pipelining, we’ve also introduced filtering in this version of the SDK. The -Filter parameter for a cmdlet narrows down the results of the request to return only the objects that satisfy the filter criteria. You can read more about the implementation of the Filter parameter in the about_Pfa2Filtering.help.txt file that’s part of the SDK distribution and also on our website.

Here are some examples of pipelining commands and filtering:

Filter for volumes named “vol1” and update them to a deleted status:

Query array for all deleted volumes and eradicate them (use with caution):

Filter hosts in a Hostgroup named “hgdev”:

Obtain a list of all volumes that were created on or before 2020-04-25T23:00:00Z:

Obtain a list of all volumes with volume names that do not include volumetest:

2.x and Beyond

Pure has an API-first culture of creation and we’re constantly coming up with new ideas around API integrations, especially with PowerShell. As the SDK evolves, look for more capabilities, functionality, integrations, and examples from Pure’s Microsoft Solutions team. 

Stay in the know by joining the Pure/Code() Slack Team and by checking out the Pure/Code() Developer Community site.