diff --git a/RELEASENOTES.md b/RELEASENOTES.md index 0cddecd..88b7fb5 100644 --- a/RELEASENOTES.md +++ b/RELEASENOTES.md @@ -4,7 +4,8 @@ * [Zerto version 7.5 has been released.](https://s3.amazonaws.com/zertodownload_docs/Latest/Zerto%20Virtual%20Replication%20Release%20Notes.pdf) As part of this release Zerto has added API functionality that requires the following updates. * A token is now required to pair two sites together. The need is discussed in [Issue 46](https://github.com/ZertoPublic/ZertoApiWrapper/issues/46). To implement this change a `-token` parameter has been added to the `Add-ZertoPeerSite` function. - * A new function has been added; `New-ZertoPairingToken`. This function will allow users to generate a pairing authentication token from the target ZVM to be used in the pairing process. [Issue 47](https://github.com/ZertoPublic/ZertoApiWrapper/issues) covers additional details. + * A new function has been added; `New-ZertoPairingToken`. This function will allow users to generate a pairing authentication token from the target ZVM to be used in the pairing process. [Issue 47](https://github.com/ZertoPublic/ZertoApiWrapper/issues/47) covers additional details. + * A new function has been added; `Invoke-ZertoEvacuateVra`. This function will allow users to evacuate a target VRA by specifying a Host Name, VRA Name, or VRA Identifier. All VMs currently replicating to the specified location will be migrated to different targets. [Issue 51](https://github.com/ZertoPublic/ZertoApiWrapper/issues/51) ### Zerto Analytics diff --git a/Tests/Public/Invoke-ZertoEvacuateVra.Tests.ps1 b/Tests/Public/Invoke-ZertoEvacuateVra.Tests.ps1 new file mode 100644 index 0000000..47629c7 --- /dev/null +++ b/Tests/Public/Invoke-ZertoEvacuateVra.Tests.ps1 @@ -0,0 +1,54 @@ +#Requires -Modules Pester +$global:here = (Split-Path -Parent $MyInvocation.MyCommand.Path) +$global:function = ((Split-Path -leaf $MyInvocation.MyCommand.Path).Split('.'))[0] + +Describe $global:function -Tag 'Unit', 'Source', 'Built' { + + Context "$global:function::Parameter Unit Tests" { + It "$global:function should have exactly 16 parameters defined" { + (Get-Command $global:function).Parameters.Count | Should -Be 16 + } + + $ParameterTestCases = @( + @{ParameterName = 'hostName'; Type = 'String'; Mandatory = $true; Validation = 'NotNullOrEmpty'; ParameterSet = @('hostName') } + @{ParameterName = 'vraName'; Type = 'String'; Mandatory = $true; Validation = 'NotNullOrEmpty' ; ParameterSet = @('vraName') } + @{ParameterName = 'vraIdentifier'; Type = 'String'; Mandatory = $true; Validation = 'NotNullOrEmpty' ; ParameterSet = @('vraIdentifier') } + ) + + It " parameter is of type" -TestCases $ParameterTestCases { + param($ParameterName, $Type, $Mandatory, $Validation) + Get-Command $global:function | Should -HaveParameter $ParameterName -Mandatory:$Mandatory -Type $Type + } + + It " parameter has correct validation setting" -TestCases $ParameterTestCases { + param($ParameterName, $Validation) + Switch ($Validation) { + 'NotNullOrEmpty' { + $attrs = (Get-Command $global:function).Parameters[$ParameterName].Attributes + $attrs.Where{ $_ -is [ValidateNotNullOrEmpty] }.Count | Should -Be 1 + } + + $null { + $attrs = (Get-Command $global:function).Parameters[$ParameterName].Attributes + $attrs.TypeId.Count | Should -Be 2 + } + } + } + + It " parameter is part of the correct ParameterSet(s)" -TestCases $ParameterTestCases { + param($ParameterName, $ParameterSet) + $commandParameterSets = (Get-Command $global:function).Parameters[$ParameterName].ParameterSets + foreach ($Set in $ParameterSet) { + $commandParameterSets.ContainsKey($Set) | Should -BeTrue + } + $commandParameterSets.Count | Should -Be $ParameterSet.Count + } + } + + Context "$global:function::Parameter Functional Tests" { + + } +} + +Remove-Variable -Name here -Scope Global +Remove-Variable -Name function -Scope Global diff --git a/ZertoApiWrapper/Public/Invoke-ZertoEvacuateVra.ps1 b/ZertoApiWrapper/Public/Invoke-ZertoEvacuateVra.ps1 new file mode 100644 index 0000000..d01ae9e --- /dev/null +++ b/ZertoApiWrapper/Public/Invoke-ZertoEvacuateVra.ps1 @@ -0,0 +1,62 @@ +<# .ExternalHelp ./en-us/ZertoApiWrapper-help.xml #> +function Invoke-ZertoEvacuateVra { + [CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = "VraIdentifier")] + param ( + # HostName Option + [Parameter( + Mandatory, + HelpMessage = "Name of the Host to Evacuate", + ParameterSetName = "HostName" + )] + [ValidateNotNullOrEmpty()] + [String]$HostName, + # VRA Option + [Parameter( + Mandatory, + HelpMessage = "Name of the VRA to Evacuate", + ParameterSetName = "VraName" + )] + [ValidateNotNullOrEmpty()] + [String]$VraName, + # VRAIdentifier Option + [Parameter( + Mandatory, + HelpMessage = "Identifier of the VRA to be evacuated", + ParameterSetName = "VraIdentifier", + ValueFromPipelineByPropertyName, + ValueFromPipeline + )] + [Alias("VraId", "Identifier")] + [ValidateNotNullOrEmpty()] + [String]$VraIdentifier + ) + + begin { + + } + + process { + switch ($PSCmdlet.ParameterSetName) { + "HostName" { + $VraName = "Z-VRA-" + $HostName + Invoke-ZertoEvacuateVra -VraName $VraName + } + + "VraName" { + $VraIdentifier = (Get-ZertoVra -vraName $VraName).VraIdentifier + Invoke-ZertoEvacuateVra -VraIdentifier $VraIdentifier + } + + "VraIdentifier" { + $Uri = "vras/{0}/changerecoveryvra/execute" -f $VraIdentifier + if ($PSCmdlet.ShouldProcess($VraIdentifier, "Evacuating VRA with Identifier:")) { + Invoke-ZertoRestRequest -Uri $Uri -Method "POST" + } + } + } + } + + end { + + } +} diff --git a/docs/Invoke-ZertoEvacuateVra.md b/docs/Invoke-ZertoEvacuateVra.md new file mode 100644 index 0000000..bea1ad3 --- /dev/null +++ b/docs/Invoke-ZertoEvacuateVra.md @@ -0,0 +1,147 @@ +--- +external help file: ZertoApiWrapper-help.xml +Module Name: ZertoApiWrapper +online version: https://github.com/ZertoPublic/ZertoApiWrapper/blob/master/docs/Invoke-ZertoEvacuateVra.md +schema: 2.0.0 +--- + +# Invoke-ZertoEvacuateVra + +## SYNOPSIS +This operation will move all VMs currently replicating to the selected host or VRA to different hosts based on internal Zerto algorithms. + +## SYNTAX + +### VraIdentifier (Default) +``` +Invoke-ZertoEvacuateVra -VraIdentifier [-WhatIf] [-Confirm] [] +``` + +### HostName +``` +Invoke-ZertoEvacuateVra -HostName [-WhatIf] [-Confirm] [] +``` + +### VraName +``` +Invoke-ZertoEvacuateVra -VraName [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +This operation will move all VMs currently replicating to the selected host or VRA to different hosts based on internal Zerto algorithms. + +This will return a Zerto Task Identifier so the task progress can be tracked. + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> Invoke-ZertoEvacuateVra -HostName 'host01' +``` + +Will move all VMs currently replicating to the selected host to different hosts. + +### Example 2 +```powershell +PS C:\> Invoke-ZertoEvacuateVra -VraName 'Z-VRA-host01' +``` + +Will move all VMs currently replicating to the selected VRA to different VRAs. + +### Example 3 +```powershell +PS C:\> Invoke-ZertoEvacuateVra -VraIdentifier '1234-1234-4312-9856' +``` + +Will move all VMs currently replicating to the selected VRA to different VRAs. + +## PARAMETERS + +### -HostName +HostName Option + +```yaml +Type: String +Parameter Sets: HostName +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VraIdentifier +VRAIdentifier Option + +```yaml +Type: String +Parameter Sets: VraIdentifier +Aliases: VraId, Identifier + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -VraName +VRA Option + +```yaml +Type: String +Parameter Sets: VraName +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS +[Zerto REST API Evacuate VRA End Point Documentation](http://s3.amazonaws.com/zertodownload_docs/Latest/Zerto%20Virtual%20Replication%20Zerto%20Virtual%20Manager%20%28ZVM%29%20-%20vSphere%20Online%20Help/index.html#page/RestfulAPIs%2FStatusAPIs.5.129.html%23) +