PureStorage.FlashArray.Backup PowerShell Module

Last updated
Save as PDF

Introduction

The PureStorage.FlashArray.Backup PowerShell Module (Backup Module) enables administrators to create Volume Sets from disks that are directly attached to a computer running Windows Server. Snapshots can be taken of a Volume Set, and these snapshots can be mounted on another Windows Server. If the Volume Set includes more than 1 Pure Volume, Protection Groups snapshots should be used to ensure consistency. Protection Group snapshots that are replicated to another FlashArray or Cloud Block Store instance in AWS or Azure can be mounted to Windows Servers that are connected to the remote FlashArray.

The PureStorage.FlashArray.Backup PowerShell Module is currently a prerelease beta and is intended for testing in non-production environments. Please send constructive feedback on what is working well, and requests for enhancement on the Pure Storage Community Site.

This beta module is signed and is posted to the PSGallery.

Installing the Backup Module

This section will show you how to install Backup Module.

PowerShell 7.x

Both PowerShell 5.x and 7.x is supported. PowerShell 7.x ships with updated PowerShellGet that understand the -Allowprerelease parameter.

Install-Module purestorage.flasharray.backup

PowerShell 5.x

PowerShell 5.x by default does not have the updated version of PowerShellGet which is required for prereleases. For GA releases, simply use the Install-Module cmdlet.

Install-Module purestorage.flasharray.backup

PowerShell Core

PowerShell Core can be installed on many operating systems and can have the PureStorage.FlashArray.Backup PowerShell module installed. Command initiated from PowerShell Core will open a remote session through SSH to the specified 'ComputerAddress' which will need to be configured with SSH to receive such a connection.

When performing installations, make sure that you are using an administrator PowerShell session. If you get an error about computer credentials, ensure a remote PowerShell session can be opened with the computer credential. One method is to bind a credential to a secure variable. Here is an example:
$compcred = Get-Credential New-PSSession -Credential $compcred

How It Works

The Backup Module requires the creation of a Volume Set. A Volume Set is a friendly name for a set of drive letters and mount points configured in Windows Server that are Volumes on the FlashArray. Once a Volume Set is defined, Protection Group snapshots that are crash consistent can be taken of the Volumes associated with the Volume Set. This means that the volume shadow copy service (VSS) is not required. A snapshot generated can then be mounted one or more times to a destination using the same disk type as the source Volume.

Currently, Backup Module only supports a target that is a physical or virtual Windows Server-based deployment regardless of workload. The reason for this is that specifying a disk path is required. VMs can be Hyper-V or VMware-based. Physical servers can have storage attached via iSCSI or fibre channel. VMs support the following connectivity methods for Volumes:

In-guest iSCSI
Virtual fibre channel
Raw Device Mapping (pRDM) disks (VMware only)
Virtual Volume (vVol) disks (VMware only)

Passthrough disks in Hyper-V are currently not supported. If passthrough disks in Hyper-V or Linux support is important to your environment, work with your Pure AE/SE to file a request for enhancement (RFE).

Details for the parameters associated with each cmdlet are documented in Parameter Reference.

VMware UUID

On some VMware environments, a Windows Server VM will not show the actual UUID of the disks. Attempts to do anything with these disks will result in an error that the disk is unsupported.

To test if the UUID is incorrect, run the following in PowerShell:

$disk = get-disk $disk.uniqueid

The above image is not the proper UUID and ends with the hostname of the VM. If the uniqueid is like the above, the module will not work with VMware Virtual Volumes unless the VMX is modified.

The above image is a proper UUID.

One line needs to be added to the VMX file for each VM.

1) Power off the VM.

2) In vCenter, right click a VM, and select Edit Settings.

3) Select VM Options, and then expand Advanced by clicking the greater than sign '>' to the left of Advanced.

4) Scroll down and select Edit Configuration

5) Look for the disk.ENABLEUUID line, and change it to TRUE. Notice that you are unable to modify this line if the VM is powered on.

6) After the VM is powered off, go back to the Configuration Parameters and highlight False.

7) Change it to TRUE

8) If there is no disk.ENABLEUUID entry, select ADD CONFIGURATION PARAMS at the top of Configuration Parameters.

9) With no extra characters or spaces before or after type disk.ENABLEUUID under Name, and TRUE, under Value.

10) Select OK, then Power On the VM.

11) Rerun the PowerShell lines to enumerate the UUID and ensure they look like the following image, and not "SCSI\DISK*:<hostname>"

Create a Volume Set

Creating a new Volume Set is achieved by executing the cmdlet New-PsbVolumeSet.

TIP One way of adding a credential to a secure variable is by assigning get-credential to a variable. $credentialvariable = Get-Credential

The example below creates a new Volume Set for a VMware VM using vVol disks.

New-PsbVolumeSet -VolumeSetName volset136 -ComputerAddress $vmname -ComputerCredential $vmCredential -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential -Path 'h:\,F:\' -VCenterAddress $vCenterEndpoint -vCenterCredential $vCenterCredential -VMName $vmname -VMPersistentID $VMPID -VolumeType vVol

Create a replication target, automatic snapshot generation, and retention policies for the Protection Group in the FlashArray UI or utilizing the PureStoragePowerShellSDK2.

Invoke a Snapshot

Invoke a snapshot with the cmdlet Invoke-PsbSnapshotJob. The first time a snapshot is invoked, the Protection Group to use must be figured out or created. Subsequent snapshots only need to declare the Protection Group.

The first example creates a Protection Group with the name psb-2022prev with the Volumes declared in Path.

Invoke-PsbSnapshotJob -VCenterAddress $vcenterendpoint -VCenterCredential $vcentercredential -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential -VolumeSetName volset136 -VolumeType vVol -ComputerAddress $vmname -ComputerCredential $vmcredential -Path 'H:\,F:\' -CreatePgroup -NewPgroupSuffix volset136 -VmName $vmname -VmPersistentId $VMPID

The second example uses the Protection Group already created in the first example which means that it is not the first time the cmdlet has been executed.

Invoke-PsbSnapshotJob -VCenterAddress $vcenterendpoint -VCenterCredential $vcentercredential -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential -VolumeSetName volset136 -VolumeType vVol -ComputerAddress $vmname -ComputerCredential $vmcredential -Path 'H:\,F:\' -Pgroupname psb-volset136 -VmName $vmname -VmPersistentId $VMPID

The third example chooses the Protection Group with the fewest number of additional volumes. It will fail is there is not an existing Protection Group that contains all of the declared volumes with Path.

Invoke-PsbSnapshotJob -VCenterAddress $vcenterendpoint -VCenterCredential $vcentercredential -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential -VolumeSetName volset136 -VolumeType vVol -ComputerAddress $vmname -ComputerCredential $vmcredential -Path 'H:\,F:\' -UseBestPgroupMatch -VmName $vmname -VmPersistentId $VMPID

Mount a Snapshot

To mount a snapshot to a physical or virtual server, use the cmdlet Mount-PsbSnapshotSet. Get the latest snapshot of a volume set to mount with the Get-PsbSnapshotJobHistory cmdlet.

The example below mounts the snapshot to the computer declared in -ComputerAddress.

Mount-PsbSnapshotSet -HistoryId $snaps[0].HistoryId -VCenterAddress $vcenterendpoint -VCenterCredential $vcentercredential -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential -ComputerAddress $vmname -ComputerCredential $vmcredential -Path 'c:\mp101,c:\mp102' -VmPersistentId $VMPID

When performing a mount operation, the target server must support the same disk type as the source. A RDM cannot be mounted as a vVol or physical disk. A vVol cannot be mounted as an RDM or physical disk. A physical disk type cannot be mounted as an RDM or vVol.

In the case of replicated protection group snapshots, the -DatastoreName to be used, can be declared since the source datastore will not exist on the target FlashArray.

Dismount a Snapshot

To dismount a snapshot use the Dismount-PsbSnapshotSet cmdlet. Get the MountID from the Get-PsbSnapshotSetMountHistory cmdlet.

The example below will remove the mount from the computer declared in -ComputerAddress.

Dismount-PsbSnapshotSet -VCenterAddress $vcenterendpoint -VCenterCredential $vcentercredential -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential -ComputerAddress $vmname -ComputerCredential $vmcredential -MountId $mounts[0].mountid

List Available Drive Letters

To find available drive letters to be able to mount a snapshot set on the local or remote Windows Server machine, use the cmdlet Get-PsbAvailableDrives.

An example is shown below.

$session = New-PSSession Get-PSBAvailableDrive -ComputerAddress localhost -ComputerSession $session

List the Snapshot Job History

Use this cmdlet to get the list of snapshots that were invoked. A where statement can narrow down the results. The first object will be the most recent snapshot.

$snaps = Get-PsbSnapshotJobHistory -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential -VolumeSetName volset136

When enumerating snapshots that were replicated to the declared -FlashArrayAddress, the correct -VolumeSetName is critical since a query for the volume set will return nothing since the only the replicated snapshots will exist, not the original volumes which are the source of those snapshots. By default only snapshots created by utilizing the Invoke-PsbSnapshotJob cmdlet will be shown. To show all snapshots, such as those created by Protection Group policies, include the -IncludeNonSDKSnapshots parameter.

List the Snapshot Set Mount History

To list a particular volume set with the -VolumeSetName parameter or to see all Volume Sets (do not use the -VolumeSetName parameter) use the Get-PsbSnapshotSetMountHistory cmdlet.

Use this cmdlet with a where statement to find the computer and mount that you want. Without a where, the correct mountid needed for Dismount-PsbSnapshotSet will have to be discerned from the returned array of all mounts created with this module.

The example below will return all the mounts where the computer name contains the value assigned to the $vmname variable and a path of "c:\mp101".

$mounts = Get-PsbSnapshotSetMountHistory -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential | where {($_.Computer -Contains $vmname -and $_.Paths -Contains "c:\mp101")}

List Virtual Machine Persistent IDs

For VMware-based VMs using RDMs or vVols, use the cmdlet Get-PsbVmPersistentID if the VMware administrator changes the friendly name of the VM as seen in vCenter. Subsequent automation will fail if you only declare the VMName parameter.

$VMPID = Get-PSBVMPersistentId -VCenterAddress $vcenterendpoint -VCenterCredential $vcentercredential -VmName $vmname

List the Volume Set(s)

To list a particular volume set with the -VolumeSetName parameter or to see all Volume Sets (do not use the -VolumeSetName parameter) use the Get-PsbVolumeSet cmdlet.

The example below will return all Volume Sets.

Get-PsbVolumeSet -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential

List Protection Groups that Contain the Volumes in a Volume Set

To enumerate any Protection Groups that contain the Volumes in a specific Volume Set, use the cmdlet Get-PsbVolumeSetProtectionGroup. An example is shown below.

Get-PsbVolumeSetProtectionGroup -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential -VolumeSetName volset136

Remove a Snapshot

To remove a snapshot that was created as part of a Volume Set, use the cmdlet Remove-PsbSnapshotSet. Combine this cmdlet with Get-PsbSnapshotJobHistory to enumerate the snapshots to find the one(s) to remove. An example is shown below.

Remove-PsbSnapshotSet -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential -HistoryId $snaps[0].historyid

Remove a Volume Set

To remove a Volume Set, use the cmdlet Remove-PsbVolumeSet. An example is shown below.

Remove-PsbVolumeSet -FlashArrayAddress $FADNS -FlashArrayCredential $FlashArrayCredential -VolumeSetName myvolSet

Backup Module and SQL Server 2022's Transact-SQL Snapshot Backup Feature

Microsoft SQL Server 2022 added new functionality, Transact-SQL snapshot backup, that enables application consistent snapshots without requiring the volume shadow copy service (VSS). This process will work with Backup Module and crash consistent backups. An article will be forthcoming on how to use this feature with FlashArray snapshots.

Parameter Reference

Parameter	Cmdlet(s)	Values	Description
`ComputerAddress`	`Dismount-PsbSnapshotSet Get-PsbAvailableDrive Invoke-PsbSnapshotJob Mount-PsbSnapshotSet New-PsbVolumeSet`		The name (DNS or Fully Qualified Domain Name) or IP address of a physical server or VM running Windows Server.
`ComputerSession`	`Get-PSBAvailableDrive`		A session that is declared if Backup Module is installed on MacOS or Linux, allowing a remote PowerShell session to the target Windows Server (`ComputerAddress`). See PowerShell Core for more information.
`ComputerCredential`	`Dismount-PsbSnapshotSet Invoke-PsbSnapshotJob Mount-PsbSnapshotSet` `New-PsbVolumeSet`		The credentials for the Windows Server passed in through a variable.
`CreatePgroup`	`Invoke-PsbSnapshotJob`		Use this the first time `Invoke-PsbSnapshotJob` is run to create a Protection Group with psb- as the prefix. It also adds all Volumes declared in the `Path` parameter.
DatastoreName	`Mount-PsbSnapshotSet`		Use this to declare which datastore to use for the mounted volumes. This is most useful in replicated environments where the target FlashArray is not the same FlashArray as the source volumes used to create the snapshots.
`FlashArrayAddress`	`Dismount-PsbSnapshotSet Get-PsbSnapshotJobHistory Get-PsbVolumeSet Get-PsbVolumeSetProtectionGroup Invoke-PsbSnapshotJob Mount-PsbSnapshotSet New-PsbVolumeSet Remove-PsbSnapshotSet Remove-PsbVolumeSet`		The name (DNS or Fully Qualified Domain Name) or IP address of a Pure Storage FlashArray.
`FlashArrayCredential`	`Dismount-PsbSnapshotSet Get-PsbSnapshotJobHistory Get-PsbVolumeSet Get-PsbVolumeSetProtectionGroup Invoke-PsbSnapshotJob Mount-PsbSnapshotSet New-PsbVolumeSet Remove-PsbSnapshotSet Remove-PsbVolumeSet`		The credentials for a Pure Storage FlashArray passed in through a variable.
`HistoryID`	`Mount-PsbSnapshotSet Remove-PsbSnapshotSet`		A unique ID assigned to a snapshot set when the snapshot is created.
`MountID`	`Dismount-PsbSnapshotSet`		A unique ID assigned when a snapshot set is mounted. This allows the same source snapshot set to be mounted multiple times.
`NewPgroupSuffix`	`Invoke-PsbSnapshotJob`		These parameters can be used to create a Protection Group the first time `Invoke-PsbSnapshotJob` is run. This will create a Protection Group with the suffix provided.
`NoPgroup`	`Invoke-PsbSnapshotJob`		This should only be used when a single Pure Volume is declared. A Volume snapshot will be taken instead of a Protection Group snapshot. Consistency cannot be guaranteed with multiple volumes without using a protection group.
`Path`	`Invoke-PsbSnapshotJob Mount-PsbSnapshotSet New-PsbVolumeSet`		The path can be a drive letter or mount point separated by a comma without spaces. Valid path examples: Single Drive Letter `'E:\'` Multiple Drive Letters `'E:\,P:\'` Mount Point and Multiple Drive Letters `'C:\mp1,S:\,T:\'`
`PgroupName`	`Invoke-PsbSnapshotJob`		This should be the steady state parameter used when invoking a snapshot.
`ReplicateNow`	`Invoke-PsbSnapshotJob`		In the case of a Protection Group with a replication target, this parameter forces replication to occur immediately after snapshot creation. If not used, replication will occur at the interval set as part of the Protection Group replication policy.
`UseBestPgroupMatch`	`Invoke-PsbSnapshotJob`		Use this parameter to select the Protection Group that contains all of the Volumes declared using `Path` with the fewest number of additional Volumes. Only use when multiple Protection Groups include all of the declared volumes in the path and you prefer to have the cmdlet find the protection group with the fewest number of additional Volumes. Using this parameter when the declared Volumes in the path only belong to one Protection Group, and that Protection Group has many, or all of the Volumes on the FlashArray included, can waste space since it is not the number of snapshots but the change rate times the retention, that impacts snapshot consumption.
`VCenterAddress`	`Dismount-PsbSnapshotSet Get-PsbVmPersistentId Invoke-PsbSnapshotJob Mount-PsbSnapshotSet New-PsbVolumeSet`		(VMware only) The name (DNS or Fully Qualified Domain Name) or IP address of a VMware vCenter Server.
`VCenterCredential`	`Dismount-PsbSnapshotSet Get-PsbVmPersistentId Invoke-PsbSnapshotJob Mount-PsbSnapshotSet New-PsbVolumeSet`		(VMware only) The credentials for the VMware vCenter server passed in through a variable.
`VmName`	`Get-PSBVMPersistentId Invoke-PsbSnapshotJob New-PsbVolumeSet`		(VMware only) This name is the friendly name of the VM as seen by vCenter/ESXi, not the hostname or FQDN of the VM. This is only used for virtual machines in a VMware environment using either pRDM or vVol disk types. VMs that utilize in-guest iSCSI or virtual FC HBAs are treated as physical servers with physical disk types.
`VmPersistentID`	`Get-PsbVmPersistentId Invoke-PsbSnapshotJob Mount-PsbSnapshotSet New-PsbVolumeSet`		(VMware only) This is an optional parameter that will protect automation in the case that the friendly name of a VMware VM in vCenter is changed.
`VolumeSetName`	`Get-PsbSnapshotJobHistory Get-PsbVolumeSetProtectionGroup Invoke-PsbSnapshotJob New-PsbVolumeSet Remove-PsbVolumeSet`		This is the friendly name used to assign a set of Volumes to a Volume Set. If the number of Volumes declared in `Path` change, the snapshot will fail if all Volumes are not included in the declared Protection Group. Add the new volumes to the existing Protection Group or create a new one using `CreatePgroup` and NewPgroupSuffix parameters of `Invoke-PsbSnapshotJob`.
`VolumeType`	`Invoke-PsbSnapshotJob New-PsbVolumeSet`	`Physical` `RDM` `vVol`	`Physical` - Use this for bare metal servers and VMs that use virtual Fibre Channel (Hyper-V only) or in-guest iSCSI (Hyper-V and VMware) and direct Volumes on FlashArray. `RDM` - VMware VMs that use pRDMs. `vVol` - VMware VMs that use vVols.