Thursday, July 28, 2016

Starting vRO Workflows with Log Insight Webhooks

Beginning with version 3.3 of Log Insight, alerts can be forwarded via a webhook.  Basically, any URL you designate will have an HTTP POST issued with the alert contents as a JSON body.  This feature provides some very basic capability and most use cases will require a bit more functionality.

For example, vRO workflows can be started from the vRO REST API, but you need to authenticate and prepare a JSON body with expected inputs at a minimum.

I learned of a nice shim, written in Python by some of my peers here at VMware.  You can read more about the general capability of the shim at this link.  The shim had the basic capability I needed, it just didn't support a vRO endpoint.  The authors (Alan Castonguay and Steven Flanders) invited contributions via a pull request, so, I added the vRO shim and I want to provide a little more information about the usage here in this blog post.  General install and usage instructions are on the Github page for the shim, so I won't cover that.

Authentication

The "vrealizeorchestrator.py" shim does not include any authentication information.  By default, Requests library defaults to the user's .netrc file if no auth options are given.  So, you will need to set up a .netrc in the user home directory with the hostname, username and password, i.e.

machine vro-01a.corp.local
login administrator@vsphere.local
password VMware1!

This has the benefit of securing the password without adding additional code and exposing the credentials.

To Parse or Not to Parse?

The example code shows a workflow that accepts two inputs, both string.  One is "value" which I will talk about below in the next section.  The other, "alertName" is a value that can be retrieved via the parse() function that is part of the main file "runserver.py" and does a nice job of returning a Python object that you can pull various bits of the alert payload from.  

Do you need to use the parsed alert?  Depends.  In the use case I was writing this shim for, I needed the entire payload in vRO so I could parse it there.  This is because the alert itself has a lot of variability - it is an alert that watches for NSX distributed firewall drops on port 22, by src/dst pair.  That src/dst pair could be different each time and there could be any number of those pairs in a single alerts - practically impossible to anticipate for workflow input.  On the other hand, if your alert watches a specific system for a specific event... well, you probably don't even need to pass inputs. Or maybe you just need the system name.  My recommendation is to try and make your Log Insight alerts as specific as possible and then deal with the remaining variables in either the Python code via the parse() function or in the case of multiple variables by passing the entire alert payload on to vRO for evaluation.

JSON Payload Serialization

I ran into a fun problem with trying to pass a JSON string to vRO as an input.  Basically, it confuses vRO because it reads the JSON string input value as part of the parameter input body.  My work-around was to serialize the JSON string from Log Insight and as such vRO would just see a long string input and be happy.

So, this is why you see the line:

"value": base64.b64encode(request.get_data())

As discussed above, you might not need to do this.  However, if you do, you'll want to grab the CyrptoJS actions package for vRO It has a base64 decode action and I tested it with the shim.


Comments and feedback are welcome, of course.  The shim is provided as an example and should not be used in production.