PureStorage.FlashArray.Backup PowerShell Module

Introduction

The PureStorage.FlashArray.Backup PowerShell Module (Backup Module), enables administrators to create volume sets from disks that are physically attached to a bare metal Windows Server, any virtual machine (VM) using in-guest direct connectivity to storage (iSCSI or virtual fibre channel), and VMs  configured with Raw Device Mapping (RDM/pRDM) or vVol disks with VMware vSphere.

Volume sets are created with a friendly name and include a set of drive letters and mount points. Crash consistent, Protection Group snapshots can be taken of these volumes, and these snapshots can easily be mounted one or more times using the same disk types as the source volumes (physical, rdm, vvol). Since the disk paths must be declared, this enables snapshots of any supported Pure volume in a Windows Operating System Environment. Please see the cmdlet parameter section for details on parameter usage.

 

SQL Server 2022 & Transact-SQL Snapshot Backup

Microsoft SQL Server 2022 added new functionality, Transact-SQL snapshot backup, that enables application consistent snapshots without the volume shadow copy service (VSS). There are a few ways to connect to a SQL Server instance, and my colleague Anthony Nocentino wrote an in-depth blog on how to do it and utilize TSQL snapshot backup.

There are 3 steps involved in taking an application consistent snapshot:

1. Declare which databases are involved with TSQL.  ALTER DATABASE testdb1 SET SUSPEND_FOR_SNAPSHOT_BACKUP = ON;
2. Invoke a snapshot with this backup module. Invoke-PsbSnapshotJob...
3. Thaw the database(s) with TSQL.  BACKUP DATABASE testdb1 TO DISK = 'd:\temp\db.bkm' WITH METADATA_ONLY, FORMAT;

Create a Volume Set

VM Persistent ID: This is optional, but 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. Parameters VMPersistentID, VCenterAddress, VCenterCredential, VMName are only used on VMware VMs with pRDM or vVols.

$VMPID = Get-PSBVMPersistentId -VCenterAddress vcenter01 -VCenterCredential $vc-cred -vmname 2022

New-PsbVolumeSet: VolumeType can be vvol, rdm or physical

New-PsbVolumeSet -VolumeSetName myvolSet -ComputerAddress sqlvm2 -ComputerCredential $vmCredential -FlashArrayAddress FA-DNS -FlashArrayCredential $FlashArrayCredential -Path 'E:\,F:\' -VCenterAddress $vCenterEndpoint -vCenterCredential $vCenterCredential -VMName sqlvm2 -VMPersistentID $VMPID -VolumeType vvol

Invoke a Snapshot

Invoke-PsbSnapshotJob:  Parameters VMPersistentID, VCenterAddress, VCenterCredential, VMName are only used on VMware VMs with pRDM or vVols.

The first time a snapshot is invoked, the Protection Group to use must be figured out. Subsequent snapshots can simply declare the Protection Group to use with the -pgroupname parameter.

• Use Get-PsbVolumeSetProtectionGroup to see if any Protection Groups exist that contain all volumes in the set.
• Use the -createpgroup & -pgroupsuffix parameters in Invoke-PsbSnapshotJob to create a Protection Group with all volumes declared in the -path parameter.
• Use the -UseBestPgroupMatch parameter in Invoke-PsbSnapshotJob to select the Protection Group that contains all of the volumes declared in the -path parameter with the fewest number of additional volumes. 

#This example declares which pgroup to use

Invoke-PsbSnapshotJob -vcenteraddress vcenter01 -vcentercredential $vc-cred -FlashArrayAddress FA-DNS -FlashArrayCredential $FA-CRED -VolumeSetName 2022set2 -VolumeType vvol -ComputerAddress 2022prev -ComputerCredential $sqlvm4 -Path 'v:\,c:\mp1' -pgroupname psb-2022prev -VMName 2022 -VMPersistentId $VMPID

#This example creates a pgroup with a suffix of 2022prev, so the pgroup name will be psb-2022prev

Invoke-PsbSnapshotJob -vcenteraddress vcenter01 -vcentercredential $vc-cred -FlashArrayAddress FA-DNS -FlashArrayCredential $FA-CRED -VolumeSetName 2022set2 -VolumeType vvol -ComputerAddress 2022prev -ComputerCredential $sqlvm4 -Path 'v:\,c:\mp1' -createpgroup -newpgroupsuffix 2022prev -VMName 2022 -VMPersistentId $VMPID

#This example will select the pgroup with the fewest number of additional volumes. It will fail is there is no pgroup that contains all of the declared volumes in the -path

Invoke-PsbSnapshotJob -vcenteraddress vcenter01 -vcentercredential $vc-cred -FlashArrayAddress FA-DNS -FlashArrayCredential $FA-CRED -VolumeSetName 2022set2 -VolumeType vvol -ComputerAddress 2022prev -ComputerCredential $sqlvm4 -Path 'v:\,c:\mp1'-UseBestPgroupMatch -VMName 2022 -VMPersistentID $VMPID  

Mount a Snapshot

Get-PsbSnapshotJobHistory: The first object will be the most recent snapshot.

$snaps = Get-PsbSnapshotJobHistory -FlashArrayAddress FA-DNS -FlashArrayCredential $FA-CRED -volumesetname 2022set2

Mount-PsbSnapshotSet

Mount-PsbSnapshotSet -HistoryId $snaps[0].HistoryId -vcenteraddress vcenter01 -vcentercredential $vc-cred -FlashArrayAddress FA-DNS -flasharraycredential $FA-CRED -computeraddress 2022prev -computercredential $sqlvm4 -Path 'n:,o:' -vmpersistentid $VMPID

Dismount a Snapshot

Get-PsbSnapshotSetMountHistory:  Pipe this cmdlet with where to zero in on the computer and mount that you want, else the correct mountid will have to be discerned from the returned array of all mounts created with this module.

$mounts = Get-PsbSnapshotSetMountHistory -FlashArrayAddress FA-DNS -FlashArrayCredential $FA-CRED | where {($_.Computer -contains "2022prev" -and $_.Paths -contains "n:")}

Dismount-PsbSnapshotSet

dismount-psbsnapshotset -vcenteraddress vcenter01 -vcentercredential $vc-cred -flasharrayaddress FA-DNS -flasharraycredential $FA-CRED -mountid $mounts[0].mountid -computeraddress 2022prev -computercredential $sqlvm4

Find available drive letters

Get-PsbAvailableDrives: Find available drive letters so that you can mount a snapshot set on the local or remote Windows Server.

$session = New-PSSession

Get-PSBAvailableDrive -ComputerAddress localhost -ComputerSession $session

Enumerate the Volume Set(s)

Get-PsbVolumeSet: Return a particular volume set, or all volume sets with -volumesetname omitted.

Get-PsbVolumeSet -FlashArrayAddress FA-DNS -FlashArrayCredential $FA-CRED -VolumeSetName

Enumerate Protection Groups that contain all the volumes in a volume set

Get-PsbVolumeSetProtectionGroup

Get-PsbVolumeSetProtectionGroup -FlashArrayAddress FA-DNS -FlashArrayCredential $FA-CRED -VolumeSetName 2022set2

Remove a snapshot

Remove-PsbSnapshotSet: Enumerate the snapshots to find the one you want to remove, then remove it.

$snaps = Get-PsbSnapshotJobHistory -FlashArrayAddress $FlashArrayEndpoint -FlashArrayCredential $FlashArrayCredential -VolumeSetName qsqlvm4g

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

Remove a volume set

Remove-PsbVolumeSet

Remove-PsbVolumeSet -FlashArrayAddress FA-DNS -FlashArrayCredential $FlashArrayCredential -VolumeSetName myvolSet

PowerShell 5.x

The following errors will not happen if you install PowerShell 7.x and then use install-module with the -AllowPrerelease parameter. Not all environments will allow the installation of a newer version of PowerShell.

Errors:

This is because, even Windows Server 2022's version of PowerShell, ships with PowerShellGet 1.0.0.1 and it does not understand the prerelease parameter. Unfortunately PowerShellGet requires a particular version of nuget, so that must be installed first in an administrator PowerShell session.

Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force

Install-Module -Name PowerShellGet -Force

Install-Module must be used since 1.0.0.1 was not installed with it, so Update-Module will fail. Since 1.0.0.1 exists unless manually removed, the '-force' parameter is required. Be sure to close all PowerShell sessions, open a new one as administrator, and install the module. If you attempt to unload PowerShellGet 1.0.0.1 and load the newer version you will probably get an error when attempting to use install-module.

Install-Module -AllowPrerelease 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.

Parameter Glossary

Address: FlashArrayAddress, ComputerAddress, VcenterAddress

These are either the IP, DNS name, or Fully Qualified Domain Name for a Pure Storage FlashArray, Windows Server, or VMware vCenter Server.

Credential: FlashArrayCredential, ComputerCredential, VcenterCredential

These are secure variables with the credentials for a Pure Storage FlashArray, Windows Server, or VMware vCenter Server. One way of adding a credential to a secure variable is by assigning get-credential to a variable.  $FA-CRED = get-credential

VolumeSetName: 

This is the friendly name used to assign a set of volumes to a volume set. If the number of volumes declared in the -path change, the snapshot will fail if all volumes are not included in the declared protection group. Add the new volumes to the protection group, or create a new protection group using the -createpgroup and -newpgroupsuffix parameters of invoke-psbsnapshotjob.

VolumeType: Physical, RDM, VVOL

VMware VMs can snapshot both physical RDM and Virtual Volume (vVol) disk types. The physical disk type is all configurations where the Windows Server has a Host object on the FlashArray. This includes bare metal servers, VMs using in-guest iSCSI, and VMs using virtual fibre channel HBAs. When performing a mount operation the target (ComputerAddress) must support the disk type as the source. A VM snapshot of an RDM cannot be mounted as a vVol. A physical disk type cannot be mounted as an RDM or vVol.

ComputerSession:

If the module is installed on MacOS or Linux, a remote PowerShell session must be opened to the target Windows Server (ComputerAddress). This session must be declared using the ComputerSession parameter. See PowerShell Core for more information.

Path: 

In Windows, the path can be a drive letter or mount point separated by a comma without spaces. Valid path examples include: 

• 'p:\'
• 'p:\,e:\'
• 'c:\mp1,q:\,r:\'

Protection Group: Pgroupname, Createpgroup, Newpgroupsuffix, Usebestpgroupmatch, Nopgroup

• Nopgroup: 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.
• Usebestpgroupmatch: This should only be used when multiple protection groups include all of the declared volumes in the path and you prefer to have our algorithm 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 the snapshot consumption.
• Pgroupname:  This should be the steady state parameter used when invoking a snapshot.
• CreatePgroup & Newpgroupsuffix:  These parameters can be used to create a pgroup the first time invoke-psbsnapshotjob is run. This will create a pgroup with psb- as the prefix adding all volumes declared in the path parameter. Create a replication target, automatic snapshot generation, and retention policies in the FA UI or utilizing the PureStoragePowerShellSDK2.

VMName: 

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. VMware & Hyper-V VMs that utilize in-guest iSCSI or virtual FC HBAs are treated as physical servers with physical disk types.

VMPersistentID:

This is an optional parameter that will protect automation in the case that the friendly name of the VM in vCenter is changed. This is only used for virtual machines in a VMware environment using either pRDM or vVol disk types. VMware & Hyper-V VMs that utilize in-guest iSCSI or virtual FC HBAs are treated as physical servers with physical disk types.

ReplicateNow:

In the case of a protection group with a replication target, the replicatenow parameter will force the replication to occur immediately after snapshot creation. Otherwise replication will occur at the interval set in the protection group replication policy.

 

Troubleshooting

Most issues are due to a credential typo, or not having permissions to open a remote PowerShell session.

• Ensure PowerShell is run as Administrator.
• If you get an error about computer credentials, check if you can open a remote PowerShell session with the computer credential. One way to bind a credential to a secure variable is to use:  $compcred = get-credential

New-PSSession -Credential $compcred

Hyper-V

• Pass-through disks, where you add a disk and select a physical disk rather than a VHD/VHDX is not supported. Invoke-Psbsnapshotjob will work correctly, but the logic to connect a disk to a VM through the mount-psbsnapshotset does not exist and it will error as seen in the below image. If this is important to you, please request a request for enhancement (RFE) with your Pure AE/SE.
• In-guest iSCSI is indistinguishable from a bare metal server. Be sure to specify physical for the disk type.
• vHBA. Virtual Fibre Channel is a little more complicated to setup due to FC Switch configuration and zoning. Once configured it is indistinguishable from a bare metal server. Be sure to specify physical for the disk type.