Disaster Recovery

vSphere Replication REST API with PowerShell: Configure VM replication

vSphere Replication (VR) 8.6 introduces REST API to allow automation of all operations and workflows.

Supported functionality through vSphere Replication REST API version 1.0 is:

  • Session management
  • Create/delete a site pairing
  • Create/pause/delete/pause/resume a replication
  • Querying vCenter inventory data, related to replication management
  • Task monitoring

This blog post will demonstrate how to leverage the REST API to automate creating a VM replication through PowerShell script.

Details on the used APIs could be found here:
Configure Replication REST API


Since vSphere Replication is about setting up replications between different sites (vCenter instances), there are some caveats. Some of the vSphere Replication workflows require requests to be made to different servers, e.g., local vCenter Server, remote vCenter Server, local VR Management Server (VRMS), remote VR Management Server.
VR REST API is designed to be used as a gateway to all those servers so that it can complete all workflows through single API connection. Therefore, for some endpoints there is a parameter to specify to which server the specific call needs to be made. For example, you can use the following request to get a list of datastores for local or remote vCenter Server instances.

GET <vr-rest-api>/api/rest/vr/v1/pairings/<pairing_id>/vcenters/<vcenter_id>/datastores

To support this, the API requires authentication to remote vCenter Server. Authentication is required only if a call to an API, including to a remote vCenter or to a remote VRMS, is made.

Configure VM Replication

Configure VM replication is by far the most complex and used workflow which you can do through VR REST API. Here is the step-by-step guidance on how to automate it through PowerShell script.

Configure VM replication is an operation between two sites – protected site and recovery site.

To configure a VM replication, we must have have the following data:

(1) Information about the VM – id, disk details, if suitable for replication

(2) Target datastore to place replication data

(3) (Optional) The target storage policy. If not specified, the default storage policy will be used.

(4) (Optional) The target vSphere Replication server to handle replication traffic. If not specified, it will be auto-selected by VRMS

(1) should be retrieved from the protected site

(2), (3), (4) should be retrieved from the recovery site.

In our example, we use the local site (which we are logged into) as protected source and the remote site as a recovery target.


Let’s take a look at the following function:

We ask the user for the local vCenter’s user name and password. Then constructing Authorization header with them in Base64 format and making a POST request to /session endpoint.

If successful – we construct global variable with the x-dr-session header and the session ID as a value. From now on, if we use $global:headers every request to the API will be authenticated until the session expires due to inactivity.

Retrieve and find a pairing

VR REST API is organized in pairings between two sites. All APIs related to replications are available within a pairing, thus we would need to find the desired pairing.

This function fetches all pairings and searches for a pairing with a given remote vCenter ID. If the remote vCenter ID is unknown, we could list all pairings and choose based on the vCenter or VRMS hostname.

Great! We have session and we know which pairing we want to use for our VM replication. Next API calls, however, require authentication to the remote site.

Establishing session to remote site

Pairing consists of two sites – local and remote. When we authenticate to the VR REST API, we create a session to the local site. However, authentication to the remote site is explicit operation per pairing. Once authenticated to both sites, all APIs are available.

This is a function which does remote login with user-supplied credentials:

Important thing in the implementation is that we must provide both x-dr-session AND Authorization header. What this does in the background is to associate the session to the remote site with the current client session. We can continue to use x-dr-session header with the same session id value as before.

Find target datastore

The ID of a target datastore is a requirement of the replication spec, used to configure VM for replication. Target datastore is a datastore at the recovery site (our remote site) and is used as a place to put the replicated VM files (VM home, disks, etc). Here is the function to find the target datastore ID by a given name:

Here we use built-in filtering functionality of the REST API to filter datastores by name:


Find target storage policy

Target storage policy is used to provision the VM disk replica. It’s an optional parameter and if not provided, the datastore’s default storage policy will be used. If the target datastore does not comply with the target storage policy, there might be a replication error. We can check compliance with a call to: 

POST /{pairing_id}/vcenters/{vcenter_id}/storage-policies/{storage_policy_id}/actions/check-compliance

when setting the target datastore ID as body to the request.

This is the function which retrieves the target storage policy ID:

Retrieve details about the VMs to replicate

There are different approaches to collect the VMs data depending on what we know about the VMs we want to replicate. In our example, we will search VMs based on their name. Keep in mind that the filtering we use is more like “value contains” rather than “value is“. So, if we have VMs with similar names, we might get all of them based on the filtering criteria.

Note we are using local_vc_server.id to collect VMs data from local site (as it’s our protected site).

Also, note we use suitable_for_replication=true query parameter to filter VMs automatically, which excludes VMs which are already replicated, missing permissions, templates, special VMs, etc. 

If there is a VM which is not suitable for replication, but you don’t know the reason – use

GET /{pairing_id}/vcenters/{vcenter_id}/vms/{vm_id}/capability

in addition, it will return a detailed information about the supported replication settings. This API is used for suitable VMs as well. 

Configure replication

Finally! We are done with collecting data and will replicate our VMs!

The function:

First, we construct configure replication spec for each VM with the desired settings. Then for each VM disk construct replication structure with the target datastore ID and target storage policy ID. VM disk data is already available from the previous call and just set it back.

Note that target_vc_id is the recovery site (in our example – the remote site).

POST request responds with a list of tasks for each VM which can be monitored to know the outcome of the operation.

Configure VM replication API has all settings which are available through the UI – excluding disks, MPIT, encryption, selection of seeds, etc. Some of these require additional API calls to collect data.


We recommend to log out from the VR REST API after you are finished with the main logic. This way you won’t exhaust the session pool to any of the services.

Put it all together

We have combined all functions into a self-contained script. Sample usage of the script:
.\vr-configure-replication.ps1 -vrmsServer my-vrms-instance.acme.com -vmNames myVm -autoReplicateNewDisks $true -targetDatastoreName local

Follow the VMware DR Community Team on Twitter @VMware_DR_team and send us any feedback.


Leave a Reply

Your email address will not be published. Required fields are marked *