Managing VPGs
The Zerto RESTful APIs includes an API that enables you to manage the creation and editing of VPGs programmatically.
The following topics are described in this section:
• | An Introduction to the vpgSettings API |
• | How Does the vpgSettings API Work |
• | Using the APIs |
• | Short Outlines of How to Manage a VPG |
• | A First Time Tutorial Using the vpgSettings API |
• | Getting Help for an API |
An Introduction to the vpgSettings API
You can manage VPGs using both the /v1/vpgs API or the /v1/vpgSettings API. Use the /v1/vpgs API to perform actions on a VPG, such as failing over a VPG, cloning a VPG or testing a VPG. Use the /v1/vpgSettings API to manage the definition of a VPG, including editing the VPG definition and adding or removing virtual machines from a VPG.
Use the vpgSettings API to do the following:
• | Create a new VPG. |
• | Display values in an existing VPG. |
• | Edit existing values in a VPG. |
What is Supported
The vpgSettings API works in the following environments:
• | vCenter Server |
• | Hyper-V |
• | vCenter Server to Hyper-V and Hyper-V to vCenter Server |
• | vCloud Director to vCloud Director |
• | vCenter Server to vCloud Director |
• | vCenter Server to Azure |
• | Running on the protected site |
• | Running on the recovery site |
• | Preseeding |
• | Virtual machines with RDM disks |
What is Not Supported
The vpgSettings API does not support the following:
• | AWS |
How Does the vpgSettings API Work
The definition of a VPG can be described by the set of values. The vpgSettings API enables managing this set of values. All the VPG settings are managed in a VPG settings object, which is saved in memory. This object is managed during a session and used to either create a VPG or update an existing VPG.
Managing a VPG using the vpgSettings API involves the following steps:
1. | Create a VPG settings object. |
2. | Manipulate the VPG settings object to include the values you want. |
3. | Commit the VPG settings object to update the VPG definition in the Zerto Virtual Manager using the values from the VPG settings object in the memory. |
The VPG settings object uses an identifier, the vpgSettingsIdentifier. This identifier is not the same as the VPG identifier used to identify an existing VPG.
To ensure uniqueness, you supply identifiers to the vpgSettings API and not names. To retrieve identifiers to use in the vpgSettings API, use other Zerto RESTful APIs. For example, to retrieve the recovery network identifiers for failover and failover test networks, use the virtualizationsites/{SITEIDENTIFIER}/networks API to return both the network names and identifiers. In the vpgSettings API, you use the network identifier and not the name. In the same way, use the virtualizationsites/{SITEIDENTIFIER}/vms API to return the identifiers of all unprotected virtual machines in a site, and use these identifiers in the vpgSettings API to specify the virtual machines to add to a VPG or to protect in a new VPG.
Using the vpgSettings API
The vpgSettings API is exposed over HTTPS and requires a session running with basic authorization. The username and password authorization used must be a valid username and password either for the Windows machine where the Zerto Virtual Manager is installed or for the hypervisor manager, VMware vCenter Server or Microsoft SCVMM, accessed by the Zerto Virtual Manager. In both cases the Zerto Virtual Manager is the Zerto Virtual Manager where the APIs will run.
Using the username and password either for the Windows machine where the Zerto Virtual Manager is installed or for the hypervisor manager, VMware vCenter Server or Microsoft SCVMM, accessed by the Zerto Virtual Manager, you can establish a session by posting the following URL:
https://zvm_ip:port/v1/session/add
A session identifier, x-zerto-session, is returned as part of the response header and the session is established. The session identifier is used in the client code with every API call for the duration of the session.
The APIs can be consumed by applications implemented in different technologies in a stateless manner.
Data returned is formatted either as JSON or as XML as set by the consumer. By default, data that is returned for the v1 APIs is formatted as JSON.
An API session times out after 30 minutes of inactivity. A VPG settings object is automatically deleted from memory in the following situations:
• | When a session times out. |
• | When the VPG settings object is not used in a session for 30 minutes, even if the session is still active. |
• | When the VPG settings object is committed. |
Short Outlines of How to Manage a VPG
You manage a VPG using the vpgSettings API by using multiple methods. This section outlines the basic use of the vpgSettings API to perform different VPG functions:
• | Creating a VPG |
• | Updating a VPG |
• | Adding a Virtual Machine to a VPG |
• | Resetting Values in a VPG Settings Object |
• | Deleting a Virtual Machine from a VPG |
• | Deleting the VPG Settings Object |
Creating a VPG
When creating a VPG the set of values are specified and saved as a VPG settings object in the API session. To update the Zerto Virtual Manager with the settings, you commit the object.
You create the VPG settings object by executing the vpgSettings API with the POST method and the necessary request body.
https://zvm_ip:port/v1/vpgsettings
The request body specifies all the details required for the VPG, details of which are in VPGs: POST.
You can create a skeleton VPG settings object by using the following request body:
{}
You can then edit the response body with the required values and pass the completed JSON as a new request body.
Executing this API creates the object settings and returns the vpgSettingsIdentifier in the response body. To create the VPG in the Zerto Virtual Manager, you have to commit the changes using the following API, with the POST method:
https://zvm_ip:port/v1/vpgsettings/vpgSettingsIdentifier/commit
For more details, refer to To create a VPG:.
Updating a VPG
When editing a VPG, you first get the VPG settings as an object using the vpgIdentifier to create a new vpgSettingsIdentifier. The settings for the VPG are then modified as required and then the VPG settings object with the changes is committed to update the Zerto Virtual Manager with the changed settings. For example, the following URL with a GET method retrieves the VPG identifier that can then be used to generate a vpgSettingsIdentifier for the settings object for the VPG:
https://zvm_ip:port/v1/vpgs
Details of the VPG are returned including the VPG identifier, which is then used in the request body of the vpgSettings URL, using a POST method:
https://zvm_ip:port/v1/vpgsettings
The request body is similar to the following, in JSON format:
{
"VpgIdentifier": "49b189ff-dcd7-4544-a25d-356bea6c6676"
}
The vpgSettingsIdentifier is returned in the response body. You can use this identifier to retrieve the settings object for the VPG, using a GET method:
https://zvm_ip:port/v1/vpgsettings/ac942f3f-8e40-4d5f-a782-8cfebe80ed33
You update the VPG settings object by executing the relevant API. For example to update any of the basic settings, you use the vpgsettings/vpgSettingsIdentifier/basic API with the PUT method and the necessary request body.
https://zvm_ip:port/v1/vpgsettings/ac942f3f-8e40-4d5f-a782-8cfebe80ed33/basic
In the following example, the request body specifies that the priority is changed to high and the journal history is changed to 10 hours:
{
"JournalHistoryInHours": 10,
"Priority": "High"
}
Executing this API changes the object settings. To update the Zerto Virtual Manager with the changed settings, you have to commit the changes using the following API, with the POST method:
https://zvm_ip:port/v1/vpgsettings/ac942f3f-8e40-4d5f-a782-8cfebe80ed33/commit
The task identifier for the update is returned in the response body and the settings object is deleted.
Note: | Changes to all the VPG settings, such as the expected RPO, are performed in the same way as described here. |
For more details, refer to To update an existing VPG:.
Adding a Virtual Machine to a VPG
The procedure to add a virtual machine to an existing VPG is the same as updating a VPG, described above, but a POST method is used instead of a PUT method to update the settings object. After the settings object is updated with the new information, the object must be committed, also using the POST method. For more details, refer to To add a virtual machine to the VPG:.
Resetting Values in a VPG Settings Object
To reset a value in a VPG settings object, do the following:
1. | Get the object and save the response. |
2. | Delete the section of the VPG settings object, using the DELETE method. |
3. | Add the new value in the VPG settings object using the PUT method. |
4. | Commit the change using the POST method. |
Note: | Mandatory parameters that do not have a default value must be set using the PUT command. |
Example 1: Resetting the Priority to the Default Value
1. | Retrieve the basic settings in the VPG settings object using the following URL with the GET method: |
https://zvm_ip:port/v1/vpgsettings/vpgSettingsIdentifier/basic
2. | Save the response body and then delete the settings in the current VPG settings object, using the same URL but with the DELETE object: |
https://zvm_ip:port/v1/vpgsettings/vpgSettingsIdentifier/basic
3. | Update the basic settings with the reset priority by changing the value of priority setting in the new request body, as follows: |
{
"JournalHistoryInHours": 4,
"Name": "test-using-API1",
"Priority": null,
"ProtectedSiteIdentifier": "6c36720e-b32d-44de-9600-042ce5268d0d",
"RecoverySiteIdentifier": "02159615-16d8-40e0-87f8-2fe669bf414f",
"RpoInSeconds": 300,
"ServiceProfileIdentifier": null,
"TestIntervalInMinutes": 262080,
"UseWanCompression": true,
"ZorgIdentifier": null
}
4. | Update the VPG settings object using the following URL with the PUT method: |
https://zvm_ip:port/v1/vpgsettings/vpgSettingsIdentifier/basic
5. | Commit the settings to update the VPG using the following URL with the POST method: |
https://zvm_ip:port/v1/vpgsettings/vpgSettingsIdentifier/commit
Example 2: Change Journal Settings
1. | Retrieve the journal settings object using the following URL with the GET method: |
https://zvm_ip:port/v1/vpgsettings/vpgSettingsIdentifier/journal
2. | Save the response body and then delete the settings, using the same URL but with the DELETE object: |
https://zvm_ip:port/v1/vpgsettings/vpgSettingsIdentifier/journal
3. | You can now update the journal settings by changing the relevant values in the new request body. |
Use the following URL with the PUT method to update the settings:
https://zvm_ip:port/v1/vpgsettings/vpgSettingsIdentifier/journal
For example, the storage to use and the hard limit and warning threshold are unlimited, as follows:
{
"DatastoreIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.datastore-201",
"Limitation":
"HardLimitInMB":0,
"HardLimitInPercent":0,
"WarningThresholdInMB":0,
"WarningThresholdInPercent": 0
}
}
4. | Use the following URL with the POST method to commit the settings: |
https://zvm_ip:port/v1/vpgsettings/vpgSettingsIdentifier/commit
Deleting a Virtual Machine from a VPG
The procedure to delete a virtual machine from an existing VPG requires that you first get the VPG settings as an object using the vpgIdentifier to create a new vpgSettingsIdentifier. The virtual machine identifier to remove from the VPG is then sent with the DELETE method to delete the virtual machine from the VPG settings:
https://zvm_ip:port/v1/vpgsettings/ac942f3f-8e40-4d5f-a782-8cfebe80ed33/vms/13d550a4-24af-4914-9ca4-09f8619eb703.vm-153
Executing this API changes the object settings. To update the Zerto Virtual Manager with the changed settings, you have to commit the changes using the following API, with the POST method:
https://zvm_ip:port/v1/vpgsettings/ac942f3f-8e40-4d5f-a782-8cfebe80ed33/commit
The task identifier for the update is returned in the response body and the settings object is deleted.
Note: | The virtual machine is deleted from the VPG but the target disks in the recovery site are kept. |
Deleting the VPG Settings Object
A VPG settings object is destroyed in the following cases:
• | When a session times out. |
• | When the object is not used in a session for 30 minutes, even if the session is still active. |
• | When the object is committed. |
• | By executing the vpgSettings API for the object, with a DELETE method: |
https://zvm_ip:port/v1/vpgsettings/ac942f3f-8e40-4d5f-a782-8cfebe80ed33
A First Time Tutorial Using the vpgSettings API
This walk-through uses the URLs that are passed to create a session and then edit an existing VPG. The examples were tested using a REST client, such as Postman, used in Google Chrome, and available from http://www.getpostman.com/.
In all the example code, the zvm_ip is the IP of the Zerto Virtual Manager where the API will run and both the content type and accept type is application/json.
To start a session:
• | Use the following URL with a POST method and basic authentication to access the hypervisor management tool, vCenter Server or the Microsoft SCVMM. |
https://zvm_ip:9669/v1/session/add
The Response Header that is returned is similar to the following:
Content-Length: 0
Date: Mon, 29 Jun 2015 08:50:58 GMT
Server: Microsoft-HTTPAPI/2.0
x-zerto-session: 9UDQD6RG7YF33QJLWQXGJV8C453N277NA22P7FSNWVZCJTWCBRHQ
The fourth line contains the value of x-zerto-session, which is used in all subsequent calls.
1. | Create a skeleton VPG settings object, using the following URL with a POST method: |
https://zvm_ip:9669/v1/vpgsettings
and the following request body:
{}
The API must be run on the protected site.
The vpgSettingsIdentifier is returned.
2. | Get the skeleton structure for the VPG settings object using the following URL with a GET method: |
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677
Where 3864850e-1580-4518-95d1-f88a4d97c677 is the vpgSettingsIdentifier returned in step Create a skeleton VPG settings object, using the following URL with a POST method:.
3. | Set in the basic parameters as required, at least the following fields: |
• | JournalHistoryInHours |
• | Name |
• | Priority |
• | ProtectedSiteIdentifier |
• | RecoverySiteIdentifier |
• | RpoInSeconds |
• | TestIntervalInMinutes. |
Get the RecoverySiteIdentifier by running the virtualizationsites API, using the following URL with the GET method:
https://zvm_ip:9669/v1/virtualizationsites
Note: | If required, the ServiceProfileIdentifier can be retrieved using the /v1/serviceprofiles API with the GET method and the ZorgIdentifier can be retrieved using the /v1/zorgs API with the GET method. |
4. | Get the structures for the Journal, Networks and Recovery sections in the skeleton by copying the Json request bodies from the examples in the help, accessed by running the following URL: |
https://zvm_ip:9669/v1/vpgsettings/help
For more details, refer to .
5. | Use the virtualizationsites API to get the following values from the recovery site to add to the skeleton settings: |
• | DatastoreIdentifier for both the journal and recovery storage |
• | DefaultNetworkIdentifier, for both the failover and move network and for the test failover network |
• | DefaultFolderIdentifier |
• | DefaultHostClusterIdentifier or DefaultHostIdentifier or ResourcePoolIdentifier |
6. | Set the journal limitations as required. A zero, 0, value means unlimited. |
7. | Get the identifiers for the virtual machines that are not protected, with the virtualizationsites/vms API and add the list of virtual machines you want protected in the VPG, as in the following example |
[{"VmIdentifier": "13d550a4-24af-4914-9ca4-09f8619eb703.vm-147"}]
8. | Remove the vpgIdentifier and vpgSettingsIdentifier lines from the skeleton. |
9. | Create a new VPG settings object by using the following URL with the POST method: |
https://zvm_ip:9669/v1/vpgsettings
and the updated skeleton for the request body.
10. | Create the VPG by committing the updated skeleton, using the following URL with a POST method: |
https://zvm_ip:9669/v1/vpgsettings/a965180f-1375-6545-9d21-556a4a41c871/commit
The task identifier is returned which can then be used with the /v1/tasks/{taskIdentifier} API to monitor the task progress. The settings object for this VPG is also destroyed.
Note: | For details about using virtualizationsites APIs, refer to Virtualization Sites API. |
The following is an example VPG settings object skeleton after it has been edited:
{
"Basic": {
"JournalHistoryInHours": 4,
"Name": "MyFirstVpg",
"Priority": "Medium",
"ProtectedSiteIdentifier": "6c36720e-b32d-44de-9600-042ce5268d0d",
"RecoverySiteIdentifier": "02159615-16d8-40e0-87f8-2fe669bf414f",
"RpoInSeconds": 300,
"ServiceProfileIdentifier": null,
"TestIntervalInMinutes": 262080,
"UseWanCompression": true,
"ZorgIdentifier": null
},
"BootGroups": {
"BootGroups": [
{
"BootDelayInSeconds": 0,
"BootGroupIdentifier": "00000000-0000-0000-0000-000000000000",
"Name": "Default"
}
]
},
"Journal": {
"DatastoreIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.datastore-201",
"Limitation":{
"HardLimitInMB":0,
"HardLimitInPercent":0,
"WarningThresholdInMB":0,
"WarningThresholdInPercent":0
}
},
"Networks": {
"Failover":{
"Hypervisor":{
"DefaultNetworkIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.network-34"
}
},
"FailoverTest":{
"Hypervisor":{
"DefaultNetworkIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.network-34"
}
}
},
"Recovery": {
"DefaultDatastoreIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.datastore-201",
"DefaultFolderIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.group-v22",
"DefaultHostClusterIdentifier":null,
"DefaultHostIdentifier":"841c3a57-e4bb-4e53-b045-47e95da4ece9.host-30",
"ResourcePoolIdentifier":null
},
"Scripting": {
"PostBackup": null,
"PostRecovery": {
"Command": null,
"Parameters": null,
"TimeoutInSeconds": 0
},
"PreRecovery": {
"Command": null,
"Parameters": null,
"TimeoutInSeconds": 0
}
},
"Vms": [{"VmIdentifier": "13d550a4-24af-4914-9ca4-09f8619eb703.vm-147"}]
}
https://zvm_ip:9669/v1/vpgs
The response to this command is a list of VPGs with information about each VPG.
2. | Copy the relevant VpgIdentifier from the response to use in the request body of another API, and create a VPG settings object for this VPG. The request body contains code similar to the following: |
{
"VpgIdentifier":"b030cbc3-3cd1-4a3b-9378-afd2a6e0ee88"
}
Note: | The content type for this example is application/json. |
Use the following URL with a POST method to create the VPG settings object for the VPG:
https://zvm_ip:9669/v1/vpgsettings
The response to this command is the vpgSettingsIdentifier and the VPG settings object is created.
3. | Get the VPG settings object for review, using the following URL with a GET method: |
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677
Where 3864850e-1580-4518-95d1-f88a4d97c677 is the vpgSettingsIdentifier returned in step Copy the relevant VpgIdentifier from the response to use in the request body of another API, and create a VPG settings object for this VPG. The request body contains code similar to the following:.
4. | Updating the VPG is done using the following steps: |
a. | Get the current settings for the part of the VPG you want to update. For example, to update the basic values, use the following URL with a GET method: |
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/basic
Where 3864850e-1580-4518-95d1-f88a4d97c677 is the vpgSettingsIdentifier returned in step Copy the relevant VpgIdentifier from the response to use in the request body of another API, and create a VPG settings object for this VPG. The request body contains code similar to the following:.
The following example response body is returned:
{
"JournalHistoryInHours": 4,
"Name": "Test-Using-API",
"Priority": "Medium",
"ProtectedSiteIdentifier": "6c36720e-b32d-44de-9600-042ce5268d0d",
"RecoverySiteIdentifier": "02159615-16d8-40e0-87f8-2fe669bf414f",
"RpoInSeconds": 540,
"ServiceProfileIdentifier": null,
"TestIntervalInMinutes": 131040,
"UseWanCompression": true,
"ZorgIdentifier": null
}
b. | Use the response body from step Updating the VPG is done using the following steps: to create the request body for the update with the required changes and then use this request body with the following URL with a PUT method: |
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/basic
The following example request body changes the priority, journal history and compression settings for the VPG:
{
"JournalHistoryInHours": 10,
"Priority": "High",
"UseWanCompression": false,
}
c. | You can verify that the VPG settings object has been updated by rerunning the following URL with a GET method: |
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/basic
d. | Update the VPG with these new settings by committing the change, using the following URL with a POST method: |
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/commit
The task identifier is returned which can then be used with the /v1/tasks/{taskIdentifier} API to monitor the task progress. The settings object for this VPG is also destroyed.
To add a virtual machine to the VPG:
https://zvm_ip:9669/v1/localsite
The API must be run on the protected site.
2. | Get the identifiers for the virtual machines that are not protected, with the /v1/virtualizationsites/vms API, using the following URL with a GET method: |
https://zvm_ip:9669/v1/virtualizationsites/6c36720e-b32d-44de-9600-042ce5268d0d/vms
Where 6c36720e-b32d-44de-9600-042ce5268d0d is the local site identifier, returned in step Get the identifier for the protected site, for the virtual machines that are not protected, with the /v1/virtualizationsites or /v1/localsite API. For example, using the following URL with a GET method:. The following example response body is returned:
[
{
"VmIdentifier": "13d550a4-24af-4914-9ca4-09f8619eb703.vm-147",
"VmName": "Operations"
},
{
"VmIdentifier": "13d550a4-24af-4914-9ca4-09f8619eb703.vm-148",
"VmName": "HR"
}
]
3. | Updating the VPG to include the virtual machine you want to add, by first creating the VPG settings object as described in steps Use the following URL with a GET method and the x-zerto-session added to the header to retrieve the VPG identifiers for existing VPGs. A VPG identifier is then used to create the VPG settings object: to Get the VPG settings object for review, using the following URL with a GET method: in To update an existing VPG:, above and then using the following URL with a POST method: |
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/vms
Where 3864850e-1580-4518-95d1-f88a4d97c677 is the vpgSettingsIdentifier. The Request Body contains the following:
{
"VmIdentifier":"13d550a4-24af-4914-9ca4-09f8619eb703.vm-147"
}
Where 13d550a4-24af-4914-9ca4-09f8619eb703.vm-147 is the virtual machine identifier to add to the VPG.
4. | Update the VPG with the virtual machine by committing the change, using the following URL with a POST method: |
https://zvm_ip:9669/v1/vpgsettings/3864850e-1580-4518-95d1-f88a4d97c677/commit
The task identifier is returned which can then be used with the /v1/tasks/{taskIdentifier} API to monitor the task progress. The settings object for this VPG is also destroyed.