The plan for this part of the series was to focus on the setup needed for configuring the recovery settings of our protected VM, finishing off the series and the workflow. Then as I started writing it I realised that as this post will provide background information on consuming the SRM api it was going to be quite long. Therefore I’ve split it into two parts. Part 4 covers the background on configuring vRO to enable the setting of the IP customisation settings using the api. While part 5, which is also available now contains the completed workflow structure.
Recovery settings provided by SRM include the recovery priority, pre and post power on commands and IP address customisation. With v8.1 of the SRM plugin for vRO it is not possible to set the IP address customisation mappings of the VM i.e. the IP address to use after failover, this must be performed using the API.
If you don’t need to set IP customisation as part of your VM recovery settings, then the workflows provided by the SRM plugin can be used. There is a large amount of overlapping functionality between the plugin workflows and the api, and as I need to change the IP customisation settings it is logical to also apply the other recovery settings as part of the same workflows. Therefore I will not be using any of the workflows provided by the plugin, and will rely on the api instead.
Adding the SRM host to vRO
SRM 8.1 has a SOAP API, which is documented on the VMware website. vRO provides a SOAP plugin that can be used to add a SOAP host and then perform operations against the host. Unfortunately when I tried to add the SRM host at the protected site as a SOAP host, telling vRO to automatically retrieve the WSDL content from the server the workflow failed. It appears vRO can’t interpret the WSDL file. Simply copying and pasting the WSDL content from a browser into the workflow generated the same issue.
The solution was to edit the WSDL content format and then copy it into the workflow. Here is the format I used to add my SRM server as a SOAP host, replace the <SRM Server FQDN> text with your protected site SRM server address:
Once the workflow completes, if you head over to the inventory tab and expand your new SOAP host you should see a fairly long list of operations under your host.
Getting started
Now the host is available how do we know where to start with performing operations on it? Well the answer is to take a look at the SRM API Developers Guide which is available on the VMware website (you will need to login to VMware Code to view the documentation). The document provides a list of the operations in an approximate order of use, starting on page 8. As you might expect one of the first operations to perform is to log in to the hosts, from there you can list existing inventory details and importantly for my use case on page 12 there is a SetRecoverySettings operation.
Logging in to SRM API
There are a couple of different operations available for logging in to SRM, I choose the LoginSites operation for ease of use since it will allow me to log in to both the protected and recovery sites with a single operation and doesn’t add the complexity of having to get a token from the PSC first. For a proof of concept this feels like a suitable solution, however if this was going to be used as part of an Enterprise solution, the token based login may be more suitable.
Looking at the details of the LoginSites operation in the API Developers Guide it requires inputs of the credentials for both sites as you would expect but there is also mention of a SrmServiceInstance assigned to an _this parameter. Checking the operation in the vRO inventory on our SOAP host we see the same input parameter _this, with the only additional information being that it is a string value.
Object Classes in the API
So what is the SrmServiceInstance and how do we get its value? It took a bit of trial and error, but eventually I discovered the answer is provided on page 18 of the API Developers Guide where there is a relationship diagram.
On the left of the diagram near the top there is a SrmServiceInstance box, and inside the box one of the operations listed is the SrmLoginSites. What I discovered is that each operation you perform via the SOAP API takes an input of _this, and sometimes an _this(type) parameter. If the operation being performed isn’t using a particular Recovery Plan, or VM for example then the _this and the _this(type) values are almost always the same. The value to use for the _this parameter is the name assigned to the box on the relationship diagram that contains the operation being performed. I discovered this through trial and error, as the api threw back some error messages such as “Type Mismatch: expected: class Drextapi::RecoveryPlanFolder, found: class Dr::ExtApi::RecoveryImpl” which gives you the hint as to the value that should have been used.
So for the LoginSites operation the _this value would be set to SrmServiceInstance. As the operation is not being performed on a particular inventory object the _this(type) parameter is also set to SrmServiceInstance.
If the operation is using a particular object, then the _this value is the id of the object on which to perform the operation, which is usually the parent object within the inventory rather than the object itself. The _this(type) value is the Object Class the operation being performed belongs to from the diagram.
So for example, to perform the GetProtectionGroup operation to find a particular Protection Group you would set the _this value to the id of the Protection Group root folder, as this is the parent of the Protection Group inventory object. The _this(type) value would be set to SrmProtectionGroupFolder as this is the Object Class the GetProtectionGroup operation belongs to. It might seem a bit strange at first, but as you start using the different operations it becomes clearer.
Why is vRO saying the session is not authenticated?
So having identified the first operation I wanted to perform, SrmLoginSites, and armed with the knowledge of how to work out the input values I needed to set I used the Generate a new workflow from a SOAP operation workflow to create a new workflow for my login operation. Adding the relevant input values and running the workflow all seemed fine, the workflow succeeded and it appeared I had been logged in. Unfortunately when I tried to follow this login with any other operation I was presented with an error message ‘the session is not authenticated’.
Having not worked with SOAP previously I didn’t really know what was going wrong. The options provided by the SOAP plugin in vRO are fairly limited and I wasn’t seeing anything in the response body or headers of my request to suggest an error or misconfiguration. A bit of research using lead me to the following blog from 2016 around automating SRM https://virtualbrakeman.wordpress.com/2016/08/24/vrealize-orchestrator-and-site-recovery-manager-the-missing-parts-or-how-to-hack-soap-apis-to-get-what-you-want/
The article was focused on a previous version of SRM but it outlined how SRM returned a token or cookie value in response to the login request, and that its value then needed to be specified on future requests. This made sense, given products such as vRA use tokens with the REST api to provide authentication when performing requests rather than the administrator supplying the username and password each time.
So, I repeated the experiment from the blog of installing Fiddler and using the example code for sending a login request via a REST operation in vRO, submitting the SOAP operation as an XML body for the request. Hey presto, it’s still valid in SRM 8.1 and the cookie header value shows up in Fiddler, but still not within vRO when you run the SOAP plugin based operation. Even specifying it by name didn’t work, so for now I am sticking to using the REST operation to perform the initial login. All subsequent actions, with one exception can be performed using SOAP operations in vRO.
The exception, is to log out the session at the end of the workflow. Each of the logout options I tried reported the ‘the session is not authenticated’ error message, even when passing the session cookie value as an input. So, I experimented with the same approach that lead to the solution for the login process, that is using Fiddler to capture the traffic. This time I used powercli to log in to SRM using the command connect-srmserver and then immediately log out using the command disconnect-srmserver. Reviewing the output captured by Fiddler showed that it was sending the SrmLogoutLocale command and setting the token as a header with the name Cookie and a value of vmware_soap_session=<token id>, which is the same format the Cookie appears in within the headers of the login operation. Therefore, I’m going to use a REST operation to perform the disconnection from SRM at the end of the workflow.
The SRM server at the protected site is the only server that needs to be added to vRO as a REST host. Add the host with the url <SRM Server FQDN>:9086 and leave authentication set to None, since we will pass credentials as part of the login/logout operations.
You will need to create two operations on the new REST host, one for login and one for logout. You could consolidate these into a single operation as they both share the same base url, however I personally prefer to keep them separate so that the purpose of each operation is clear for vRO administrators to see. The url to use for the operation is /vcdr/extapi/sdk and the Method to use for both operations is POST. All other options will be generated and then set as part of the vRO workflows before the operations are executed.
That’s all for part 4. Part 5 completes the series with details of the individual operations needed to configure the recovery settings of the VM.