Creating a Workflow to Execute a One-Line PowerShell Command
One of the most basic things you can do with vRealize Orchestrator is to execute a command within a guest operating system. vRealize Orchestrator comes out of the box with the “Run program in guest” workflow, which utilizes the VM Tools interface to kick off a process from within a guest operating system. This workflow will work with any support operating system on a virtual machine that has a valid, current version of VM Tools installed. If VM Tools is not installed, or is not running properly, this workflow will fail, so it’s important to be sure that your target virtual machines meet these pre-requisites prior to proceeding with this use case. Provided that you do meet the requirements, this can be a very powerful tool for automating operations in the datacenter, to include things like operating system configurations and software installs.
In this example we’ll use this interface and built-in workflow to execute a one line PowerShell command that will enable us to build other workflows that do more complex things. This is an example of the divide and conquer approach we recommend for vRealize Orchestrator workflow design and development. These workflows can be used as building blocks for more complex use cases that chain them together to do bigger things in sequence.
Before we get started, it’s important to note that vRealize Orchestrator comes out of the box with a PowerShell plug-in installed. It works in a slightly different manner, and requires additional configuration you might not want to undertake. It requires you to utilize WinRM remoting and to build and register a PowerShell proxy server that will actually execute the PowerShell scripts you want to execute on your behalf. It will handle the communications with the remote servers itself using WinRM. This setup can sometimes be complicated and requires your guest VMs to be able to communicate with the PowerShell server. This is not always desired nor is it always the case. Sometimes, it is necessary to orchestrate disconnected or isolated machines and the “Run program in guest” workflow is a good way to do this. We are by no means denigrating the built-in PowerShell plug-in; yet, we are simply delineating the use cases and putting forth an additional way to accomplish a similar task, but in a somewhat more lightweight manner.
As an Amazon Associate I earn from qualifying purchases.
One of the drawbacks of using this method to execute processes in guest VMs is that you must know the username and password of an account that has admin permissions to execute processes on the virtual machine. It is not always easy to supply this at runtime of a workflow. In this case, we are going to ask for that information as an input to the workflow. This requires a user to know and enter the information when the workflow is run. But what about a case where you want a user to be able to run a workflow without knowing or entering administrative user credentials? We have a solution for that, but it will be covered in a different example. The short answer is that we can cache credentials in an encrypted configuration element and reference that for use in these types of workflows in order to get around the need for a user to provide it at workflow runtime.
Create the Workflow
Create a new workflow with the name “Execute Powershell Command.” We are going to place this workflow in the /Examples/Tools/Scripts folder, but you can place yours anywhere that makes sense for your environment.
The workflow should have four inputs:
- vmUsername – string – this is the admin username for the machine that has permissions to execute a process in the operating system.
- vmPassword – SecureString – this is the password for the admin username referenced in input 1.
- vm – VC:VirtualMachine – a reference to the virtual machine on which we want to execute a program in guest.
- arguments – string – a string of arguments we will be passing to the program we will be executing. This is essentially just appended on to the end of the command we use to execute the process.
Figure 1. Workflow inputs for the "Execute Powershell Command" workflow
We will be assigning four attributes for this workflow:
- interactiveSession – boolean – set to false
- programPath – string – hardcode to “C:\Windows\System32\WindowsPowerShell \v1.0\powershell.exe
- workingDirectory – string – blank
- environment – Array/string – set to an empty array
Figure 2. Workflow attributes for the "Execute Powershell Command" workflow
This workflow has one output, which is the process ID (PID) from the process being executed in the guest:
- result – number
Figure 3. Workflow outputs for the "Execute Powershell Command" workflow
The workflow consists of two steps. The first is the out of the box “Run program in guest workflow.” The second is a Log Output step. The schema we will build will look like this:
Figure 4. Schema for the "Execute Powershell Command" workflow
Create the first step by dragging and dropping a new “Workflow element” node on to the schema canvas between the start and end nodes. Search for “Run program in guest” to find the workflow. Double-click it to accept it on to the canvas.
Wire the inputs, attributes, and outputs in the following manner:
- vmUsername -> vmUsername
- vmPassword -> vmPassword
- vm -> vm
- arguments -> arguments
- interactiveSession -> interactiveSession
- programPath -> programPath
- workingDirectory -> workingDirectory
- environment -> environment
- result -> result
The visual binding on the “Run program in guest” step should look as follows:
Figure 5. Visual binding for the "Run program in guest" step of the "Execute Powershell Command" workflow
Now add a scriptable task node between the “Run program in guest” node and the Workflow end node. Set the name to “Log Output.”
Wire the inputs, and attributes up to the “Log Output” step as follows:
- vm -> vm
- arguments -> arguments
- programPath -> programPath
The visual binding for the “Log Output” step should look as follows:
Figure 6. Visual binding for the "Log Output" step of the "Execute Powershell Command" workflow
The script content of the scriptable task should consist of the following:
System.log("Command executed in guest " + vm.name + ": " + programPath + " " + arguments);
Save the workflow and test the execution on a Windows machine in your environment.