This is the first in a multi part series on how the cmdlets within the PowervROps module (https://github.com/andydvmware/PowervROps) can be used, and gives specific examples for use.
Loading the module
The first thing that needs to be done prior to using the module is to load it into the current PowerShell session. This can be accomplished by running the following command:
import-module <path-to-module>\powervrops.psm1
To list all of the available commands within the module issue the get-command cmdlet:
get-command -module powervrops
As with all PowerShell cmdlets the get-help cmdlet can be run to return information about a specific one:
get-help addStats -detailed
Authentication
Before any meaningful commands can be executed against vROps we must have a mechanism to authenticate to it. With PowervROps there are two options; a credentials based method and a token based method. Both authentication methods work with all of the cmdlets and indeed they could be mixed and matched as necessary.
Credentials based authentication
Credentials based authentication allows identical functionality when running in interactive mode in that a credentials object can be generated and then used in the same way as using token based authentication:
$credentials = get-credential -username <username>
The advantage of using credentials based authentication is that (although a security risk), the password used for authentication can be saved to a file and then read in during credentials creation. There is lots of information on this subject and below is a link to a blog post I’ve referenced a number of times:
https://blog.kloud.com.au/2016/04/21/using-saved-credentials-securely-in-powershell-scripts/
With this method scripts can be written and then used with task scheduler in a non-interactive fashion.
Token based authentication
Token based authentication requires that a user authenticates to vROps and in turn receives a token that lasts for 24 hours and can then be used on all subsequent requests. To make the process simpler there is a cmdlet called acquireToken which handles this for you. In order to be able to use the token during the session save it to a variable:
$token = acquiretoken -resthost <fqdn-of-the-vrops-node-or-cluster> -username <username> -password <password> -authsource <authsource>
If we execute this and then query the $token variable we should return something like below:
cac9cdc1-c2b3-487c-a51f-4ccb45e2b246::571da88c-a643-4706-a4d5-2e67d9ab1254
A few things to note about this command:
- The password if using this command directly will be shown in plain text on screen, although there are methods around this when using the command in a script and prompting the user for their password an example is as follows:
-
$token = acquireToken -resthost $resthost -username $username -password ([Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR((read-host 'Password: ' -assecurestring)))) -authSource $authsource)))
- The authsource argument can either be local for local vROps accounts or the name of the domain name as configured via the authentication sources section in vROps.
Running our first command
Now that we have an authentication method we can execute our first command. For the purposes of the rest of this post (and the others in this series) I will use variables for things like the authentication token and the rest host that I will be connecting to. There is a cmdlet called getNodeStatus which returns information about the status of your vROps nodes:
getNodeStatus -resthost $resthost -token $token
This will return information similar to the following:
This command could be used along with a credentials object in a scheduled task to perform daily checks against vROps in a script format. If the variable is set by the command such as $notestatus then $nodestatus.status would quickly and easily allow you to retrieve the status of your vROps nodes without needing to open up a browser
Getting specific property information about an object
As interesting as retrieving the status of your vROps cluster is, that is far from the most interesting thing that can be achieved with PowervROPs. The scenario is to retrieve whether vSphere HA is enabled on a specific cluster. Now this information can be retrieved in many different ways and this is by far the most efficient (that’s what PowerCLI is for….). However, it shows what can be achieved via PowervROps.
There are a number of stages necessary in order to retrieve this information
- We need to obtain the ID of the object we want to query (the GUID that you see in the browser window when viewing the object in the vROps UI)
- We then need to get the specific property we are interested in from that object
Obtain the resources vROps ID
To get a resource we use the getResources cmdlet. Along with the standard arguments used in all of the cmdlets this has additional arguments for ‘name’, ‘resourceKind’ and ‘objectID’ which can be used to get a specific resource. This cmdlet can also be used to get all cluster resources, or all resources that have a common name element. For now we are going to get the cluster object called ‘Cluster A’ and save it to the variable $cluster
$cluster = getResources -token $token -resthost $resthost -name 'Cluster A' -resourceKind 'ClusterComputeResource'
If we query the cluster object and get its members we can see what a vROps resource query returns:
To get at the actual cluster object we need to step through the resourceList element:
We’ll go through the resourceList element in further detail in a future post but for now what we are interested in is the identifier element which is the object ID within vROps. We can get at this ID directly via:
$cluster.resourceList.identifier
Get all properties
Whilst we are specifically interesting in the HA enabled property it is worth knowing how to retrieve all properties as it has the benefit of showing you how the property is named when it is returned via such a query:
$clusterproperties =getResourceProperties -resthost $resthost -token $token -objectid $cluster.resourceList.identifier
If we look at the members of this variable we can see there is an element called property and if we query that then we can see all of the properties for this object
Get the HA setting property
To get at the specific property via a single command then we need to alter it slightly
$clusterhaproperty = getResourceProperties -resthost $resthost -token $token -objectid $cluster.resourceList.identifier).property | where { $_.name -eq 'configuration|dasConfig|enabled' }
As you can see knowing what the name of property is comes in handy when querying it directly.
This is the end of the first part in this series, check back soon for additional instalments where we will look at (amongst other things), generating reports, adding properties to an object, creating new objects, creating custom groups and investigating supermetrics.
All posts in this series:
Using PowervROps cmdlets (part 1) – Introduction
Using PowervROps cmdlets (part 2) – Retrieving metrics from objects
Using PowervROps cmdlets (part 3) – Adding metrics and properties to objects
Using PowervROps cmdlets (part 4) – Working with objects
Using PowervROps cmdlets (part 5) – Working with relationships
Using PowervROps cmdlets (part 6) – Working with custom groups
Using PowervROps cmdlets (part 7) – Working with supermetrics
Using PowervROps cmdlets (part 8) – Working with reports
Using PowervROps cmdlets (part 9) – Working with alerts
Leave a Reply