Skip to main content
Pure Technical Services

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

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

KP_Ext_Announcement.png

This article is for the PowerShell SDK version 1.

In this section we will cover:

 

New-PfaArray Cmdlet

To connect to a Pure Storage FlashArray the New-PfaArray cmdlet is used to create a secure connection from a host (Eg. Windows Server 2019 or Windows 10) 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.

For example, try the command below in a Windows PowerShell session.

PS C:\> Get-Help New-PfaArray -Examples

NAME
    New-PfaArray

SYNOPSIS
    Logs onto the specified FlashArray.

    -------------------------- EXAMPLE 1 --------------------------

    PS C:\>$Array = New-PfaArray -EndPoint pure01.example.com -UserName pureuser -HttpTimeOutInMilliSeconds 300000 -Version 1.3

    Using Version 1.3 of the REST API, connects to the FlashArray named "pure01.example.com" with pureuser's login
    credentials. The cmdlet prompts for the login password and masks the password string on the screen.

    The request times out if it takes longer than 300,000 milliseconds.

    "$Array" can be used with the "-Array" parameter in subsequent cmdlets (for example, "Disconnect-PfaArray -Array
    $Array").
    -------------------------- EXAMPLE 2 --------------------------

    PS C:\>$myCredential = Get-Credential
    $myArray = New-PfaArray -EndPoint pure01.example.com -Credentials $myCredential -IgnoreCertificateError

    Connects to the FlashArray named "pure01.example.com", ignoring any certificate errors.

    First, the PowerShell command Get-Credential opens a pop-up to enter the login credentials, which are saved to
    $myCredential.
    -------------------------- EXAMPLE 3 --------------------------

    PS C:\>$SecurePassword = ConvertTo-SecureString -String $ArrayPassword -AsPlaintext -Force
    $Array = New-PfaArray -EndPoint pure01.example.com -username pureuser -Password $SecurePassword -IgnoreCertificateError

    Connects to the FlashArray named "pure01.example.com", ignoring any certificate errors.

    First, the PowerShell command ConvertTo-SecureString is used to convert a plain password to a secure string, which is
    saved to $SecurePassword.
    -------------------------- EXAMPLE 4 --------------------------

    PS C:\>$Array = New-PfaArray -EndPoint pure01.example.com -UserName pureuser -RoleRequired ArrayAdmin

    Connects to the FlashArray named "pure01.example.com" with pureuser's login credentials. The cmdlet prompts for the
    login password and masks the password string on the screen.

    The request times out if it takes longer than 300,000 milliseconds.
    The request fails if the specified user does not have at least ArrayAdmin permission.
    -------------------------- EXAMPLE 5 --------------------------

    PS C:\>$Array = New-PfaArray -EndPoint pure01.example.com -ApiToken 99ce4e5a-3593-f724-4c44-e1a8c19c0c49 -IgnoreCertificateError

    Connects to the FlashArray named "pure01.example.com", ignoring any certificate errors and using an API token for authentication

Authentication

As illustrated by the above examples, when establishing a session using the PowerShell SDK, there are three options to authenticate:

  1. Username and Password
$FlashArray = New-PfaArray -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 notice in the above example that the Password parameter requires that it be a secure string. 

  1. API Token
$FlashArray = New-PfaArray -EndPoint 10.0.0.1 -ApiToken fbbb3xyz-b2da-0000-3d7d-c5604a900000
  1. Credentials
$FlashArray = New-PfaArray -EndPoint 10.0.0.1 -Credentials (Get-Credential)

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

credentials.png

Once the credentials have been entered and OK clicked the New-PfaArray cmdlet will complete the session. 

PS C:\> $FlashArray = New-PfaArray -EndPoint 10.0.0.1 -Credentials (Get-Credential) -IgnoreCertificateError
cmdlet Get-Credential at command pipeline position 1
Supply values for the following parameters:
Credential
PS C:\> 

Note that in the above example the IgnoreCertificateError is used as part of the New-PfaArray 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

 

Session Inspection

Once the session has been established the $FlashArray variable can be inspected to view the different properties. 

PS C:\> $FlashArray
Disposed   : False
EndPoint   : 10.0.0.1
UserName   : barkz
ApiVersion : 1.7
Role       : StorageAdmin
ApiToken   : fbbb3xyz-b2da-0000-3d7d-c5604a900000

Retrieving FlashArray Information

Now there is an active session to the FlashArray and this can be used to query the array for information. In order to use the current session the $FlashArray variable will be used in all subsequent cmdlets for the Array parameter. In the below example the FlashArray controller details are retrieved.

PS C:\> Get-PfaControllers -Array $FlashArray
status  : ready
model   : FA-m20
version : 4.8.1
name    : CT0
mode    : secondary

status  : ready
model   : FA-m20
version : 4.8.1
name    : CT1
mode    : primary

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-PfaControllers -Array $FlashArray
PS C:\> $Controllers.Item(0)
status  : ready
model   : FA-m20
version : 4.8.1
name    : CT0
mode    : secondary

PS C:\> $Controllers.Item(1)
status  : ready
model   : FA-m20
version : 4.8.1
name    : CT1
mode    : primary

PS C:\> $Controllers.Item(1).Name
CT1
PS C:\> $Controllers.Item(1).Model
FA-m20
PS C:\>

New-PfaCliCommand

In the Pure Storage PowerShell SDK 1.6.6.0, we introduced a cmdlet, New-PfaCliCommand, that 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.

New-PfaCLICommand -EndPoint 10.21.201.57 -Credentials $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 the error below.

New-PfaCLICommand : 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
At line:3 charrl
+ New-PfaCLICommand -EndPoint Sarray -Credentials $cred -CommandText "? ...
+ Categorylnfo : NotSpecified: (:) [New-PfaCLICommand], SocketException
-I- FullyQualifiedErrorld : System. Net. Sockets. SocketException, PurePowerShel 1. NewCLICommand

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.