One of the announcements during VMworld 2010 in San Francisco that perhaps got a bit obscured by the other “big” announcements, was the release of Onyx 2.0. For those of you that hadn’t heard of Project Onyx before, this nifty little tool captures all SOAP traffic that is passed between your vSphere client or PowerCLI session and the vCenter or ESX(i) server to which you are connected.
And that’s not all, the Onyx program will translate the captured SOAP traffic into PowerShell code. This allows you to see which vSphere APIs are used and how parameter objects for these methods are constructed.
Update September 16th 2010: the Onyx Development Team has just released a new build (2.0.3910.32223) that fixes some issues when using Onyx with the PowerCLI client. Congratulations to the Onyx Development Team for this quick resolution of the problem !
What’s new ?
The new Onyx 2.0 has a lot of new features and several improvements for older features.
- Onyx 2.0 supports vSphere 4.1! In other words all new APIs, that were introduced with vSphere 4.1, are captured and shown correctly in the produced output.
- A simple, but very user-friendly, feature is that Onyx 2.0 allows you start the vSphere client or PowerCLI session directly from the Onyx Gui.
- The vSphere client makes a lot of obvious API calls which are probably not important for the action you’re trying to capture. A good example is the continous use of PropertyCollector calls to refresh the values on the vSphere client screens. If you don’t want to obfuscate the resulting script with these calls, it’s now quite easy to suppress them. From the Onyx Gui you open the Settings menu and specify which methods should be ignored.
Using Onyx is quite simple!
Unfortunately the instructions on the VMware LABS Onyx page still seems to contain the Onyx 1.0 instructions.And although they are still valid, the usage of Onyx became a lot easier.
When you start the program you are presented with the main screen.
Top-left in the toolbar you find the Connect button that allows you to set up the connection to the vCenter or ESX(i) server for which you want to capture the actions.
There is also a History option (the list box) that allows you to choose, by default, from your last 10 connections.
The next window will ask you to which vCenter or ESX(i) server you want to connect.
With a new connection, you also have the option to automatically start the vSphere client or the PowerCLI client. Just enter your credentials and Onyx will take care of starting the client and setting up the connection.
And now the fun begins!
To start translating all your actions in the client into PowerShell code you hit the Start button in the toolbar.
Let’s have a look at a simple example. We’ll add 1 vCPU and a NIC to a guest in the vSphere client.
We immediately see the PowerShell code the Onyx program generated. Small remark, the colours in the output were done by me to better show the different parts of the generated code !
With the help of the SDK Reference it is now quite easy to find back what each part of the generated code is doing.
The action we did in the vSphere client obviously uses the ReconfigVM_Task method which requires one parameter, a VirtualMachineConfigSpec. In this VirtualMachineConfigSpec there is the numCPUs property that permits the caller to define the number of vCPUs. And additionally there is the VirtualDeviceConfigSpec object that takes care of the virtual HW, in this case the new NIC.
Notice how the object type that is entered in the device property, depends on the type of HW that was chosen. In this case the new NIC was specified as a vmxnet3 type card.
Also note that the generated code uses the actual MoRef to get the VirtualMachine object. This is not considered good coding practice. So if you are going to use the generated code, make sure you fetch the guest based on it’s name. Something like this:
$_this = Get-VM -Name "PC1" | Get-View
One of the exciting new features in Onyx 2.0 is its ability to generate different types of output.
There is the raw SOAP.
And there is C#, which SDK developers will surely appreciate.
What is also a definite improvement compared to Onyx 1.0, is the fact most of the settings are now accessible via the Settings button in the toolbar.
There are two settings that I particularly like.
One is the option were you can easily specify which of the methods shall be ignored by Onyx. In other words which of the methods you don’t want to see in the generated output.
The other one is the obfuscation feature. This allows you to suppress sensitive information from the generated output and/or the log.
Room for improvement
The new Onyx 2.0 definitely is a more user-friendly and robust application than it’s predecessor. But while using the product there are some features that seem to be missing or that would make the product even better.
What follows is a “personal” list of notes I took while test driving the product.
- “Start a new Connection” has a “Launch Client when connected” option, which is great! But the Username and Password have to be entered each time. It would have been handy if there was something like the “Use Windows session credentials” option like the vSphere client has.
- The Connect button in the Onyx toolbar has a “History” option where you can chose any of the previous connections you made in the past. Unfortunately the “History” doesn’t keep track of the client with which you connected, neither does it allow you to specify a client to connect.
- The Connection history is kept in the Onyx.settings file, which is in fact an XML file. When you want to remove one of these old connections, you will have to edit the Onyx.settings file. It would have been handy to have this option available under the Settings option.
- The “Launch Client when connected” option is a great new feature. It would have been useful if it allowed the user, in the Settings perhaps, to add additional clients. I’m thinking of the PowerGui, vEcoShell, PowerShellPlus… users.
- The raw SOAP output only shows the request packets, not the reply packets. From the log it is obvious that this information is available. Perhaps it could be a useful feature to allow for the selection of the reply packet in the raw SOAP output.
Don’t let it be misunderstood, Onyx 2.0 is a product that you need when you take automation through PowerCLI serious. A product that you should know and use in your vSphere environment.
- It will help you understand what goes on under the hood.
- It will make it easier to find which methods and objects to use for those functions that are not yet covered by a PowerCLI cmdlet.
Download Onyx 2.0 and start playing!