zertopublic / zertoapiwrapper

PowerShell wrapper for Zerto Virtual Manager API

ZertoApiWrapper

PowerShell wrapper for Zerto Virtual Manager API

Current Build Status

Legal Disclaimer

This script is an example script and is not supported under any Zerto support program or service. The author and Zerto further disclaim all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose.

In no event shall Zerto, its authors or anyone else involved in the creation, production or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or the inability to use the sample scripts or documentation, even if the author or Zerto has been advised of the possibility of such damages. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you.

Disclaimer

This code is still under development! Please use carefully and if you encounter any issues or have an idea, please submit an issue. Along the same lines, should you be proficient in PowerShell, please feel free to submit any Pull Requests with enhancements and bug fixes.

Installing the Module

This module can be installed directly from the PowerShell Gallery with the following command.

PS> Install-Module -name ZertoApiWrapper

Getting Started

• Getting Started with Zerto Virtual Manager and the ZertoApiWrapper
• Getting Started with Zerto Analytics and the ZertoApiWrapper

Recent Updates

All recent updates can now be tracked via the Change Log.

TODO

• Support ZVM appliance (different connection flow)
• JFLR Functionality
• Create VPG (Per-VM modification and Backup Settings)
• Edit VPG
• Delete Zerto License
• Flesh out Pester Tests
• Complete Automated Build Process

zertoapiwrapper's Issues

Allow Auto-Reauthentication for ZVM

Connect-ZertoServer should allow for auto reauthentication in the event of an expired session token.

Copy-ZertoVPG internal server error

PS C:\Users\Administrator> Copy-ZertoVpg -SourceVpgName xx -NewVpgName xy -VMs xy

Invoke-ZertoRestRequest : The remote server returned an error: (500) Internal Server Error.
At C:\Program Files\WindowsPowerShell\Modules\ZertoApiWrapper\1.5.3\ZertoApiWrapper.psm1:6035 char:13

•         Invoke-ZertoRestRequest -uri $baseUri -method "POST"
  

•         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Write-Error], WebException
  • FullyQualifiedErrorId : WebCmdletWebResponseException,Invoke-ZertoRestRequest

Expected Behavior

i have a second vm like the first one, only the vm is different. i was expecting a new vpg with one vm and the same settings

Current Behavior

nothing happening

Possible Solution

Steps to Reproduce (for bugs)

Connect-ZertoServer (working)
get-zertovpg (working)
Copy-ZertoVpg -SourceVpgName xx -NewVpgName xy -VMs xy4.

Your Environment

• Module version used: 1.5.3
• Operating System and PowerShell version: windows 2019 1809, 5.1.17763.1490
• Zerto Virtual Manager Version: 8.5 U2

Get-vavpg - Does not return all VPG's

According to the documentation, get-zavpg without any parameters is supposed to turn all VPGs but it does not. In fact, it returns a random VPG. Also, when I add -zorgidentifier with a proper org id, I get the same result (some random VPG). On the plus side, if I enter a correct vpgidentifier that does in fact work.

I tried my best to replicate the behavior on the api doc site and it works there.

Linux ZVM support

Does this repo support the Linux ZVM APIs?

If not, are there plans to add this support?

Thanks
Bill

Set-ZertoLicense - Fix ShouldProcess error

As discussed, ShouldProcess needs more than 0 arguments.

Need a method to Set \ Modify VPG Parameters

Need a method to setup non-default settings for a VPG both when creating a VPG as well as any time a VPG needs to be modified after creation.

ChangeVRA cmdlet

Excellent toolset!

Either I am missing it, or there is not an option to perform a change vra cmdlet?

Its not an evacuation of a host, just the ability to perform the change vra recovery host.

Attempting to write a balancing script.

Thanks

Get-ZertoRecoveryReport failing to pass vpgName and vpgIdentifier parameters correctly

Expected Behavior

Get-ZertoRecoveryReport returns data scoped to the VPG passed via the vpgName or vpgIdentifier parameters. It also is not accepting pipeline input.

Current Behavior

Get-ZertoRecoveryReport fails to return data using the -vpgName parameter or returns unfiltered data when using the -vpgIdentifier parameter.

Steps to Reproduce (for bugs)

After a successful 'Connect-ZertoServer':

PS C:\> Get-ZertoRecoveryReport -vpgName "VPG_Name" -Verbose
VERBOSE: GET https://ZertoServer:9669/v1/reports/recovery?vpgName=VPG_Name with 0-byte payload
VERBOSE: received 2-byte response of content type application/json; charset=utf-8

Running Get-ZertoRecoveryReport with the -vpgIdentifier parameter does not appear to filter the results at all

PS C:\> $reports1 = Get-ZertoRecoveryReport -vpgIdentifier "vpgID"
PS C:\> $reports2 = Get-ZertoRecoveryReport
PS C:\> $reports1.count
169
PS C:\> $reports2.count
169

Context

We would like to be able to use this data to report on failover testing and recovery operations.

Your Environment

Module version: 1.3.0.20191201
Operating System and PowerShell version: Windows 2016 with PS 5 and 6, also Windows 10 with PS 5, 6 and 7
Zerto Virtual Manager Version: 7.5U1

Add-ZertoPeerSite - Error using hostname

Expected Behavior

When using the Add-ZertoPeerSite module, I'm attempting to use the -targetHost parameter with a hostname instead of an IP address

Current Behavior

Receiving the following error: Add-ZertoPeerSite: Cannot validate argument on parameter 'targetHost'. Cannot convert value "hostname" to type "System.Net.IPAddress". Error: "An invalid IP address was specified."

Possible Solution

Line 9 appears to look for an IP Address match. This should also look for hostname input.

Steps to Reproduce (for bugs)

Use a hostname for the -targetHost parameter when executing the Add-ZertoPeerSite module.

Context

Had to modify my scripts to use IP addresses only instead of hostnames.

Your Environment

• Module version used: 1.4.3
• Operating System and PowerShell version: Windows 10, PowerShell 7.0.3
• Zerto Virtual Manager Version: 8.0 U2

General authorization error

I am using the default self signed certificate that comes with Zerto. Ran the connect-zertoserver -zertoserver -credential (Get-credential) and it succeeds but then any command that I run afterwards I get the following error.

Invoke-RestMethod : {"errorCode":50,"errorMessage":"General authorization error"}
At C:\Program Files\WindowsPowerShell\Modules\ZertoApiWrapper\1.1.0.34\ZertoApiWrapper.psm1:45 char:13

What is the best way to resolve.

Thanks

Remove-ZertoVpgVm not working as expected

Right now Remove-ZertoVpgVm is not working for me. When I run a command such as

Remove-ZertoVpgVm -VpgName 'test-vpg' -Vm 'test-vm'

I get the following error.

Method invocation failed because [System.Management.Automation.PSCustomObject] does not contain a method named 'Where'.
At C:\Program Files\WindowsPowerShell\Modules\ZertoApiWrapper\1.5.3\ZertoApiWrapper.psm1:5955 char:17
+ ...             $protectedVms.Where( { $_.VmName -like $machine }) | Sele ...
+                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (Where:String) [], RuntimeException
    + FullyQualifiedErrorId : MethodNotFound
 
WARNING: No VMs found to remove. Please check your parameters and try again.

To fix this I had to adjust Remove-ZertoVpgVm.ps1 line 33

From
$protectedVms.Where( { $_.VmName -like $machine }) | Select-Object -ExpandProperty VmIdentifier

To

$protectedVms | Where-Object ( { $_.VmName -like $machine }) | Select-Object -ExpandProperty VmIdentifier

I don't know enough to explain why this fixes the issue I just figured it out by messing around with the code.

New-ZertoVpg does not support ShouldProcess

New-ZertoVpg does not support ShouldProcess. This should be corrected.

Usage question

First, thanks so much for creating this. I’m never not amazed by all the hard work people put into these projects.

I have a question:

I’m sure I’m just being dumb, but I don’t see how to edit a vpg’s settings. I can create a vpg settings identifier, and get information about the settings of the vpg from that, but I don’t understand how to modify them.

If you could point me in the right direction, that would awesome.

Start-ZertoFailoverTest errors with empty $body

Expected Behavior

A ZertoFailoverTest begins.

Current Behavior

After using 'Connect-ZertoServer' I am able to run other functions, but cannot start a failover test. Specifying vpgName and/or vmName all results in failure.

Running 'Get-ZertoVpg -vpgName name' or 'Get-ZertoProtectedVm -vmName name' both succeed, while 'Start-ZertoFailoverTest -vpgName name' fails.

Steps to Reproduce (for bugs)

After a successful 'Connect-ZertoServer':

PS H:> Start-ZertoFailoverTest -vpgName "VPG_name"
Invoke-ZertoRestRequest : Cannot validate argument on parameter 'body'. The argument is null or empty. Provide an
argument that is not null or empty, and then try the command again.
At C:\Program Files\WindowsPowerShell\Modules\ZertoApiWrapper\1.2.0.20190801\ZertoApiWrapper.psm1:5304 char:68

• ... oRestRequest -uri $uri -method "POST" -body $($body | ConvertTo-Json)

•                                             ~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : InvalidData: (:) [Invoke-ZertoRestRequest], ParameterBindingValidationException
  • FullyQualifiedErrorId : ParameterArgumentValidationError,Invoke-ZertoRestRequest

Context

We would like to use this function to automate failover testing.

Your Environment

• Module version used: 1.2.0.20190801
• Operating System and PowerShell version: Windows 2016 with PS 5 and 6, also Mac 10.14 with PS 6 and 7
• Zerto Virtual Manager Version: 7.5U1

Implement JFLR Functionality

Need to implement JFLR functionality

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.028.html%23

Modify Add-ZertoPeerSite function to allow the use of a pairing token.

Expected Behavior

Per the pairing functionality update, to leverage the API and pair two 7.5 sites together, you now need to issue a token generated by the site you are pairing to. The current implementation does not allow for a token to be passed.

Current Behavior

No parameter to pass the token.

Possible Solution

Update the Add-ZertoPeerSite function to accept a token.

Steps to Reproduce (for bugs)

N\A

Context

Need to be able to pair two sites together.

Your Environment

• Module version used: Latest
• Operating System and PowerShell version: Windows powershell core 6.2
• Zerto Virtual Manager Version: 7.5

404 Error Returned when Searching for a Zerto Analytics VPG

Expected Behavior

Should return information about the VPG specified

Current Behavior

Returns a 404 error

Possible Solution

Fix the URI build process to correctly use the right API endpoint.

Steps to Reproduce (for bugs)

1. Get-ZAVpg -vpgIdentifier "MyVpgIdentifier"

Context

Your Environment

• Module version used: 1.1.0.34
• Operating System and PowerShell version: 6.2.2
• Zerto Virtual Manager Version: N\A - Zerto Analytics

Update ZertoAnalytics Auth Token Checks

TODO: Update Zerto Analytics Rest Request to check and ensure the token exists before attempting to execute and throw an error if it does not.

Originally posted by @wcarroll in #35 (comment)

Unable to Export Nic Settings

Expected Behavior

Run the Export-ZertoVmNicSetting against a single or all VPGs to export settings into a csv file which can then be edited for import.

Current Behavior

When running the command, I am receiving an array index error as per below:

PS C:\Users\dbarkho> Export-ZertoVmNicSetting -VpgName "DanTest" -OutputFile E:\temp\export.csv
Index operation failed; the array index evaluated to null.
At C:\Program Files\WindowsPowerShell\Modules\ZertoApiWrapper\1.3.0.20191201\ZertoApiWrapper.psm1:597 char:53

• ... VMName = $vmMap[$($vm.vmIdentifier)]

•                                                    ~~~~~~~~~~~~~~~~
  

  • CategoryInfo : InvalidOperation: (:) [], RuntimeException
  • FullyQualifiedErrorId : NullArrayIndex

Export-Csv : Cannot bind argument to parameter 'InputObject' because it is null.
At C:\Program Files\WindowsPowerShell\Modules\ZertoApiWrapper\1.3.0.20191201\ZertoApiWrapper.psm1:621 char:24

•     $nicSettings | Export-Csv -Path $OutputFile
  

•                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : InvalidData: (:) [Export-Csv], ParameterBindingValidationException
  • FullyQualifiedErrorId : ParameterArgumentValidationErrorNullNotAllowed,Microsoft.PowerShell.Commands.ExportCsvCommand

Possible Solution

Steps to Reproduce (for bugs)

1. Connect to the ZVM: Connect-ZertoServer -zertoServer ""
2. Run the Nic export comand: Export-ZertoVmNicSetting -VpgName "DanTest" -OutputFile E:\temp\export.csv

The above error is then received. I have tried against a single or all VPGs, but no luck unfortunately.

Context

Your Environment

• Module version used: 1.3.0.20191201
• Operating System and PowerShell version: Windows server 2k16, PS 5.1
• Zerto Virtual Manager Version: 7.0U1

Bulk VM NIC Settings Update Fucntionality

Expected Behavior

This module should provide a method to bulk import changes to protected virtual machine live and test NIC settings. To accomplish this goal, it would also be necessary to export current settings.

Current Behavior

The export process can be completed with the module as is, but requires additional lines of code to translate all of the identifiers to user friendly names along with logic to only export the data into a friendly format. The import process is similar, but requires a invocation of a API call outside of the module. This should be built in to the process.

Possible Solution

Add functions to Export and Import this data.

Context

Manually updating this information in bulk is time consuming and error prone.

New-ZertoVpg sets journal to unlimited

New-ZertoVpg does not set default journal limits. This should be addressed to ensure normal default GUI workflow limits are set.

Missing Legal Disclaimer

The README.md file does not contain the required legal disclaimer section.

New-ZertoVPG does not work when replicating to same site

New-ZertoVPG does not work when replicating to same site

Expected Behavior

New VPG is created

Current Behavior

Error because Get-ZertoPeerSite does not show local Site/has as an option for local site

Possible Solution

Adjust Get-ZertoPeerSite to include local site
Add option to New-ZertoVPG to use local site

Steps to Reproduce (for bugs)

Create new VPG with a target to another cluster in the same site

Context

Had to create VPG manually and use Copy-ZertoVPG for subsequent VPGs

Your Environment

• Module version used: 1.5.1
• Operating System and PowerShell version: Windows Server 2019 PS PS5.1
• Zerto Virtual Manager Version: 8.0U2

Implement Copy Vpg Settings Function

Expected Behavior

New function to clone a VPG and specify different VMs with all the same settings as an existing VPG. This has been introduced with Zerto 7.5 along with an API endpoint and needs to be added to the Wrapper

Current Behavior

Function does not exist, needs to be added.

Possible Solution

Create the new function

Context

This has been introduced with Zerto 7.5 along with an API endpoint and needs to be added to the Wrapper

Missing Legal Disclaimer

The README.md file does not contain the required legal disclaimer section.
Please ensure that the repository includes an appropriate legal disclaimer.

New VPG error when targeting single host for recovery

Expected Behavior

VPG to be created when a single recovery host is specified.

Current Behavior

Error is thrown when a single recovery is specified.

Possible Solution

After debugging, it seems that the statement to assign the recovery host identifier is using the incorrect key.

Steps to Reproduce (for bugs)

1. Input a single recovery host with using the New-ZertoVPG function with -recoveryHost parameter.
2. Attempt to save the VPG and error is thrown.

Context

Attempting to create VPG through PowerShell API

Your Environment

• Module version used: 1.5.0
• Operating System and PowerShell version: Windows 10, PowerShell 7
• Zerto Virtual Manager Version: 8.0

Connect-ZertoServer throws error when target ZVM is unlicensed.

As discussed, need to find workaround for initialization of Get-ZertoLocalSite.

Invoke-ZertoRestRequest: C:\PowerShell\Modules\ZertoApiWrapper\1.4.1\ZertoApiWrapper.psm1:2539:5
Line |
2539 |      Invoke-ZertoRestRequest -uri $uri
     |      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"Message":"Valid License is not provided "}

Missing Legal Disclaimer

The README.md file does not contain the required legal disclaimer section.

Implement logic if commitPolicyTimeout is Set, commitPolicy is Mandatory.

ZertoApiWrapper/ZertoApiWrapper/Public/Invoke-ZertoMove.ps1

Line 24 in 73540fa

[Int]$commitPolicyTimeout,

Save-ZertoVpgSetting -vpgSettingsIdentifier $vsetid

Zerto error (displayed in gui) when attempting to change the urn value in [vpgsettings.vms.recovery.vcd.storageProfile] via Save-ZertoVpgSetting.

Expected Behavior

Execution of the Save-ZertoVPG Setting returns a value e.g. "d1ff1e2c-2e84-41e8-9f93-e56e1dcfde4f.6791dec1-9e73-4d6f-bf87-121e624390b2" and a new task appears in ZVM gui.

Expected result is to see updated storage profile name when I open the vpg for edit in ZVM gui.

Current Behavior

The following Task error is displayed in the ZVM gui.

"The following properties are irrelevant when replicating from vCD to vCD. Remove these accordingly: Name: JournalDatastore; Location: ProtectionGroupManagementSettings.VMsManagementSettings.0.VMSettings"

Steps to Reproduce (for bugs)

Steps:
1.getZertoVpg identifier for specific VPG with get-zertovpg (filter)
2.Create vpgsettings identifier with new-zertovpgsettingsidentifer ($vsetid = ...)
3.get-vpgsettings for the above vpgsettingsid ($vpgsettings = ...)
4.change storageprofile urn value in $vpgsettings.vms.recovery.vcd.storageProfile
5. Save-Save-ZertoVpgSetting -vpgSettingsIdentifier $vsetid

Context

Cloud provider migrating to a new storage platform with a unique storage profile. Adding the new storage profile to each Zerto customer's VDC.

Your Environment

Environment Notes:
VCD to VCD (10.1.2)
ZertoApiwrapper Ver: 1.5.3
Zerto 8.0U4 to Zerto 8.0U4
Powershell: 5.1.18362.145

start-zertoclonevpg

start-zertoclonevpg

Is there a way to call multiple VPG's using this function? I have tried a few different options, like comma, brackets, quotes, etc. I figured maybe I would have to build an array and modify the ps1 to accept the array. Before I went thru that, I figured I would ask and make sure I am not calling them correctly.

Mike

Multiple parameters will fail if more then one Managed-Object with the provided name exists

Currently the fact that you can have multiple objects in vCenter with the same name on different levels of the vCenter inventory is not respected. Commands will fail if more then a single object with the used name exists.

E.g., let's take a look at the New-ZertoVpg commandlet.
When multiple clusters with multiple distributed switches exist, portgroups can have the same name across all those switches.
Currently when providing the -recoveryNetwork or -testNetwork parameter to the commandlet it will then use this code to find the matching network by name:

$identifiersTable['failoverNetworkIdentifier'] = $peerSiteNetworks | Where-Object { $_.VirtualizationNetworkName -like $recoveryNetwork } | Select-Object -ExpandProperty NetworkIdentifier

If more then one network exists the Zerto API will attach the VDS name to the network name, e.g.: if a network my_test_network exists in a VDS named vds_a and vds_b then the Zerto API will return my_test_network (vds_a) and my_test_network (vds_b) for the VirtualizationNetworkName property.
Thus in such cases the compare operation using -like will return no result and the commandlet will fail with an error like failoverNetworkIdentifier is not associated with a valid identifier. Please check the submitted values and try again.

While this example of the issue was specific for networks it exists for other objects as well, e.g. folder names.
The wrapper should handle such cases. E.g. if no exact match for my_test_network exists but multiple results for my_test_network* exist then a propper exception should be raised at very least.

In some cases it would probably be possible to handle this in an automated manner. E.g. the target cluster is known and the network is unique within the cluster, then it's clear what network the user desires to use.

New-ZertoVPG - VMs not passed as arrary in powershell 5.1

Expected Behavior

The Zerto REST API for the VPG Settings expect VPG member VMs to be passed as an array even if there is only a single VM being passed.

Current Behavior

When a single VM is used, the API throws an error stating that it should be an array and cannot be parsed.

Possible Solution

Update the logic in the function to specify an array.

Steps to Reproduce (for bugs)

1. Use New-ZertoVpg and specify only a single VM using powershell 5.1

Context

Cannot create single VM VPGs

Your Environment

• Module version used: 1.1.0.34
• Operating System and PowerShell version: Windows 10, PSVersion 5.1
• Zerto Virtual Manager Version: 7.0U2

Change PeerSiteName filter to case-insensitive

The ZVM API peer site filter for peer name is case sensitive. With PowerShell case sensitivity should not be an issue. Should update New-ZertoVpg to get all the peer sites, then filter the data locally.

New function to get authentication token required

Expected Behavior

With the new requirement for an authentication token, we now require a function to generate that token. Per this documentation.

Current Behavior

Does not exist.

Possible Solution

Create a new function and required tests.

Steps to Reproduce (for bugs)

N\A

Context

Cannot pair sites without a token and need a method to generate a token

Your Environment

N\A

New-ZertoVpg does not validate settings submitted are valid

New-ZertoVpg should validate the settings are valid and not empty.

New-ZertoVpg max journal size too small

Max value of a 32 bit signed int is not large enough to handle larger journal settings when provided in MB. Even a 32 bit unsigned int would only provide for about 4 TB. To fix this, these parameters should be changed from 32 bit signed ints to 64 bit unsigned ints. This will also ensure that only positive values are supplied.

Implement Evacuate VRA Functionality

Expected Behavior

You should be able to make a call and have any VMs currently replicating to a location be migrated to a different target.

Current Behavior

Does not exist.

Possible Solution

Create a function to leverage the new Evacuate VRA endpoint in the ZVM API.

Context

Automatically evacuate target VRAs.

Add default parameter set to New-ZertoVpg

New-ZertoVpg should have a default parameter set to guide the customer through the VPG setup process.

Will assign 'recoveryHostDatastore' parameter set as this is minimum required infrastructure to get Zerto to replicate.

Create VPG Workflow

Need to be able to utilize the module to create a VPG.

Parameters with limited inputs should use ValidateSet param settings

To help with setting validation, parameters that only accept certain non-boolean values should use the [ValidateSet()] parameter attribute or Enums

This needs to be implemented in a multitude of functions, including but not limited to:

• Get-ZertoEvent
• Get-ZertoRecoveryReport
• Get-ZertoTask
• Get-ZertoVolume
• Get-ZertoVpg
• Invoke-ZertoFailover
• Invoke-ZertoMove
• New-ZertoVpg

Remove-ZertoPeerSite is Missing

Missing functionality being able to programmatically unpair a site.

Add CPU param to Install-ZertoVra

Need a param for rolling out VRAs with multiple CPUs

Expected Behavior

1 is default and up to 4 is possible.

Current Behavior

No param

Possible Solution

Add a param

Steps to Reproduce (for bugs)

1. get-help install-zertovra(no param)

Context

We have prevously used the GUI to use Cluster settings and it will roll out with multple

Your Environment

• Module version used:
• Operating System and PowerShell version:
• Zerto Virtual Manager Version:

Missing Legal Disclaimer

The README.md file does not contain the required legal disclaimer section.
Please ensure that the repository includes an appropriate legal disclaimer.

Remove-ZertoVpg should be updated to process multiple VPGs

Remove-ZertoVpg currently only processes one virtual protection group. It should be modified to take an array of VPG names and remove each of them.