VMware Skyline is a proactive support tool to help customers avoid problems before they occur. More information on the service can be found here: https://www.vmware.com/support/services/skyline.html. One feature of this service is a GraphQL based API known as the Skyline Insights API. Using this API, you can query for active findings (the problems known/covered in the Skyline catalog) and for affected objects (the inventory items impacted by these findings). This was my first attempt at using a GraphQL based interface and it had a few learning curves.
The first learning curve with GraphQL was dealing with iterating through the results set. By default, the Insights API only returns 200 results per query. Once you have the first 200 records, if the query has more results you need to ask for the next batch of 200, and so on until you have all the results. This is easy enough to do, however the API will eventually start rate limiting queries against a Skyline Organization. Due to this, we also need some logic to account for these HTTP 429 rate limiting responses. As I attempted to solve these issues, I ended up creating a PowerShell module that would account for these lessons learned. The remainder of this post will cover how to use this new VMware.Skyline.InsightsApi PowerShell module.
To get started, you’ll need a API token. The process to create one is well documented here: https://blogs.vmware.com/kb/2021/12/skyline-insights-api-getting-started.html.
Second, you’ll need the module. All of the code for this is available in the VMware PowerCLI-Example-Scripts repo at https://github.com/vmware/PowerCLI-Example-Scripts/tree/master/Modules/VMware.Skyline.InsightsApi and also available in the PowerShell Gallery. The easiest way to install this module is with Install-Module VMware.Skyline.InsightsApi. This module contains 7 functions:
Get-Command -Module VMware.Skyline.InsightsApi
CommandType Name Version Source
----------- ---- ------- ------
Function Connect-SkylineInsights 1.0.0 VMware.Skyline.InsightsApi
Function Disconnect-SkylineInsights 1.0.0 VMware.Skyline.InsightsApi
Function Format-SkylineResult 1.0.0 VMware.Skyline.InsightsApi
Function Get-SkylineAffectedObject 1.0.0 VMware.Skyline.InsightsApi
Function Get-SkylineFinding 1.0.0 VMware.Skyline.InsightsApi
Function Invoke-SkylineInsightsApi 1.0.0 VMware.Skyline.InsightsApi
Function Start-SkylineInsightsApiExplorer 1.0.0 VMware.Skyline.InsightsApiThe first two functions listed (Connect-SkylineInsights and Disconnect-SkylineInsights) are used to connect to the API. The first requires an -apiKey parameter, which we obtained earlier. With this apiKey a global variable is created ($Global:DefaultSkylineConnection) containing the bearer token used to query the API. The second function simply clears out this global variable. As a safety mechanism, logic exists in the helper function to prevent the other functions from executing if this global variable is not present.
The Format-SkylineResult function is an optional function that helps with converting some of the objects returned by the API into strings. This is useful if you want to export the output into something like a CSV file. By default, if you attempt to pass the output from one of the other functions to a CSV, like Get-SkylineFinding | Export-Csv D:tmp\mySkylineFindings.csv many of the columns will end up with System.Object[] and the date values will be stored as long integers. If we also use this function, such as Get-SkylineFinding | Format-SkylineResult | Export-Csv D:tmp\mySkylineFindings.csv the objects are converted to strings (that can be separated by the value you pass to -separator) and the dates are converted to PowerShell dates.
The next function listed, Get-SkylineAffectedObject will return the list of affected inventory findings. It requires a -findingId and a -products input parameter to be passed in, either by property name or pipeline. A ‘product’ in this context is the case sensitive name of an endpoint in the Skyline Inventory, such as a vCenter Server name, Horizon Connection Server, vROps instance or the like. The ‘findingId’ is the case sensitive ID of the finding / issue that Skyline is aware of. Both of these properties, in the expected case, can be uncovered with the next function.
Next up, Get-SkylineFinding is a function that requires no input parameters, but does support three — the same -findingId and -products described above, as well as -severity. You can specify any number of these parameters, either by name or pipeline. The severity parameter is implemented client side, so all records are returned to the function, but the function will only return those matching one of the Skyline finding severities (Critical, Moderate, or Trivial). The output of this function can be piped to the above AffectedObject function, such as Get-SkylineFinding -severity:CRITICAL | Get-SkylineAffectedObject .
The Invoke-SkylineInsightsApi function is a proxy function that is consumed by both Get-SkylineAffectedObject and Get-SkylineFinding and is usually not directly consumed. It is exposed in the function for testing and any sort of future use. This is where much of the logic is implemented so that it can be shared by the two get functions.
Last, but not least, is the Start-SkylineInsightsApiExplorer function. This function will take the bearer token from the Connect-SkylineInsights function, put it in the clipboard, then launch the Skyline Insights API Explorer website in a web browser. From here, you can paste the bearer token into the ‘Request Headers’ area and interactively explore the GraphQL query for Skyline Findings.
I hope you find this module useful. If you have any feedback please leave a comment below or open an issue in the PowerCLI-Example-Scripts repo here: https://github.com/vmware/PowerCLI-Example-Scripts/issues.
