Skip to main content
Pure Technical Services

How-To: Connect to a FlashArray with the PowerShell SDK v2

Currently viewing public documentation. Please login to access the full scope of documentation.

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 -Credentialparameter 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 -Credentialparameter is set to use the Windows PowerShell cmdlet Get-Credential which will prompt for a User name and Password.

posh-creds.png

Once the credentials have been entered and OK clicked, the Connect-Pfa2Array cmdlet will complete the session. 

Note that in the above example the -IgnoreCertificateErroris 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:

  1. 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 or New-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 the Connect-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 the Connect-Pfa2Array command.
    • $MaxRole is the maximum role allowed for ID Tokens issued by this API client. Valid values are array_adminstorage_adminops_admin, and readonly.
    • $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 command Update-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).
  2. 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 the New-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 the New-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.  

  3. 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 the New-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.