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
enterpassword
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
enterpassword
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 typeConnect-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 aSecureString
at the command prompt typeConnect-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 thepassword
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.