How-To: Connect to a FlashArray with the PowerShell SDK v1
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:
- 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.
- API Token
$FlashArray = New-PfaArray -EndPoint 10.0.0.1 -ApiToken fbbb3xyz-b2da-0000-3d7d-c5604a900000
- 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.
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
.