VPGs: POST

May 2024 · 8 minute read
VPGs: POST

VPGs: POST

Creates a VPG or performs actions on a specific VPG.

URL

Create VPG

Deprecated

Insert a tagged checkpoint

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/Checkpoints

Clone VPG

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/CloneStart

Abort VPG clone

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/CloneAbort

Failover VPG

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/Failover

Commit VPG failover

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/FailoverCommit

Rollback VPG failover

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/FailoverRollback

Test VPG

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/failoverTest

Stop VPG test

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/failoverTestStop

Force synchronize a VPG

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/forcesync

Move VPG

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/move

Rollback Move VPG

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/moveRollback

Commit Move VPG

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/moveCommit

Pause VPG protection

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/pause

Resume VPG protection

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/resume

Where:

zvm_ip

The IP address of the Zerto Virtual Manager where the API is run.

port

The port to access the Zerto Virtual Manager. The default port is 9669.

protectionGroupIdentifier

The identifier of the VPG for which an action is executed, such as a clone, failover or failover test.

Request Body Using Json Format

The following is an example of a request body in Json format for https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/Checkpoints

{

  "checkpointName": "String content"

}

The following is an example of a request body in Json format for https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/CloneStart.

{

  "CheckpointId": "String content"

  "DatastoreIdentifier": "String content"

  "VmIdentifiers":

  [

    VmIdentifier": "string content"

  ]

}

The following is an example of a request body in Json format for https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/Failover.

{

  "CheckpointIdentifier": "String content",

  "CommitPolicy":1,

  "ShutdownPolicy":0,

  "TimeToWaitBeforeShutdownInSec":2147483647

  "IsReverseProtection": Boolean

  "VmIdentifiers":

  [

    VmIdentifier": "string content"

  ]

}

The following is an example of a request body in Json format for https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/FailoverCommit

{

  "IsReverseProtection": Boolean

}

The following is an example of a request body in Json format for https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/FailoverTest.

{

  "CheckpointIdentifier": "String content"

  "VmIdentifiers":

  [

    VmIdentifier": "string content"

  ]

}

The following is an example of a request body in Json format for https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/FailoverTestStop.

{

  "FailoverTestSuccess": Boolean,

  "FailoverTestSummary": "String content"

}

The following is an example of a request body in Json format for https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/move:

{

  "CommitPolicy": "String content",

  "CommitPolicyTimeout": 2,

  "ForceShutdown": Boolean,

  "ReverseProtection": Boolean,

  "KeepSourceVms": Boolean,

  "ContinueOnPreScriptFailure": Boolean

}

The following is an example of a request body in Json format for https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/moveCommit:

{

  "ReverseProtection": Boolean,

  "KeepSourceVms": Boolean

}

The request body for the following VPG POST APIs is empty:

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/FailoverRollback

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/failoverTest

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/failoverTestStop

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/forcesync

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/moveRollback

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/pause

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/resume

XML Request Format

For the XML request format, see VPGs API POST Method Request and Response Formats.

Request Values

Insert Checkpoint

Request values for https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/checkpoints

Parameter

Description

mandatory

default

CheckpointName

The name of the tagged checkpoint.

Yes

-

Note: It is not possible to insert a tagged checkpoint if the protected site is either Azure or AWS.

Clone a VPG

Request values for https://zvm_ip:port/v1/vpgs/{VpgIdentifier}/CloneStart.

Parameter

Description

mandatory

default

CheckpointId

The identifier of the checkpoint to use for cloning.

No

The latest checkpoint.

DatastoreIdentifier

The identifier of the datastore on which the cloned virtual machines are created. Specifying a datastore when the recovery site is vCD or Public cloud is not allowed.

No

The datastore (vSphere) or storage (Hyper-V) with the most free space.

VmIdentifiers

The name of the virtual machine/s selected for cloning.

No

Aborting a Clone

Request body for https://zvm_ip:port/v1/vpgs/{VpgIdentifier}/CloneAbort is empty.

Failover a VPG

Request values for https://zvm_ip:port/v1/vpgs/{VpgIdentifier}/failover.

Parameter

Description

Mandatory

default

CheckpointIdentifier

The identifier of the checkpoint to use for failover.

No

The latest checkpoint

CommitPolicy

The policy to use after the failover enters a Before Commit state. Possible values are (Json/XML):

Rollback or 0: After the seconds specified in the TimeToWaitBeforeShutdownInSec setting have elapsed, the failover is rolled back.

Commit or 1: After the seconds specified in the TimeToWaitBeforeShutdownInSec setting have elapsed, the failover continues, committing the virtual machines in the recovery site.

None or 2: The virtual machines in the VPG being failed over remain in the Before Commit state until either they are committed with Commit a failover, or rolled back with Roll back a failover.

No

Rollback

ShutdownPolicy

The shutdown policy to apply to the virtual machines on the protected site that are being failed over.

Possible values are (Json/XML):

0: The protected virtual machines are not touched before starting the failover. This assumes that you do not have access to the protected virtual machines.

1: If the protected virtual machines have VMware Tools or Microsoft Integration Services available, the virtual machines are gracefully shut down, otherwise the failover operation fails. This is similar to performing a Move operation to a specified checkpoint.

2: The protected virtual machines are forcibly shut down before starting the failover. If the protected virtual machines have VMware Tools or Microsoft Integration Services available, the procedure waits five minutes for the virtual machines to be gracefully shut down before forcibly powering them off. This is similar to performing a Move operation to a specified checkpoint.

No

TimeToWaitBeforeShutdownInSec

The amount of time in seconds the failover waits in a Before Commit state to enable checking that the failover is as required before performing the commit policy setting. The commit policy setting can either be commit or rollback.

No

IsReverseProtection

1 or True: Enable reverse protection. The virtual machines are recovered on the recovery site and then protected using the default reverse protection settings.

0 or False: Do not enable reverse protection. The VPG definition is kept with the status Needs Configuration and the reverse settings in the VPG definition are not set.

No

False

VmIdentifiers

The name of the virtual machine/s selected for failover.

No

Commit a failover

Request body for https://zvm_ip:port/v1/vpgs/{VpgIdentifier}/FailoverCommit.

Parameter

Description

mandatory

default

IsReverseProtection

1 or True: Enable reverse protection. The virtual machines are recovered on the recovery site and then protected using the default reverse protection settings.

0 or False: Do not enable reverse protection. The VPG definition is kept with the status Needs Configuration and the reverse settings in the VPG definition are not set.

No

False

Note: Attempting to commit a failover during the initial stage, before it is ready to commit or roll back, throws an exception.

Roll back a failover

Request body for https://zvm_ip:port/v1/vpgs/{VpgIdentifier}/FailoverRollback is empty.

Note: Attempting to rollback a failover during the initial stage, before it is ready to commit or roll back, throws an exception.

Test a failover

Request values for https://zvm_ip:port/v1/vpgs/{VpgIdentifier}/FailoverTest.

Parameter

Description

mandatory

default

checkpointId

Deprecated. See CheckpointIdentifier.

Irrelevant

CheckpointIdentifier

The identifier of the checkpoint to use for testing.

No

Latest checkpoint

VmIdentifiers

The name of the virtual machine/s selected for testing.

No

Stopping a failover test

Request values for https://zvm_ip:port/v1/vpgs/{VpgIdentifier}/FailoverTestStop.

Parameter

Description

mandatory

default

FailoverTestSuccess

True: The test was successful.

False: The test was not successful.

No

True

FailoverTestSummary

Free text describing the test.

No

N/A

Move VPG Operation

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/move:

Parameter

Description

mandatory

default

CommitPolicy

The policy to use after the move enters a Before Commit state. Possible values are (Json/XML):

Rollback or 0: The Move is rolled back after the seconds specified in the setting, commitPolicyTimeout, elapse.

Commit or 1: The Move resumes committing the virtual machines in the recovery site after the seconds specified in the setting, commitPolicyTimeout, elapse.

None or 2: The virtual machines in the VPG being moved remain in the Before Commit state until either they are committed with Commit a Move or rolled back with the Rollback a Move.

No

Site settings default commit policy

CommitPolicyTimeout

The amount of time, in seconds, the Move is in a "Before Commit" state, before performing the commitPolicy setting.

No

Site settings default commit policy.

ForceShutdown

0 or False: If a utility (VMware Tools) is installed on the protected virtual machines, the procedure waits five minutes for the virtual machines to be gracefully shut down before forcibly powering them off.

1 or True: To force a shutdown of the virtual machines.

No for Hyper-V and vSphere

Yes for Cloud Service Providers

False

ReverseProtection

0 or False: Do not enable reverse protection. The VPG definition is kept with the status Needs Configuration and the reverse settings in the VPG definition are not set.

1 or True: Enable reverse protection. The virtual machines are recovered on the recovery site and then protected using the default reverse protection settings.

Note: If ReverseProtection is set to True, the KeepSourceVMs should be ignored because the virtual disks of the VMs are used for replication and cannot have VMs attached.

No

True

KeepSourceVms

0 or False: Remove the protected virtual machines from the protected site.

1 or True: Prevent the protected virtual machines from being deleted in the protected site.

No

False

ContinueOnPreScriptFailure

0 or False: Do not continue the Move operation in case of failure of script executing prior the operation.

1 or True: Continue the Move operation in case of failure of script executing prior the operation.

No

False

Move Commit Operation

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/moveCommit:

Parameter

Description

mandatory

default

ReverseProtection

0 or False: Do not enable reverse protection. The VPG definition is kept with the status Needs Configuration and the reverse settings in the VPG definition are not set.

1 or True: Enable reverse protection. The virtual machines are recovered on the recovery site and then protected using the default reverse protection settings.

No

As set at "move" request

KeepSourceVms

0 or False: Remove virtual machines from the inventory.

1 or True: Prevent the protected virtual machines from being deleted in the protected site.

No

False

Force synchronize a VPG

Request body for https://zvm_ip:port/v1/vpgs/{VpgIdentifier}/forcesync is empty.

Pause VPG protection

Request body for https://zvm_ip:port/v1/vpgs/{VpgIdentifier}/pause is empty.

Resume VPG protection

Request body for https://zvm_ip:port/v1/vpgs/{VpgIdentifier}/resume is empty.

Response In Json Format

The following is an example response Json body for:

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/checkpoints,

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/Failover, https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/FailoverCommit, https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/FailoverRollback, https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/FailoverTest, https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/FailoverTestStop, https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/forcesync,

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/move,

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/moveCommit,

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/moveRollback,

https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/pause, and for https://zvm_ip:port/v1/vpgs/{protectionGroupIdentifier}/resume.

{

  "TaskIdentifier": "String content"

}

Response Values

Parameter

Description

TaskIdentifier

The identifier of the task. The task identifier can be used with the Tasks API to monitor the action.

XML Response Format

For the XML response format, see VPGs API POST Method Request and Response Formats.

Response Values

Parameter

Description

TaskIdentifier

The identifier of the task. The task identifier can be used with the Tasks API to monitor the action.

ncG1vJloZqxrXpa6osbOp5iwq16YvK572Z6praeUpMSvuM6am5icn5jAcIONbpaFmaSawLV7uZ6pradVZ32XtdGtrJqkVWd9k7HPpaCcmaSevK9xkWmJfouEWn9xja%2BCql5qYIS7rbXNnlxraHiaubF7uZ6praePi7azwNSao5iKlaW5qq%2FAraCopo%2BHkpSgvnqHgqtfiMGiwNSseImBo2OCb32PcWWhrJ2h