Introduction to UCS PowerTool Part III Cisco DevNet Learning Labs

Overview

UCS PowerTool is a library of PowerShell Cmdlets that enable the management of UCS environments from Microsoft Operating Systems, via the UCS XML API.

Cisco UCS is an Integrated Compute Infrastructure that has supported an XML API since its introduction. UCS Manager is the service that provides the XML API endpoint along with a graphical interface and a command line. The UCS components both physical and logical are represented as XML objects in a hierarchical Object Model format and can be manipulated via the XML API.

All UCS objects are described in an XML schema, this schema defines the objects their attributes and associated values. The schema is also used to generate more than 98% of the UCS PowerTool Library. Because a UCS component must be part of the Object Model to be part of the UCS system all components of UCS are always available via the XML API.

Objective

This Introduction to UCS PowerTool Learning Lab will guide you through the use of UCS PowerTool to connect to a UCS Manager, perform queries against UCS Manager objects, create new objects, modify objects, generate PowerTool code from interactions in the UCS GUI and disconnect from the UCS Manager. UCS Manager Objects are representations of pools, policies, other logical constructs and physical entities.

Completion time: 30 minutes

Prerequisites

Prior to starting this learning lab it would be helpful to understand UCS Manager and the functionality that it provides to manage UCS compute environments.

An understanding of PowerShell would also be helpful.

UCS PowerTool

UCS PowerTool is a library of Microsoft PowerShell Cmdlets (pronounced command-lets) that enable the retrieval and manipulation of UCS Manager managed objects. UCS Manager API interaction can be categorized into several distinct sections.

Sessions
Methods
Queries and Filters
Configurations and Transactions
Event Subscription

UCS PowerTool provides services and cmdlets for all the categorizations of UCS Manager API interactions, along with cmdlets that allow for the inspection of object metadata, object hierarchical containment and object cmdlet action capabilities with pipeline object definitions.

UCS PowerTool cmdlets follow the same structure as PowerShell cmdlets (verb-noun) utilizing the defined Microsoft PowerShell Verbs. UCS PowerTool cmdlet nouns are the UCS objects. For example, to retrieve compute blade objects from UCS Manager, utilize the Get-UcsBlade cmdlet. The Get-UcsBlade cmdlet will retrieve all the UCS compute blade objects from all currently connected UCS Managers.

UCS PowerTool Download and Documentation

UCS PowerTool for UCS Manager is a component in the UCS PowerTool Suite. In addition to UCS Manager management capabilities in UCS PowerTool, there is also a cmdlet library for UCS Central and UCS IMC. UCS Central PowerTool library provides cmdlets to manage UCS Central, UCS Central is a manager of UCS Managers. UCS IMC PowerTool is a collection of cmdlets to manage the CIMC (Cisco Integrated Management Controller) component of the UCS C and E Series servers.

To use UCS PowerTool in your environment be sure to download and get the documentation.

Event Infrastructure Utilization

If you are utilizing event provided infrastructure a script has been provided to reset the environment to pre-lab settings.

On the desktop Double-click the Reset-Ucs-LL shortcut, provide the UCS Manager IP address that was assigned to you for the Learning Lab and hit Enter

Repeat this process for each assigned IP address, if you were assigned more than one.

Reset-Ucs-LL Icon:

Reset-Ucs-LL Console:

Exercise 1

Connecting to a UCS Manager has be done so far running the Connect-Ucs cmdlet and providing credentials in the credentials dialog. This is fine for interactive sessions but does not work for scheduled jobs, automation and orchestration tools or desired state configuration tools, including Microsoft's PowerShell powered DSC

There are a couple of methods for non-interactive login to UCS Manager. Connect-Ucs has a -Credential parameter that accepts a PowerShell credential object. Or Connect-Ucs can utilize a previous session's exported credentials as input.

Launch UCS PowerTool by double clicking the UCS PowerTool icon on the Desktop.

UCS PowerTool Icon:
Connect to the UCS Manager, at the command prompt type

Connect-Ucs -Name <ip-address-ucs-manager>

User: admin

Password: password

Connect-Ucs credentials dialog:
Create a directory, at the command prompt type

New-Item -ItemType Directory ucs-sessions

New-Item:
Export the current UCS PSSession, at the command prompt type

Export-UcsPSSession -Path C:\ucs-sessions\ucspe.xml

When prompted for a Key enter password

Then run a directory listing of C:\ucs-sessions dir C:\ucs-sessions

Export-UcsPSSession:

The file ucspe.xml was created in the sessions directory. The contentts will look similar to this
```
<basehandles>
<ucshandles>
 <ucs name="192.168.65.143" username="admin" password="UNfaLOSYLu9b1cAsPUWqhdy3KdT2EFgU8iHvq2Q95qA=" />
</ucshandles>
<imchandles />
<ucscentralhandles />
</basehandles>
```
Disconnect from the UCS Manager, at the command prompt type

Disconnect-Ucs
Connect to the UCS Manager using the exported sessions file, at the command prompt type

Connect-Ucs -Path C:\ucs-sessions\ucspe.xml

When prompted for a Key enter password

Connect-Ucs with exported sessions file:
Disconnect from the UCS Manager, at the command prompt type

Disconnect-Ucs

This is the end of exercise 1.

Exercise 2

The Connect-Ucs cmdlet when utilizing the exported sessions file also allows the -Key to be a parameter supplied on the command line. However it cannot be just a text string it needs to be a System.Security.SecureString, fortunately there is a cmdlet to make one of those.

Try to connect UCS Manger with a string for the -Key parameter, at the command prompt type

Connect-Ucs -Path C:\ucs-sessions\ucspe.xml -Key password

View the error

Connect-Ucs : Cannot bind parameter 'Key'. Cannot convert the "password" value of type "System.String" to type
"System.Security.SecureString".
At line:1 char:50
+ Connect-Ucs -Path C:\ucs-sessions\ucspe.xml -Key password
+                                                  ~~~~~~~~
+ CategoryInfo          : InvalidArgument: (:) [Connect-Ucs], ParameterBindingException
+ FullyQualifiedErrorId : CannotConvertArgumentNoMessage,Cisco.Ucsm.Cmdlets.ConnectUcs

Try converting the string password to a SecureString at the command prompt type

Connect-Ucs -Path C:\ucs-sessions\ucspe.xml -Key $(ConvertTo-SecureString -String "password" -AsPlainText -Force)

Connect-Ucs with exported sessions file and Key:

That worked, the $() causes the password to be converted to a SecureString before it is passed as the -Key
Disconnect from the UCS, at the command prompt type

Disconnect-Ucs
Create a Microsoft PowerShell Credential object. First step is to create the SecureString, at the command prompt type

$ucs_passwd = ConvertTo-SecureString "password" -AsPlainText -Force
Next create the credential object with the UCS Manager user name and the SecureString password, at the command prompt type

$ucs_creds = New-Object System.Management.Automation.PSCredential ("admin", $ucs_passwd)
Connect to UCS Manager with the PSCredential object, at the command prompt type

Connect-Ucs -Name <ip-address-ucs-manager> -Credential $ucs_creds

Connect-Ucs with PSCredential

The SecureString used with an exported UCS PSSession makes using any kind of system information available as a key. For example you could use a system name as the key so that only a specific system can login to the UCS Manager.

This is the end of exercise 2.