How-To: Connect to a FlashArray with the PowerShell SDK v2
This article is for the PowerShell SDK version 2.
Connecting to an Array
To connect to a Pure Storage FlashArray, the Connect-Pfa2Array
cmdlet is used to create a secure connection from a host to the specified FlashArray. A connection to the FlashArray is done over HTTPS using TLS 1.1/1.2.
The PowerShell SDK provides detailed help for each of the cmdlets. Use the Get-Help
<cmdlet name> to retrieve the details. Refer to this article for more information on accessing and using help.
Authentication Methods
When establishing a session using the PowerShell SDK version 2.x, there are a few options to authenticate to an array and utilize Tokens or a username and password combination, which are necessary for SDK version 2 cmdlets to interact with the array.
Depending on the API versions that are present on your array determines the methods to which you can connect to them via REST.
This article shows the which versions of the API is included with each FlashArray Purity version. To determine exactly what API versions are supported on your array, use your browser and connect to https://<FQDN or IP Address of array>/api/api_version.
An OAuth2 authentication is the only allowed method of connecting to an array with the Purity API versions 2.0 to 2.1.
API version 2.2 allows for the additional authentication method of connecting using a username and password combination or API Tokens.
API Tokens
Connect with Credentials
Purity API 2.2 or later
$FlashArray = Connect-Pfa2Array -EndPoint 10.0.0.1 -Credential (Get-Credential) -IgnoreCertificateError
The below example uses the -
Credential
parameter to create a session to the Pure Storage FlashArray at 10.0.0.1 (-EndPoint
). The -EndPoint
can either be an IP address or a Fully Qualified Domain Name (FQDN). Once connected, the session is stored as a PowerShell Object (PSObject) with the variable name of $FlashArray
. The -
Credential
parameter is set to use the Windows PowerShell cmdlet Get-Credential
which will prompt for a User name and Password.
Once the credentials have been entered and OK clicked, the Connect-Pfa2Array
cmdlet will complete the session.
Note that in the above example the -
IgnoreCertificateError
is used as part of the Connect-Pfa2Array
cmdlet. This parameter prevents certificate errors such as an unknown certificate issuer or non-matching names from causing the request to fail.
When using the Credentials method it is also possible to create a variable and assign the credentials to that variable.
$Creds = Get-Credential
Connect with a username and password
Purity API 2.2 or later
$FlashArray = Connect-Pfa2Array -EndPoint 10.0.0.1 -UserName pureuser -Password (ConvertTo-SecureString -String 'mypassword' -AsPlainText -Force) -IgnoreCertificateError
When using the -UserName
and -Password
parameter method of creating a session, please take notice that the -Password
parameter requires that it be a secure string.
Connect via OAuth2
Purity API 2.0 or later
For more information on OAuth2, please visit this site.
To create a PowerShell session to an array using OAuth2, follow the 2 steps bellow:
-
An API Client registration on the array, and an RSA key pair (certificates).
If you already have an API Client you can proceed to step 2.
To create a PowerShell Session using OAuth2, you will need an API Client on the FlashArray. You can create an API Client either using the Purity//FA CLI commands (See
pureapiclient
command in the CLI or this article for details), or using a Pure Storage PowerShell SDK 2 REST session.There are two ways to create an API Client using Pure Storage PowerShell SDK 2: Using the cmdlets
New-Pfa2ApiClient
orNew-Pfa2ArrayAuth
.This article shows the which versions of the API is included with each FlashArray Purity version.To determine exactly what API versions are supported on your array, use your browser and connect to https://<FQDN or IP Address of array>/api/api_version.
a. If you want to use your existing RSA key pair, use
New-Pfa2ApiClient
. Note that you need to be already authenticated with the array, either with an existing API Client or using the API Token (not available with API versions 2.0 or 2.1). If you are not authenticated yet to an array that supports API version 2.2 or later, do so using theConnect-Pfa2Array
command as shown previously. Once authenticated, use the command shown below.PS C:\>$ApiClient = New-Pfa2ApiClient -Array $Array -MaxRole $MaxRole -Issuer $ArrayIssuer -PublicKey $Certificate -Name $ClientName
Where,
$Array
is the PureArray object returned by theConnect-Pfa2Array
command.$MaxRole
is the maximum role allowed for ID Tokens issued by this API client. Valid values arearray_admin
,storage_admin
,ops_admin
, andreadonly
.$ArrayIssuer
is the name of the identity provider that will be issuing ID Tokens for this API client. This can be any arbitrary unique name or specific for audit purposes. Often times this parameter is set the same as the$ClientName
.$Certificate
is the API Client's PEM formatted (Base64 encoded) RSA public key.$ClientName
is the unique name to be used for this API Client.
API Clients created using
New-Pfa2ApiClient
are disabled by default. To enable the API Client use the commandUpdate-Pfa2ApiClient
:PS C:\>Update-Pfa2ApiClient -Array $Array -Name $ClientName -Enabled $true
b. If you do not want to use your own key pair, the
New-Pfa2ArrayAuth
command bellow will generate a key pair for you and store it under%USERPROFILE%\.ssh\
, or Mac/Linux under~/.ssh/*
. The command will also create the API Client on the FlashArray. Please note that if the API Client already exists, the command will return the existing client.PS C:\>$ApiClientAuthInfo = New-Pfa2ArrayAuth -Endpoint $ArrayEndpoint -ApiClientName $Clientname -Issuer $ArrayIssuer -Username $ArrayUsername -Password $ArrayPassword -Force
Where,
$ArrayEndpoint
is the FlashArray IP or Name.$ClientName
is the unique name for this API Client.$ArrayIssuer
is the name of the identity provider that will be issuing ID Tokens for this API client. This can be any arbitrary unique name or specific for audit purposes. Often times this parameter is set the same as the$ClientName
.$ArrayUsername
is the FlashArray username.$ArrayPassword
is the FlashArray Password (SecureString Object).
-
Create OAuth2 session using the API client KeyID and ClientID: To create an OAuth2 session this way, you will need the following information from the API Client:
$clientID
,$keyId
, and$privateKeyFile
. This information can be retrieved from the response of theNew-Pfa2ArrayAuth
command performed previously.PS C:\>$clientId = $ApiClientAuthInfo.PureClientApiClientInfo.clientId PS C:\>$keyId = $ApiClientAuthInfo.PureClientApiClientInfo.KeyId PS C:\>$privateKeyFile = $ApiClientAuthInfo.pureCertInfo.privateKeyFile
Optionally, if you used the
New-Pfa2ApiClient
command,$clientID
and$keyId
can also be retrieved from the response of theNew-Pfa2ApiClient
command used previously, and$privateKeyFile
should be your private key file location:PS C:\>$clientId = $ApiClient.Id PS C:\>$keyId = $ApiClient.KeyId PS C:\>$privateKeyFile = "<path to private key file>"
A third option is to use the command
pureapiclient list
, on the Purity//FA CLI, to list all existing API Clients. -
Finally, use the following command to create the OAuth2 session:
PS C:\>$oauth = Connect-Pfa2Array -Endpoint $ArrayEndpoint -Username $ArrayUsername -Issuer $ArrayIssuer -ApiClientName $Clientname -ClientId $clientId -KeyId $keyId -PrivateKeyFile $privateKeyFile -PrivateKeyPassword $privateKeyPassword -IgnoreCertificateError
Where,
$ArrayEndpoint
is the FlashArray IP or Name.$ArrayUsername
is the FlashArray username.$ArrayIssuer
is the name of the identity provider that will be issuing ID Tokens for this API client. This can be any arbitrary unique name or specific for audit purposes. Often times this parameter is set the same as the$ClientName
.$ClientName
is the unique name for this API Client.$privateKeyPassword
is required if the private key was generated using a passphrase. If you created the API Client using theNew-Pfa2ArrayAuth
command there is no passphrase. This password should be a SecureString object.
Note: The
Connect-Pfa2Array
cmdlet caches authentication information for the duration of the PowerShell session. With this, subsequent SDK cmdlets do not need to explicitly provide-Array
parameter. The cmdlets will retrieve the FlashArray authentication information from PowerShell session variable.
This is an example function that combines all of the commands and variables necessary for OAuth authentication using a generated Private Key for the user. You could use this function in multiple scripts to eliminate repetitive entries. Optionally, it prints to the screen the $clientID, $keyId, and $privateKeyFile variables for use.
# Define the variables PS C:\>$ArrayEndpoint = "10.1.1.1" # is the FlashArray IP or Name PS C:\>$ArrayClientname = "demo" # is the unique name for this API Client PS C:\>$ArrayIssuer = $ArrayClientname # is the name of the identity provider that will be issuing ID Tokens for this API client PS C:\>$ArrayPassword = ConvertTo-SecureString "pureuser" -AsPlainText -Force # is the FlashArray Password (SecureString) PS C:\>$ArrayUsername = "pureuser" # is the FlashArray username PS C:\>$MaxRole = "array_admin" # The role the user has on the array PS C:\>$privateKeyPass = ConvertTo-SecureString "Pr1v@teK3y!#" -AsPlainText -Force #is required if the private key was generated using a passphrase. If you created the API Client using the `New-Pfa2ArrayAuth` command there is no passphrase. This password should be a SecureString. # Remove the comments on the 'Write-Host' lines if you want to variables output to screen. function ArrayAuth () { $fa = New-Pfa2ArrayAuth -MaxRole array_admin -Endpoint $ArrayEndpoint -APIClientName $ArrayClientname -Issuer $ArrayIssuer -Username $ArrayUsername -Password $ArrayPassword $clientId = $fa.PureClientApiClientInfo.clientId #Write-Host "ClientID: $($clientId)" #Write-Host " " $keyId = $fa.PureClientApiClientInfo.KeyId #Write-Host "KeyID $($KeyId)" #Write-Host " " $privateKeyFile = $fa.pureCertInfo.privateKeyFile #Write-Host "PrivateKey $($privateKeyFile)" } ArrayAuth PS C:\>$array = Connect-Pfa2Array -Endpoint $ArrayEndpoint -Username $ArrayUsername -Issuer $ArrayIssuer -ClientId $clientId -KeyId $keyId -PrivateKeyFile $privateKeyFile -PrivateKeyPassword $privateKeyPass -IgnoreCertificateError -ApiClientName $ArrayClientname
Disconnecting from an Array
The Disconnect-Pfa2Array
cmdlet provides the ability to disconnect from an active array session created with the Connect-Pfa2Array
cmdlet. If you have more than one session connected, you must specify the -Array
parameter.
PS C:\>Disconnect-Pfa2Array -Array $FlashArray
Retrieving FlashArray Information
Once an active session to the FlashArray is established, the array object can be passed to other cmdlets. With previous SDK versions, in order to use the current session, the $FlashArray
variable would be used in all subsequent cmdlets for the -Array
parameter. This is no longer necessary in SDK version 2.x and is only required when multiple array connections are used within the same session. In the below example, the FlashArray controller details are retrieved.
The Get-Pfa2Controller
cmdlet requires Purity API version 2.2. if your array only supports Purity version 2.1 or earlier, the cmdlet will error.
Please see this matrix guide for more information on SDK v2 cmdlets and their implemented API versions.
PS C:\> Get-Pfa2Controller Name : CT0 Mode : primary Model : FA-x70 Status : ready Type : array_controller Version : 6.0.0 Name : CT1 Mode : secondary Model : FA-x70 Status : ready Type : array_controller Version : 6.0.0
Any time information is retrieved from the FlashArray (GET operations) and assigned to variable, it will return a PowerShell Object (PSObject). With the information stored as a PSObject, individual properties can be queried, used as part of the pipeline, or simply formatted.
PS C:\> $Controllers = Get-Pfa2Controller PS C:\> $Controllers.Item(0) Name : CT0 Mode : primary Model : FA-x70 Status : ready Type : array_controller Version : 6.0.0 PS C:\> $Controllers.Item(1) Name : CT1 Mode : secondary Model : FA-x70 Status : ready Type : array_controller Version : 6.0.0 PS C:\> $Controllers.Item(1).Name CT1 PS C:\> $Controllers.Item(1).Model FA-x70 PS C:\>
You could pipe the variable to the PowerShell cmdlet Get-Member
to retrieve all the available properties and methods returned from the PSObject. In this example, you would issue a $Controllers | Get-Member
to view the available objects.
The Invoke-Pfa2CliCommand
The Invoke-Pfa2CliCommand
cmdlet provides the ability to pass CLI commands to the FlashArray or FlashBlade for situations when the REST API has updated in a new version of Purity, but any new REST endpoints are not supported in the PowerShell SDK yet. Here is an example:
Invoke-Pfa2CLICommand -EndPoint 10.21.201.57 -Credential $Creds -CommandText "purevol list"
When using this cmdlet, be sure that your firewall rules allow for SSH Port 22 traffic. Otherwise, the cmdlet will fail with an error, such as the one below.
New-Pfa2CLICommand : A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond
You may see in the error message the CommandText is a “?”. If that is used, it will show the results as what you would see using the CLI and executing purehelp
.