Cisco UCS Automation – Part 2: A Step-by-Step Guide to Connecting and Disconnecting using UCS PowerTool

Let’s Connect

What’s the hardest part about meeting someone new or going to another country or just interacting with something you are unfamiliar with? Typically, it’s how to start the interaction, how do you connect, stay connected, and reconnect. Sometimes the relationship or the place just doesn’t work out and then you have to leave or disconnect.

I think you probably already know that I’m not going to be talking about personal relationships or travel, but interacting with Cisco UCS Management interfaces via UCS PowerTool. In my previous blog I wrote about getting started using UCS PowerTool for automation, this blog is all about Connecting and Disconnecting. Could there really be that much information about connecting and disconnecting? You bet, let’s get started.

Simple Connect and Disconnect

Connecting to the three available UCS Management interfaces is pretty straight forward, use the appropriate “Connect” Cmdlet and provide one or more IP addresses or DNS names for the UCS Management interface(s) that you would like to connect to.

Connect-Ucs -Name <ucsm-ip or dns-name, ucsm-ip or dns-name, ...>
Connect-UcsCentral -Name <ucsc-ip or dns-name, ucsc-ip or dns-name, ...>
Connect-Imc -Name <cimc-ip or dns-name, cimc-ip or dns-name, ...>

Disconnecting is even easier, just use the appropriate “Disconnect” Cmdlet and all the existing connections will be dis-connected.

Disconnect-Ucs
Disconnect-UcsCentral
Disconnect-Imc

When connecting to UCS Manager, UCS Central or a CIMC (Cisco Integrated Management Controller), by default only a single connection to a single interface is supported and is referred to as the “Default” connection. A variable will be created in the UCS PowerTool session to hold the connection information, these variables respectively are named,

$DefaultUcs
$DefaultUcsCentral
$DefaultImc

Connect To UCS Manager

Contents of $DefaultUcs and Disconnect from UCS Manager

After a “Disconnect” Cmdlet is run, the respective variable, if empty, will be removed from the environment. I said “if empty” because by default only a single connection to a single UCS Management interface per UCS PowerTool session is supported, you can however connect to more than one UCS Management interface, but first you just have to tell UCS PowerTool that is what you want to do.

Connect to Multiple UCS Management Interfaces

If you attempt to make a second connection to the same UCS Management interface or to another UCS Management interface an error is returned indicating that multiple default UCS (in this case) is not allowed by configuration.

The Set-UcsPowerToolConfiguration Cmldet allows you to set the Ucs PowerTool session to support multiple default configurations. The Set-UcsPowerToolConfiguration Cmdlet is the same Cmdlet for each PowerTool suite.

To view the current settings for UCS PowerTool Configuration, run the Get-UcsPowerToolConfiguration Cmdlet. To support multiple connections set the SupportMultipleDefaultUcs parameter to $true

Get-UcsPowerToolConfiguration

Set-UcsPowerToolConfiguration -SupportMultipleDefaultUcs $true

Set-UcsPowerToolConfiguration

With the SupportMultipleDefaultUcs parameter set to $true you can connect to more UCS Managers, UCS Centrals, or CIMCs, and where does that connection information get stored? In the $DefaultUcs, $DefaultUcsCentral, or $DefaultImc variables respectively.

Then when running the respective “Disconnect” Cmdlet all the sessions stored in the $Default variables with be disconnected. You can also specify which connection you would like to disconnect.  The $DefaultUcs, $DefaultUcsCentral, $DefaultImc variables are PowerShell array type variables if you know the specific connection that you would to disconnect you can specify it using PowerShell array notation and Named UCS connections (covered a little further down).

What Does it Mean to be Default?

What does being the “default” connection mean? It means that when a Cmdlet is run and a specific connection is not specified then the Cmdlet is run against all the $Default connections. For example, if there are two “default” connections to two different UCS Managers and the Cmdlet Get-UcsBlade is run, the Cmdlets will be run in parallel retrieving blade information from both UCS Managers at the same time. UCS PowerTool associates the source UCS Manager, UCS Central or CIMC as an attribute to the returned objects. Using this attribute you can determine where the source of the returned object.

For example running Get-UcsBlade while connected to two UCS Managers and selecting the object attributes; Dn, TotalMemory, NumOfCpus, Ucs. Produces output indicating the source UCS Manager of the returned objects.

Get-UcsBlade | Select-Object Dn, TotalMemory, NumOfCpus, Ucs

Get-UcsBlade | Select-Object Dn, TotalMemory, NumOfCpus, Ucs

The “default” connection is used when a specific connection is not specified. When running the Connect-Ucs, Connect-UcsCentral, or Connect-Imc Cmdlets the connection information can be saved to a variable and excluded from the respective “Default” connections variable.

$ucsm_connections = Connect-Ucs -Name <ucsm-ip or dns-name, ...> -NotDefault

$ucsc_connections = Connect-UcsCentral -Name <ucsc-ip or dns-name, ...> -NotDefault

$cimc_connections = Connect-Imc -Name <cimc-ip or dns-name, ...> -NotDefault

When saving the UCS connection information to a variable no output is returned to the console and the $DefaultUcs variable is not just empty, it does not exist in the session! Now when running a UCS PowerTool Cmdlet to specify the UCS Management interface use the connection specification parameter. For example using the previously shown Get-UcsBlade Cmdlet

Get-UcsBlade -Ucs $ucsm_connections | Select-Object Dn, TotalMemory, NumOfCpus, Ucs

Specific connection variables can be an array of connections so the result of running a Cmdlet against a specific connection can be the same as running a Cmdlet using the “default” connection. What’s the difference? Using the “default” connection variables allow you to not worry about specifying a connection parameter for each UCS PowerTool Cmdlet where the specific connection can allow for a finer grain of control. My advice, is to use what works for you.

That Pesky Credentials Dialog Box

Connecting to a single UCS Management interface one time, multiple times, or to multiple UCS Management interfaces one time, or multiple times are all supported. However, that pesky dialog box asking for credentials keeps popping up. How can that be suppressed when you are automating? The Microsoft PS Credential object is the way to go to achieve full non-interactive automation capabilities.

$ucsm_credentials = New-Object -TypeName System.Management.Automation.PSCredential

                    -ArgumentList “username”, 

                    $(ConvertTo-SecureString -Force -AsPlainText “password”))

Create A Microsoft PSCredential Object

Let’s breakdown what is going on

◉ ConvertTo-SecureString is run on the “password” and produce a SecureString.

◉ New-Object is used to create a System.Management.Automation.PSCredential object

◉ The PSCredential object is populated with the supplied “username” and the “password”

     ◉ Both the “username” and “password” strings in this example can also be variables

◉ The new PSCredential object is stored in the $ucsm_credentials variable

To use the $ucsm_credentials (PSCredential object) variable when connecting to an endpoint just specify it using the -Credential parameter of the respective UCS PowerTool “Connect” Cmdlet. Using the -Credential parameter does not limit the functionality of the “Default” or -NotDefault options.

Connect-Ucs -Name <ucsm-ip or dns-name, ...> -Credential $ucsm_credentials

Connect-UcsCentral -Name <ucsc-ip or dns-name, ...> -Credential $ucsc_credentials

Connect-Imc -Name <cimc-ip or dns-name, ...> -Credential $cimc_credentials

Alternate Connection Capabilities for IMC PowerTool

There is a bit of alternate “Connect” functionality available with the Connect-Imc Cmdlet via two additional parameters, -FromIp and -ToIp. All the “Connect” variations still apply, “Default”, -NotDefault, -Credential

$cimc_connections = Connect-Imc -FromIp 10.10.10.10 -ToIp 10.10.10.30 -NotDefault

Connect-Imc FromIp ToIp

View and Save Connections for Another Time

Now that you are connected in whatever way you have chosen to connect; wouldn’t it be great if there was a way to easily “Get” information about all your connections and perhaps even a way to “Export” all your connections and then use that export to quickly re-connect all those connecitons at another time? Awesomely there is, through the use of the these two UCS PowerTool Cmdlets

Get-UcsPsSession

Export-UcsPsSession -Path .\ucs-sessions.xml -Key $(ConvertTo-SecureString -AsPlainText "password" -Force)

Get-UcsPsSession will list all the UcsPsSession objects contained in the $DefaultUcs, $DefaultUcsCentral, or $DefaultImc variables respectively or the session information stored in a variable like $cimc_connections using the -Ucs parameter

Export-UcsPsSession will export to the specified file an XML encoded list of all your connections. When using Export-UcsPsSession you must provide a “Key”. This “Key” will also be needed when using the exported sessions as input to the “Connect” Cmdlets. You can export sessions stored in a variable like $ucsm_connections using the -Ucs Parameter

To export the connected sessions

Export-UcsPSSession -Path .\ucs-session.xml -Key $(ConvertTo-SecureString -Force -AsPlainText "password")

<basehandles>

  <ucshandles />

    <imchandles>

      <imc name="10.10.20.10" username="admin" password="+7VRmPxpy3ujd2CvMzw6PAd3TbGobzJHq4rqNuieCpk=" />

      <imc name="10.10.20.20" username="admin" password="TMZsoRk1zk3A3BCPUAJ8+ILP9LHo5ommYmlyJTb8JbE=" />

      <imc name="10.10.20.30" username="admin" password="QfL+wn3QGgFZu2HjIcjef28z2/SV4DwAN1jM2FXsRH0=" />

    </imchandles>

  <ucscentralhandles />

</basehandles>

To utilize the export connection sessions

Connect-Ucs -Path .\ucs-session.xml -Key $(ConvertTo-SecureString -Force -AsPlainText "password")

The “Key” could be almost anything, perhaps a piece of information local to the machine running UCS PowerTool or something that can be gleaned from the Network or another host.

Export-UcsPsSession

Connect-Ucs using output from Export-UcsPsSession

Don’t Let Anything Come Between Us

Sometimes when working in a corporate environment there is a Proxy between you and the UCS Management interface, we have that aspect covered in UCS PowerTool as well. The “Connect” Cmdlets all support a -Proxy parameter that takes as input a Microsoft System.Net.WebProxy object

$proxy = New-Object System.Net.WebProxy

$proxy.Address = "http://<url>:<port>"

$proxy.UseDefaultCredentials = $false

$proxy.Credentials = New-Object System.Net.NetworkCredential("username","password")

Connect-Ucs -Path .\ucs-connections.xml -Proxy $proxy

It’s Not You(s) It’s Me! We Can Still be Friends

One final note about the “Disconnect” Cmdlets. All of the “Disconnect” Cmdlets will by default disconnect all the UcsPsSessions stored in the $DefaultUcs, $DefaultUcsCentral, or $DefaultImc variables respectively. You can use the -Ucs, -UcsCentral, -Imc parameter of the respective “Disconnect” Cmdlets to specify a specific single connection or an array of connections.