If you’ve installed Cisco UCS Director before, you know that there exists a small component that can be installed onto a Windows device that allows for remote execution of PowerShell scripts. These scripts can be harnessed and used in ways to add automation and orchestration functionality to UCS Director where native integration into UCS Director may not already be happening. This series of posts is to explain what the use cases for the PowerShell Agent are, what the PowerShell agent does, and how you can utilize PowerShell for some advanced techniques within the Cisco UCS Director platform.
Installation and Configuration
I will not go into the full details of the base install and configuration of the agent onto a Windows server in your UCS Director environment. I will make sure to mention, however, that you should remember these key details:
- Cisco UCS Director and the PowerShell Agent services default communication port is 43981/tcp
- An access key is created by the main UCS Director services that will be used for secure communication on that port. Make sure to copy that key from the main UCS Director interface and enter it into the PowerShell Agent configuration on the Windows server the Agent was installed
- Consider your third-party modules that you will plan on installing and check with the support matrices to see what maximum versions of the .NET Framework and PowerShell you can install on the Agent. I would recommend going as high as you can to start. (Special Note: At the time of writing this post, PowerShell 6.0 was still in alpha and I would not consider that version ready for production use, especially due to many issues I’ve personally had with opening remote PowerShell sessions).
- You will likely have to configure WinRM on any device you plan to have the agent server communicate with. Most WinRM configurations are set, by default, to disallow every host in their TrustedHosts configuration
The Flow of Communication
One of the misconceptions of the PowerShell Agent (or at least what I thought for the longest time) was that by default the PowerShell Agent processes all the PowerShell requests locally. This was proven to be quite incorrect. The PowerShell Agent initiates a remote PowerShell session (PSSession) to any particular device that may be included in the WinRM configuration and that you can communicate with on the default WinRM port.
Breaking through this wall was key to start understanding exactly how to troubleshoot some potential problems with the PowerShell Agent and some key PowerShell cmdlets. You can read more about that in another blog post I wrote here: Using Invoke-WebRequest with the Cisco PowerShell Agent
This idea comes in handy, especially when you have certain PowerShell modules that may not necessarily function correctly unless on a host with certain Windows features. During many of the test sessions I’ve opened with various devices in my lab, I did come across a unique case in which Windows Active Directory cmdlets could not be executed unless ran from a device that had a specific Windows Active Directory role associated with it.
You can easily test communication with a PowerShell Agent in the UCS Director interface. As an administrator of UCS Director, navigate to the follow location: Administration > Virtual Accounts. Select the PowerShell Agents tab. You should see your PowerShell agent that you registered with your Director instance. If you select your instance, two new task options appear in the bar above your list. You can select Test Connection if you need to test just simple network communication to the device. You can select Execute Command if you would like to initiate communication with the PowerShell Agent service and get information back from PowerShell to UCS Director.
Above is the screen that you are presented. You must provide these five objects whenever communicating with PowerShell Agent. As many of these are self-explanatory, I won’t go into basic details, but I will state that there are some nuances to the Commands/Script field. There are certain character sequences that you may have problems with, like “/” and “$”. The reason for this is that the PowerShell Agent is essentially running an Invoke-Command cmdlet with the remote PSSession and there are some nuances in sending special characters to that cmdlet that must be taken into consideration or your syntax is going to be off when remotely executing the command.
What I’m going to do here is show a quick example of how information is returned from the PowerShell Agent. In my lab, I have a device, called UCSD-PowerShell, that I’m going to run the simple cmdlet of Get-Host. This screen will show you what I filled out:
After clicking on the Execute button, I am told that my command completed successfully.
If I scroll down, I can see some formatted output of the response:
This appears to be the object information I would get from a Get-Host, with some of the PowerShell session information sprinkled in there.
To Be Continued
In the next post in this series, we will explore using these building blocks and creating a small UCS Director workflow that uses the Execute PowerShell Command task and what we can do with the response to use returned PowerShell object information in other UCS Director workflow tasks.