It's been a very successful VMWorld this year, especially for PowerCLI – lots of sessions and a great lab. For the first time this year we had a scenario-based lab – migrating a vSphere 4 environment to vSphere 5. For those of you that were unable to attend the lab during the event – be sure to check the attached lab manual and scripts below. We hope to see you at the event next year!
Download PowerCLI lab manual 2011
PowerCLI 4.1.1 introduces the new Get-EsxTop cmdlet. This cmdlet provides functionality similar to the “esxtop” utility. The cmdlet allows you to access a wide variety of stats for your virtual environment – thus allowing you to create even more versatile reports using PowerCLI.
There are 3 types of data returned by the cmdlet – counter information, topology information, and statistical data. The counter information shows you the available counters on your ESX as well as their properties (metadata information). To list all available counters you can simply do:
Get-EsxTop –Counter
# View the fields available for VCPU counter:
(Get-EsxTop –Counter –CounterName VCPU).Fields
The topology information contains either inventory data that does not change (e.g. physical CPU information) or a counter instance structure describing the relationship between different counters. To list all available topologies, run:
Get-EsxTop –TopologyInfo
# View the entries of a specific topology:
(Get-EsxTop –TopologyInfo –Topology SchedGroup).Entries | Format-Table
Finally the statistical data gives you the actual values for the available counters:
# Retrieve the counter values for “VCPU” and “SchedGroup” counters:
Get-EsxTop –CounterName VCPU | Format-Table * -AutoSize
Get-EsxTop –CounterName SchedGroup | Format-Table * -AutoSize
You can use these three sources to navigate the esxtop information and build your reports.
Get-EsxTop works on ESX 4.0 or newer. The cmdlet is dynamic in its nature, meaning that the returned values may differ between ESX versions and the actual data returned is appended as PowerShell dynamic properties to the output objects. Please note that the cmdlet is currently experimental and its output may change in future PowerCLI versions.
There are certain events in life that we all strive to avoid, yet they seem practically inevitable. Facing problems, when using some software product is one of those. And using PowerCLI and vSphere makes no exception. Occasionally, you will stumble upon a configuration, environment, or a PowerCLI/vSphere problem itself. This article shows how you can effectively report the problem to VMware. You will need this if cannot solve some problem yourself and need outside help or just want to inform VMware about the problem so they can fix it at some later point.
Reporting a problem with PowerCLI is easy. What you have to do is generate a diagnostic bundle with the Get-ErrorReport cmdlet and send it to VMware (or someone else with enough expertise on PowerCLI). There are 2 main scenarios for reporting the problem. The first is sending the bundle to VMware tech support (if you have a tech support account). The second is to post it in the PowerCLI community forum (http://communities.vmware.com/community/vmtn/vsphere/automationtools/powercli), attach the bundle to your post, and wait for someone to take a look at it.
Here is the online documentation of the cmdlet: http://www.vmware.com/support/developer/PowerCLI/PowerCLI41/html/Get-ErrorReport.html.
Get-ErrorReport has the following signature:
Get-ErrorReport
-ProblemScript is the Powershell script that reproduces the problem. Get-ErrorReport executes this script and captures all the actions caused by it, so someone at VMware can be able to analyze them later.
-ProblemScriptTimeoutSeconds is the time limit in which the script must finish execution. If the script exceeds this time limit it’s considered an error. This parameter is needed because Get-ErrorReport cannot know what time an arbitrary script should take, so it cannot know if the script has blocked or is still operating as expected.
-ProblemDescription is your description of the problem you observed. It should be as specific as possible. It should describe what the erroneous behavior is and what the expected behavior is.
-Destination is the directory where you want to save the diagnostic bundle. It’s a .zip file.
-DontIncludeServerLogs specifies if vCenter logs should be captured as well. If this switch parameter is not set, the cmdlet will extract the vCenter logs + the logs of all ESX servers managed by the vCenter. This is quite a slow operation and will increase the size of the diagnostic bundle dramatically. Including vCenter logs is useful if the problem you’re reporting is on the vCenter/ESX side. So it’s better to set this parameter if you report a PowerCLI-specific problem.
Let’s see some examples now.
Example 1.
Let’s say you have a problem moving a virtual machine from one host to another. You can assign the script that moves the virtual machine to a variable and pass it to Get-ErrorReport.
Example 2.
Let’s say you want to connect to a server and retrieve the virtual machines but the operation hangs. Again, you can create the script that gets the virtual machines and pass it to Get-ErrorReport, specifying that you expect that the script should take no longer than 60 seconds to finish. Let’s assume you also want to include the vCenter logs in the report.
Now you know how to record diagnostic information that will help someone with PowerCLI expertise understand your problem (and hopefully provide a solution). This someone will probably be VMware tech support (for those of you who have a tech support account) or the PowerCLI community forum where someone from VMware or the community can hopefully take a look at it.
Surely, some of you are curious about the contents of the diagnostic bundle. You can take a look yourself by unpacking the .zip file. Here is the list of the types of information the support bundle includes:
– The problem description that the user has supplied
– The PowerCLI version and configuration
– The script that reproduces the error
– The output objects of the script that reproduces the error
– A snapshot of the Powershell session state before and after the script execution. This snapshot includes all the Powershell variables and their values (the contents of the PSCmdlet.SessionState object).
– All the Soap communication messages between PowerCLI and the vCenter/ESX it’s connected to;
– [Optionally] The vCenter logs.
PS. Any information that is previously known to be sensitive (like passwords used when authenticating to the server) is not included in the diagnostic bundle. But, note that if you have a clear-text password stored in a Powershell variable – it will go in the log, since there is no way for Get-ErrorReport to know that some arbitrary variable contains a password.
Best regards,
– Angel Evrov, MTS at VMware
Complex scripts need to handle errors and resolve common error scenarios without user interaction. A step in that direction is exposing the entire specter of vCenter server error hierarchy along with PowerCLI specific exceptions (for example when validating input parameters).
This improvement makes possible to write scripts which handle expected errors and deal with them as it’s shown below:
In addition to this feature the full exception chain is available in the error records as inner exception. So if the error is PowerCLI specific exception, the inner exception can be used to get the underlying vCenter Server error.
Thanks to that you can easily tune your script to check the returned by the server NoDiskSpace MethodFault and deal with it specifically.
VM customization is a very powerful feature that can make miracles during the deployment process. Since vSphere PowerCLI 4.0 U1, you can use cmdlets to modify a number of network settings of the newly created virtual machines. Here is how to do it:
Regards,
Nedko Nedev
Member of PowerCLI Dev Team
PowerCLI has several cmdlets that work inside the guest of a VM:
These cmdlets are script-based and this makes them user-customizable. By default, they are supported on Windows (XP, 2003) and RedHat 5 guest operating systems. But if you want to execute the cmdlets on a different guest OS, you can extend their guest OS support either by modifying the existing scripts, or by adding your own ones. The scripts are located in the PowerCLI installation folder: “<Install_Folder>\Scripts”.
The script names follow this convention: <operation_identifier>_<guest_OS_identifier>[.bat]. The operation identifier is “GuestDiskExpansion” for Set-HardDisk and the cmdlet name (without dash between verb and noun) for the VMGuestNetworkInterface and VMGuestRoute cmdlets (e.g. “GetVmGuestNetworkInterface”). The OS identifier should be either an OS family (e.g. “WindowsGuest” or “LinuxGuest”) or a specific OS version – guest id (e.g. “winXPProGuest”). You can see the guest id using Get-VMGuest cmdlet. The script extension must be “.bat” for Windows scripts and must be omitted for Linux scripts.
When you pass a collection of VMs to one of these cmdlets, the cmdlet checks the guest OS and chooses the most appropriate script for each VM. In short, this is how it works: PowerCLI searches for a script for the specific guest id (specific OS version) of the VM and if there is such a script – it uses it; if no such script is found – PowerCLI checks for a script that matches the guest OS family and uses it. In this way, you can have a specific script for a specific OS (e.g. Windows 7) and use the common OS family script (e.g. Windows) for all other OS versions (e.g. XP, 2003).
Each script receives its parameters in a specific order and must also print its output in a specific format. Each predefined script contains a comment at the beginning which describes the expected parameters and output. You can either modify the existing scripts or write new ones (e.g. for a specific OS version). Either way you need to ensure that the script handles the expected parameters and prints the expected output – only then the cmdlet will be able to use the script.