Pure Storage FlashArray PowerShell SDK

Latest version 2.2.279 (May 2022)

► Download from the PSGallery

► Download the MSI Installer

► Release Notes

► about_Pfa2Filtering.Help.txt

// FIXES.

    1. Due to a security change in Purity version 6.1.15, the New-Pfa2ArrayAuth & Invoke-Pfa2CLICommand cmdlets can not acquire a valid certificate from the array to execute a CLI command. The failure happens before the command is sent to the array.

// Known Issues

• When a cmdlet is launched, it will by default call the Purity API version 2.2 instead of calling the highest API version available on the array (ie. 2.0 or 2.1). This can be overridden at the cmdlet level by specifying the -ApiVersion parameter for each cmdlet that is affected (ex. Get-Pfa2Volume -ApiVersion 2.0). Or, if it is done on connection to the array using the Connect-Pfa2Array cmdlet (ex. Connect-Pfa2Array -ApiVersion 2.0), then all cmdlets executed during that session with that array will be calls to the API version 2.0. 

• The Get-Pfa2AlertEventcmdlet returns incomplete error information. The -Ids parameter should be mandatory. This is a current limitation of the REST response. This will be resolved in the next release of the SDK. 

• The Get-Pfa2ApiClientcmdlet cannot sort by the "keyid" property using the -Sort switch. This will be resolved in the next release of the SDK.

• The Update-Pfa2AdminSetting cmdlet doesn't allow resetting -MaxLoginAttempts or -LockoutDuration. This is a limitation of the PowerShell client and will be addressed in a later build.
• Objects returned by REST APIs care immutable and cannot be modified. If for some reason you need to modify the returned object(s), you would need to copy it first, property by property, to a new object.
• When -ErrorActionPreference is Continue, The REST API will still stop processing a pipeline when an error occurs. For cmdlets like New-Pfa2Volume which can accept a pipeline of volume names, the Powershell client batches these into a single REST request to the FlashArray.

• There is a limitation of the cmdlet New-Pfa2Kmip. When creating a new KMIP server, a certificate is required. The mandatory parameter -Certificate accepts the value of a certificate name instead of certificate content. The proper workflow to create a KMIP server is:

      1 - Import a certificate and assign a name for the certificate

      2 - Use a certificate name when creating KMIP server

  However, the Pure Storage FlashArray PowerShell SDK 2.2 does not provide the functionality of importing a certificate (as shown in Step 1). The limitation also applies to the Update-Pfa2Kmip cmdlet when a user wants to update a certificate of a specific KMIP server. The cmdlet to provide this will be introduced in a future release. The alternative way to realize step 1 is to use the CLI to import the certificate. For information about the purecert CLI command, please refer to this support article.
   
  Other KMIP related cmdlets like Get-Pfa2Kmip, Delete-Pfa2Kmip, and Get-Pfa2KmipTest do not have the limitation mentioned above.

Latest version 1.19.49 (May 2022 - final major update)

► Download from the PSGallery

► Download the MSI Installer

► Release Notes

► Readme.md

// FIXES.

    1. Due to a security change in Purity version 6.1.15, the New-PfaCliCommand cmdlet can not acquire a valid certificate from the array to execute a CLI command. The failure happens before the command is sent to the array.

// Known Issues

• When using the Get-PfaAllNetworkInterfaceMetricsErrorTotal cmdlet with API versions 1.17 to 1.19:
• The Total result is only returned for Purity versions 5.3.0, 5.3.2, and 6.0.0. Total is not returned on 6.1.6 or 6.2.0. This is due to a limitation in the Purity REST API.
• When using the Get-PfaAllDriveAttributes cmdlet with API version 1.0 to 1.19:
• last_evac_completed and last_failure results are only available with Purity versions 5.2.7, 5.3.0, and 5.3.2. This is due to a limitation in the Purity REST API.
• The cmdlet Get-PfaBlockDifferences contains a parameter called -VolumeName. This parameter name is incorrect in that the cmdlet only works with snapshots, not volumes. This parameter has an alternative alias of -SnapshotName that can be used. Since this is an alias of the -VolumeName parameter, scripts that use that parameter will continue to execute without error.
•  Any previous known issues in the previous 1.17.16 release that have not been listed as corrected in the "Fixes" section above.

Version 2.2.272

// New in this Release

• This release is a rebuild of the PowerShell SDK with FlashArray API parity up to version 2.2.
• Overall total number of cmdlet reduction from 441 to 200 by consolidation of plural cmdlet naming to singular naming, as well as combining cmdlet functionality.
• Cmdlet naming convention change to allow for API 1.x and 2.x interoperability and side-by-side operation.
• Integration of secure OAuth authentication. (required for API 2.0 and 2.1)
• .NET Core 2.x support.
• Expanded cmdlet pipelining.
• Additional -Filter parameter for cmdlets (refer to the about_Pfa2Filtering.Help.txt link below).
• Common C# wrapper implementation used in many Pure Storage SDK offerings, such as the VMware SDK.
• Cross-platform operating system support using PowerShell version 7.x on MacOS and Linux.⁽¹⁾
• Addition of -ApiVersion parameter for cmdlets to target a specific API version.

^{(1) Limited version and distribution compatibility tested. Please see the SDK version 2.x Requirements above.}

// Known Issues

• When a cmdlet is launched, it will by default call the Purity API version 2.2 instead of calling the highest API version available on the array (ie. 2.0 or 2.1). This can be overridden at the cmdlet level by specifying the -ApiVersion parameter for each cmdlet that is affected (ex. Get-Pfa2Volume -ApiVersion 2.0). Or, if it is done on connection to the array using the Connect-Pfa2Array cmdlet (ex. Connect-Pfa2Array -ApiVersion 2.0), then all cmdlets executed during that session with that array will be calls to the API version 2.0. 

• The Get-Pfa2AlertEventcmdlet returns incomplete error information. The -Ids parameter should be mandatory. This is a current limitation of the REST response. This will be resolved in the next release of the SDK. 

• The Get-Pfa2ApiClientcmdlet cannot sort by the "keyid" property using the -Sort switch. This will be resolved in the next release of the SDK.

• The Update-Pfa2AdminSetting cmdlet doesn't allow resetting -MaxLoginAttempts or -LockoutDuration. This is a limitation of the PowerShell client and will be addressed in a later build.
• Objects returned by REST APIs care immutable and cannot be modified. If for some reason you need to modify the returned object(s), you would need to copy it first, property by property, to a new object.
• When -ErrorActionPreference is Continue, The REST API will still stop processing a pipeline when an error occurs. For cmdlets like New-Pfa2Volume which can accept a pipeline of volume names, the Powershell client batches these into a single REST request to the FlashArray.

• There is a limitation of the cmdlet New-Pfa2Kmip. When creating a new KMIP server, a certificate is required. The mandatory parameter -Certificate accepts the value of a certificate name instead of certificate content. The proper workflow to create a KMIP server is:

      1 - Import a certificate and assign a name for the certificate

      2 - Use a certificate name when creating KMIP server

  However, the Pure Storage FlashArray PowerShell SDK 2.2 does not provide the functionality of importing a certificate (as shown in Step 1). The limitation also applies to the Update-Pfa2Kmip cmdlet when a user wants to update a certificate of a specific KMIP server. The cmdlet to provide this will be introduced in a future release. The alternative way to realize step 1 is to use the CLI to import the certificate. For information about the purecert CLI command, please refer to this support article.
   
  Other KMIP related cmdlets like Get-Pfa2Kmip, Delete-Pfa2Kmip, and Get-Pfa2KmipTest do not have the limitation mentioned above.

Version 1.19.37

// New in this Release

• New Cmdlets:
  • Add-PfaPodReplicaLink
  • Add-PfaVolumesTag
  • Get-PfaAllPodIOLatencyReplicationMetricsMirrored
  • Get-PfaAllPodIOReplicationMetricsMirrored
  • Get-PfaAllVolumeOffloadSnapshotRestoreStatus
  • Get-PfaOffloadSnapshotRestoreStatus
  • Get-PfaOffloadTargetWithSpace
  • Get-PfaPendingDeleteSnapshotsTags
  • Get-PfaPendingDeleteVolumesTags
  • Get-PfaPodIOLatencyReplicationMetricsMirrored
  • Get-PfaPodIOReplicationMetricsMirrored
  • Get-PfaPodReplicaLink
  • Get-PfaPodReplicaLinkHistory
  • Get-PfaSnapshotTag
  • Get-PfaSnapshotsTag
  • Get-PfaVolumeIOLatencyMetricsMirroredByTimeRange
  • Get-PfaVolumeIOMetricsMirroredByTimeRange
  • Get-PfaVolumeTags
  • Get-PfaVolumesTags
  • Invoke-PfaRestCommand
  • New-PfaRestApiToken
  • Remove-PfaReplicaLink
  • Remove-PfaVolumeTag
  • Set-PfaPodDemote
  • Set-PfaProPromote
• Raised the required minimum FlashArray Purity API version to 1.7.
• Added PowerShell version check to New-PfaArray cmdlet. This was done to inform the user that the SDK v1 can not be executed in a PowerShell version 6 (.net Core) or later session as it is not compatible with those versions. Optimally, this warning should be presented at the time of the module load, but that is not possible within the PowerShell framework.
• Added support for persistent array connections. Once an array connection is made using the New-PfaArray cmdlet, a new global variable is created called $PURE_AUTH_1_X. All commands executed after will use that variable and that array connection. This removes the requirement of having to specify the -Array parameter for each cmdlet. When the cmdlet Disconnect-PfaArray is executed, the $PURE_AUTH_1_X variable is removed. In the case where multiple array connections are established, the variable will always contain the last array that a connection was made to. This change coincides with the same functionality of the SDK version 2.

// Fixes

• Enhanced cmdlet help and online dynamic help. 
• Due to changes in the REST API, not all cmdlets support the Filtering parameters that include -Filter, -Sort, -Offset, -Limit, and -TotalItemCountVariable, even though they allowed them when executed. This has been resolved whereas only the cmdlets that support Filtering will allow the parameters. Please see about_Purity_Filtering help for more Information on filtering with examples.

// Known Issues

• When using the Get-PfaAllNetworkInterfaceMetricsErrorTotal cmdlet with API versions 1.17 to 1.19:
• The Total result is only returned for Purity versions 5.3.0, 5.3.2, and 6.0.0. Total is not returned on 6.1.6 or 6.2.0. This is due to a limitation in the Purity REST API.
• When using the Get-PfaAllDriveAttributes cmdlet with API version 1.0 to 1.19:
• last_evac_completed and last_failure results are only available with Purity versions 5.2.7, 5.3.0, and 5.3.2. This is due to a limitation in the Purity REST API.
• The cmdlet Get-PfaBlockDifferences contains a parameter called -VolumeName. This parameter name is incorrect in that the cmdlet only works with snapshots, not volumes. This parameter has an alternative alias of -SnapshotName that can be used. Since this is an alias of the -VolumeName parameter, scripts that use that parameter will continue to execute without error.
•  Any previous known issues in the previous 1.17.16 release that have not been listed as corrected in the "Fixes" section above.

Version 1.17.16

// New in This Release

• Fix for possible race condition when using specific cmdlets.

Version 1.17.11

// New in This Release

• Added -DisableLoggingToArray to New-PfaArray and New-PfaCLICommand to disabled phone home logging to the array (and the associated thread) for this connection.
• Fixed resource consumption issue in a New-PfaCLICommand connection that could cause the number of threads in a process to continually increase.

// Known Issues

• Get-PfaProtectionGroupVolumeSnapshots does not work if the array is connected using REST API 1.4.

The following Cmdlets remove the "-CaCertificate" parameter. See the new New-PfaKMIP cmdlet.

•     Import-PfaNamedCertificate 
•     New-PfaNamedCertificate
• Get-PfaNamedCertificate no longer accepts the -ExportCaCertificate parameter.

Version 1.17.3

// New Features

Release 1.17.3.0 adds the following changes to Release 1.16

Added support for Maintenance Window.

•     New-PfaMaintenanceWindow
•     Get-PfaMaintenanceWindow
•     Remove-PfaMaintenanceWindow

Added CaCertificate to New-PfaKMIP cmdlet.

Added support for Azure Offload.

•     Connect-PfaOffloadAzureTarget
•     Get-PfaOffloadAzureTarget
•     Get-PfaAllOffloadAzureTarget
•     Disconnect-PfaOffloadAzureTarget

Added support for EULA.

•     Get-PfaArrayEula
•     Set-PfaArrayEulaAccept

Added support for Network Interface metrics.

•     Get-PfaNetworkInterfaceMetrics
•     Get-PfaNetworkInterfaceMetricsError
•     Get-PfaAllNetworkInterfaceMetrics
•     Get-PfaAllNetworkInterfaceMetricsError
•     Get-PfaAllNetworkInterfaceMetricsErrorTotal
•     Get-PfaAllNetworkInterfaceMetricsTotal

Added support for POD metrics.

•     Get-PfaAllPodSpaceMetricsTotal

Added support for Protection Group replication bandwidth

•     Get-PfaAllProtectionGroupReplicationBandwidth
•     Get-PfaAllProtectionGroupReplicationBandwidthByTimeRange
•     Get-PfaProtectionGroupReplicationBandwidth
•     Get-PfaProtectionGroupReplicationBandwidthByTimeRange

Added support for reading volume host encryption key status

•     Get-PfaVolumeHostEncryptionKeyStatus
•     Get-PfaAllVolumeHostEncryptionKeyStatus

Added support for reading volume space metrics.

•     Get-PfaAllVolumeSpaceMetricsTotal
•     Get-PfaAllVolumeTotal

Added support for reading volume group bandwidth

•     Set-PfaVolumeGroupBandwidthLimit

Added support for volume and volume group IOPS limit

•     Set-PfaVolumeGroupIOPSLimit
•     Set-PfaVolumeIOPSLimit

Added support for VNC support for software app 

•     Disable-PfaSoftwareVNC
•     Enable-PfaSoftwareVNC

Added support for reading the software app nodes.

•     Get-PfaAllSoftwareNode
•     Get-PfaSoftwareNode

Version 1.16.6

// New Features

Release 1.16.6.0 adds the following changes to Release 1.13

• Added support for REST 1.14, 1.15 and 1.16. The following features are implemented.

Added support for NFS and S3 snapshot offload 

•  Connect-PfaOffloadNFSTarget
•  Connect-PfaOffloadS3Target
•  Disconnect-PfaOffloadNFSTarget
•  Disconnect-PfaOffloadS3Target
•  Get-PfaAllProtectionGroupOffloadSnapshot
•  Get-PfaAllVolumeOffloadSnapshot
•  Get-PfaOffloadNFSTarget
•  Get-PfaOffloadS3Target
•  Get-PfaOffloadSnapshot
•  Get-PfaOffloadTarget
•  Get-PfaProtectionGroupOffloadSnapshot
•  Restore-PfaAllVolumeOffloadSnapshot

Added support for how directory service roles are modified

•  Get-PfaDirectoryServiceRole
•  New-PfaDirectoryServiceRole

Added support for maximum login attempts and user lockout

•  Get-PfaAdminSetting
•  Get-PfaAllLockedUser
•  Get-PfaLockedUser
•  Set-PfaAdminSetting
•  Unlock-PfaUser

Added support for host NQN's

•  Add-PfaHostNqn
•  Remove-PfaHostNqn
•  Set-PfaHostNqn

Added support for creating and deleting local user

•    New-PfaLocalUser
•  Remove-PfaLocalUser

Added support to view and manage software applications on Purity Array

•    New-PfaSoftware
•  Get-PfaSoftware
•  Disable-PfaSoftware
•  Enable-PfaSoftware
•  Remove-PfaSoftware
•  Get-PfaSoftwareAttribute

Added ability to view pods on remote array

•    Get-PfaAllRemotePod
•  Get-PfaRemotePod

Added the ability to list latency values when viewing performance data.

•   Get-PfaAllHostGroupIOLatencyMetrics
•   Get-PfaAllHostGroupIOLatencyMetricsMirrored
•   Get-PfaAllHostGroupIOLatencyMetricsTotal
•   Get-PfaAllHostIOLatencyMetrics
•   Get-PfaAllHostIOLatencyMetricsMirrored
•   Get-PfaAllHostIOLatencyMetricsTotal
•   Get-PfaAllPodIOLatencyMetricsMirrored
•   Get-PfaAllVolumeGroupIOLatencyMetrics
•   Get-PfaAllVolumeGroupIOLatencyMetricsByTimeRange
•   Get-PfaAllVolumeGroupsIOLatencyMetricsTotal
•   Get-PfaAllVolumeIOLatencyMetrics
•   Get-PfaAllVolumeIOLatencyMetricsByTimeRange
•   Get-PfaAllVolumeIOLatencyMetricsTotal
•   Get-PfaArrayIOLatencyMetrics
•   Get-PfaHostGroupIOLatencyMetrics
•   Get-PfaHostGroupIOLatencyMetricsMirrored
•   Get-PfaHostIOLatencyMetrics
•   Get-PfaHostIOLatencyMetricsMirrored
•   Get-PfaNamedVolumeGroupsIOLatencyMetricsByTimeRange
•   Get-PfaNamedVolumesIOLatencyMetricsByTimeRange
•   Get-PfaPodIOLatencyMetricsMirrored
•   Get-PfaVolumeGroupIOLatencyMetrics
•   Get-PfaVolumeGroupIOLatencyMetricsByTimeRange
•   Get-PfaVolumeIOLatencyMetrics
•   Get-PfaVolumeIOLatencyMetricsByTimeRange

Added the following new cmdlets:

•   Set-PfaHost
•  Set-PfaPod
•  Set-PfaVolumeBandwidthLimit
•  Set-PfaSmtpManagerAttribute
•  Get-PfaSmtpManagerAttribute

Updated the following cmdlets:

• Get-PfaHost
• Get-PfaHosts
• Get-PfaPod
• Get-PfaPods
• Get-PfaVolume
• Get-PfaVolumes
• New-PfaHost
• New-PfaPod
• New-PfaVolume
• Remove-PfaProtectionGroupOrSnapshot
• Restore-PfaDestroyedProtectionGroup

The following cmdlets starting REST 1.16 do not return "san_usec_per_read_op", "san_usec_per_write_op". These values are part of new cmdlet mentioned above *IOLatency*.

• Get-PfaAllHostIOMetrics
• Get-PfaHostIOMetricsAverage
• Get-PfaAllHostIOMetricsTotal
• Get-PfaArrayIOMetrics
• Get-PfaArrayIOMetricsAverage
• Get-PfaAllVolumeIOMetricsByTimeRange
• Get-PfaNamedVolumesIOMetricsByTimeRange
• Get-PfaVolumeIOMetrics
• Get-PfaVolumeIOMetricsByTimeRange
• Get-PfaAllVolumeIOMetric

// Known Issues

• The Remove-PfaVolumeorSnapshot and Remove-PfaProtectionGrouporSnapshot cmdlets will not allow for a single operation of both Destroy and Eradicate. The cmdlets must be run twice, once to Destroy and once to Eradicate. It is recommended that if using these cmdlets in an automation routine, that a "sleep" or "pause" of at least 2 seconds be done between operations to ensure the Destroy was completed.

Version 1.13.1.12

The Pure Storage PowerShell SDK leverages the REST API and wraps those APIs as PowerShell cmdlets.

// New Features

Release 1.13.0 adds the following changes to Release 1.7

• Support for REST 1.12 and REST 1.13, bug fixes.
• TMAN-3817: Added notification property to SNMPManager object. New cmdlet: Set-PfaSnmpManagerNotification
• Added -Filter parameter to cmdlets that return multiple objects to enable server side filtering. See new help topic about_Purity_Filtering.

Added the following new cmdlets related to Pod and sync-rep management

• Add-PfaArrayToPod
• Copy-PfaPod
• Get-PfaAllPodFootprint
• Get-PfaAllPodMediator
• Get-PfaAllPodSpaceHistory
• Get-PfaAllPodSpaces
• Get-PfaNamedPodFootprint
• Get-PfaNamedPodMediator
• Get-PfaNamedPodSpace
• Get-PfaNamedPodSpaceHistory
• Get-PfaNamedPods
• Get-PfaPendingDeletePods
• Get-PfaPendingPodFootprint
• Get-PfaPendingPodMediator
• Get-PfaPendingPodSpace
• Get-PfaPod
• Get-PfaPods
• New-PfaPod
• Remove-PfaArrayFromPod
• Remove-PfaPod
• Rename-PfaPod
• Restore-PfaPod

Added the following cmdlets to support named certificate management.

• Get-PfaNamedCertificate
• Get-PfaNamedCertificateAttribute
• Get-PfaNamedCertificateAttributes
• Import-PfaNamedCertificate
• Remove-PfaNamedCertificate
• New-PfaNamedCertificateImport
• New-PfaNamedSelfSignedCertificate

Added the following cmdlets to support reading mirrored IO statistics.

• Get-PfaAllHostGroupIOMetricsMirrored
• Get-PfaAllHostIOMetricsMirrored
• Get-PfaAllPodIOMetricsMirrored
• Get-PfaAllVolumeIOMetricsMirrored
• Get-PfaArrayIOMetricsMirrored
• Get-PfaHostGroupIOMetricsMirrored
• Get-PfaHostIOMetricsMirrored
• Get-PfaPodIOMetricsMirrored
• Get-PfaVolumeIOMetricsMirrored

Added the following cmdlets to support KMIP.

• Get-PfaKmip
• Get-PfaKmips
• New-PfaKmip
• Remove-PfaKmip
• Test-PfaKmip
• Update-PfaKmip

Added the following cmdlets to support Purity //Run apps

• Get-PfaPureAppAttributes
• Get-PfaPureAppsAttributes

Added the following cmdlets to support volume groups and vvols.

• Get-PfaAllVolumeGroupIOMetrics
• Get-PfaAllVolumeGroupIOMetricsByTimeRange
• Get-PfaAllVolumeGroupsIOMetricsAverage
• Get-PfaAllVolumeGroupsIOMetricsTotal
• Get-PfaVolumeGroupIOMetrics
• Get-PfaVolumeGroupIOMetricsAverage
• Get-PfaVolumeGroupIOMetricsByTimeRange
• Get-PfaVolumeGroupSpaceMetrics
• Get-PfaVolumeGroupSpaceMetrics
• Get-PfaNamedVolumeGroupsIOMetricsByTimeRange
• Get-PfaNamedVolumeGroups
• Get-PfaPendingDeleteVolumeGroups
• Get-PfaProtocolEndpointVolumes
• Get-PfaProtocolEndpointVolume
• Get-PfaVolumeGroups
• Get-PfaVolumeGroup
• New-PfaHostGroupProtocolEndpointVolumeConnection
• New-PfaHostProtocolEndpointVolumeConnection
• New-PfaProtocolEndpointVolume
• New-PfaVolumeGroup
• Remove-PfaVolumeGroup
• Restore-PfaVolumeGroup

Added the following cmdlets to support remote host/hostgroup/volume operations

• Get-PfaRemoteHost
• Get-PfaRemoteHostGroup
• Get-PfaRemoteHostGroupVolumeConnections
• Get-PfaRemoteHostGroups
• Get-PfaRemoteHosts
• Get-PfaRemoteVolumeHostConnections
• Get-PfaRemoteVolumeHostGroupConnections
• Get-PfaVolumeConnection
• Get-PfaArrayTCPConnection