PureStorage.FlashArray.Backup PowerShell Module
- Introduction
- Installing the Backup Module
- How It Works
- VMware UUID
- Create a Volume Set
- Invoke a Snapshot
- Mount a Snapshot
- Dismount a Snapshot
- List Available Drive Letters
- List the Snapshot Job History
- List the Snapshot Set Mount History
- List Virtual Machine Persistent IDs
- List the Volume Set(s)
- List Protection Groups that Contain the Volumes in a Volume Set
- Remove a Snapshot
- Remove a Volume Set
- Backup Module and SQL Server 2022's Transact-SQL Snapshot Backup Feature
- Parameter Reference
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 |
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 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 |
The name (DNS or Fully Qualified Domain Name) or IP address of a Pure Storage FlashArray. | |
FlashArrayCredential |
Dismount-PsbSnapshotSet |
The credentials for a Pure Storage FlashArray passed in through a variable. | |
HistoryID |
Mount-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 |
|
The path can be a drive letter or mount point separated by a comma without spaces. Valid path examples:
|
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 |
(VMware only) The name (DNS or Fully Qualified Domain Name) or IP address of a VMware vCenter Server. | |
VCenterCredential |
Dismount-PsbSnapshotSet |
(VMware only) The credentials for the VMware vCenter server passed in through a variable. | |
VmName |
Get-PSBVMPersistentId |
(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 |
(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 |
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 |
Physical RDM vVol |
|