Cisco UCS Automation Series, Part I – Getting Started with UCS PowerTool

You WANT to Automate! But Where to Start?

You want to automate but not sure where to start or what tools to use or even what processes can be automated and if the thing you want to automate is even automatable. Does it offer an API? If it does, is there an SDK? Are there samples of what can be done? What has been done? How much can be done? A lot of questions typically bog down the process, mire you in indecision and eventually you give up!

Fortunately, if you have Cisco UCS in your Data Center you are already more than halfway to the serendipitous realization that automation is within your reach. How can I be so sure? I have been working with Cisco UCS servers for many years and I have watched the tools I use to automate evolve into powerful allies in my quest to manage my Data Center at the push of a button or by the sound of my voice.

Too frequently we think, “Oh it’s just a couple clicks, or a quick entry at the command line.” But really if you do something more than once you should automate it. Automation can provide consistency in outcome as well as more efficient issue mitigation. But the question still is how can you get started.

UCS PowerTool Suite

UCS PowerTool is a set of PowerShell modules engineered specifically for UCS Manager, UCS Central, and the Cisco Integrated Management Controller (CIMC) of stand-alone/rack-mount servers. UCS PowerTool provides literally thousands of Cmdlets to manage, monitor, migrate, and mitigate anything on your UCS systems. The fact is that if you can do something in a UCS GUI, you can do it with PowerTool.

I did say there are thousands of Cmdlets in the UCS PowerTool Suite. Let’s focus on just the UCS Manager PowerTool module. In the 2.3.1.5 release there are only 2,406 Cmdlets. That of course is a much more manageable number, right?… Just Kidding. The truth is there really is no way to know them all, or which one to use. But get this, you can ask UCS PowerTool to tell you which Cmdlets to use!

ConvertTo-UcsCmdlet

ConvertTo-UcsCmdlet is a specialized UCS PowerTool Cmdlet that will literally tell you how to configure a pool, policy, vlan, really any object in UCS Manager just by asking. It works a few different ways; however, the easiest way is outlined below.

◉ Create something in UCS Manager GUI or CLI, for example a Boot Policy that can be consumed by a Service Profile or Service Profile Template.
◉ Get the Boot Policy configuration from UCS Manager using the UCS PowerTool Cmdlet Get-UcsBootPolicy with the “-Hierarchy” parameter and send the output of Get-UcsBootPolicy to ConvertTo-UcsCmdlet
◉ ConvertTo-UcsCmdlet will output the Cmdlets and the required parameter settings to make the Boot Policy

That’s it! It is really that easy. Now if you want to, take that output and turn it into a script.  Then whenever you need that kind of Boot Policy on a UCS Manager you can just run the script when you are connected to the UCS Manager where you would like the Boot Policy.

Try It Out

Here is what the Boot Policy creation looks like in UCS Manager to boot from a local disk first, then a CD/DVD, then CIMC Mounted Virtual Media.

Create a Boot Policy

Here is the code that you would run in the UCS PowerTool Console to get the Boot Policy and then Convert it to UCS PowerTool Cmdlets. In the example the Boot Policy is named “Local-DVD-Virt”

Get-UcsBootPolicy -Name Local-DVD-Virt -Hierachy | ConvertTo-UcsCmdlet

Here is what the output of ConvertTo-UcsCmdlet looks like when Get-UcsBootPolicy is run to retrieve that boot policy and then piped to ConvertTo-UcsCmdlet.

ConvetTo-UcsCmdlet Output

This process removes the guesswork and also shows you a good UCS PowerTool practice of wrapping your configurations in a UCS Transaction.

This is the code that was generated

Start-UcsTransaction

$mo = Get-UcsOrg -Level root | Add-UcsBootPolicy -ModifyPresent -BootMode "legacy" -Descr "Local Disk then Local CD/DVD then Virtual Media" -EnforceVnicName "yes" -Name "Local-DVD-Virt" -PolicyOwner "local" -Purpose "operational" -RebootOnUpdate "yes"

$mo_1 = $mo | Add-UcsLsbootVirtualMedia -ModifyPresent -Access "read-only-local" -LunId "0" -MappingName "" -Order 2

$mo_2 = $mo | Add-UcsLsbootVirtualMedia -ModifyPresent -Access "read-only-remote-cimc" -LunId "0" -MappingName "" -Order 3

$mo_3 = $mo | Add-UcsLsbootStorage -ModifyPresent -Order 1

$mo_3_1 = $mo_3 | Add-UcsLsbootLocalStorage -ModifyPresent

$mo_3_1_1 = $mo_3_1 | Add-UcsLsbootLocalHddImage -ModifyPresent -Order 1

Complete-UcsTransaction

Is it Perfect?

*** UPDATE *** UPDATE *** UPDATE *** UPDATE *** UPDATE ***

Since this blog was published, a new version of UCS PowerTool was released on  November, 17th 2017  that fixes the issue described below. However, please remember the method described below in the event that you do run into an error or similar issue in the future.

*** UPDATE *** UPDATE *** UPDATE *** UPDATE *** UPDATE ***

As I stated earlier this process works with every UCS object. If you can “Get” it, you can create code for it.  In some cases, it is not a foolproof process. In fact, the code generated above with ConvertTo-UcsCmdlet will produce an error when it is run, but that’s OK because you just remove the part that created the error and try the generated code again.

To try the generated code, you would need to remove the existing object from UCS Manager or perhaps just change the name of that object, in this case you would change the -Name parameter of the Add-UcsBootPolicy Cmdlet

In the screenshot below the name of the boot policy has been changed to “test-boot-pol”. However, when running the code an error was generated indicating that the “-Purpose” parameter cannot be set because it is an “implicit” property. UCS Manager “implicit” properties are not able to be set by a user, even if that user is an “admin” user. “implicit” properties can only be set by an internal UCS Manager process. To remediate the error, remove the “-Purpose” parameter and its value from the line and retry the code.

Error running generated PowerTool Cmdlets

Start-UcsTransaction

$mo = Get-UcsOrg -Level root | Add-UcsBootPolicy -ModifyPresent -BootMode "legacy" -Descr "Local Disk then Local CD/DVD then Virtual Media" -EnforceVnicName "yes" -Name "test-boot-pol" -PolicyOwner "local" -RebootOnUpdate "yes"

$mo_1 = $mo | Add-UcsLsbootVirtualMedia -ModifyPresent -Access "read-only-local" -LunId "0" -MappingName "" -Order 2

$mo_2 = $mo | Add-UcsLsbootVirtualMedia -ModifyPresent -Access "read-only-remote-cimc" -LunId "0" -MappingName "" -Order 3

$mo_3 = $mo | Add-UcsLsbootStorage -ModifyPresent -Order 1

$mo_3_1 = $mo_3 | Add-UcsLsbootLocalStorage -ModifyPresent

$mo_3_1_1 = $mo_3_1 | Add-UcsLsbootLocalHddImage -ModifyPresent -Order 1

Complete-UcsTransaction

The screenshot below shows the working code with the “-Purpose” parameter removed.

Successful run of generated PowerTool Cmdlets

The power of ConvertTo-UcsCmdlet will help get you started automating UCS with PowerTool, and keep you automating UCS PowerTool. What could be easier than creating an object in UCS Manager and then having UCS PowerTool tell you how to create that object with UCS PowerTool.

See ConvertTo-UcsCmdlet in Action