Archive

Posts Tagged ‘vi java api’

VMware vSphere Fault Model and Common Faults

May 24th, 2010 No comments

A fault is like an exception in Java or another modern programming language. It’s a data structure that holds information about an exceptional situation. Most of the faults are raised by the server; you can normally determine the cause from their fault names.

Close to 300 fault types are defined in the vSphere API. Let’s look at the top level hierarchy shown as follows.

 

The supertype for all faults is MethodFault. It is extended by InvalidCollectorVersion, InvalidProperty, RuntimeFault, and VimFault. The first two faults are not further extended to any other fault types.

Categories: vSphere API Tags: ,

Innovation, Openness, Community: Celebrating 2nd Anniversary of vSphere Java API

May 21st, 2010 No comments

It’s been two years since the first release of VI Java API on May 22, 2008. As of today, this VMware sponsored open source API has been downloaded more than 8,200 times including 1,000+ direct access to the source code from SVN. More importantly, the API has been widely adopted by VMware Community including partners and customers in their products and operation environment. I was amazed to hear success stories from companies which use this API to manage 10,000 servers.

Besides Java, people also started to use JVM languages such as Jython and Groovy to leverage the API. I think that is the direction for the API to be used by system administrators who look for an alternative to vSphere PowerCLI which is a great product with no choice but on Windows only.

How Was It Started?

The API was started because of my personal experience while helping VMware strategic partners. I found the Web Services SDK hard to use, and related samples hard to follow because of the procedural nature of Web Services. So I started to think how to solve the problem. During March and April 2008, I wrote code every night on my old Compaq notebook after helping my kid to sleep at night.

Categories: vSphere API Tags:

VMware vSphere PowerCLI Alternative on Linux?

May 17th, 2010 3 comments

After creating a light virtual appliance last year, Timo Sugliani continued with a full fledged version of virtual appliance with all you need for vSphere development with Java and Jython. This is what Timo called “my linux powershell toolkit.” The biggest advantage is that you are no longer limited by Windows as your development platform.

How to Fix Task Timeout in vSphere?

May 11th, 2010 No comments

Task management is an important part of vSphere API. It enables asynchronous calls by returning a Task back before the work is actually done at the server side. If a task takes too long (for example, more than 15 minutes to create a virtualmachine snapshot from VirtualCenter), however, it can time out before it finishes. It means you lose tracking of the task.

You can easily fix this issue by changing the configurations. On the ESX server, add the following to the /etc/opt/vmware/vpxa/vpxa.cfg file:

<task>
<timeout>7200</timeout>
</task>

and

<vmomi>
<soapStubAdapter>
<blockingTimeoutSeconds>7200</blockingTimeoutSeconds>
</soapStubAdapter>
</vmomi>

Remember to restart the service:

Categories: vSphere API Tags: , ,

Attention Administrators: vSphere Java API is for You too!

May 10th, 2010 No comments

Most people have the perception that vSphere Java API is for developers. It’s true but actually more than that. Administrators can take advantage of it as well.

Today, William Lam (@lamw) posted a Java version of his vdf tool which was originally written in Perl. For people don’t know William yet, he is a system administrator at Salesforce.com now and Yahoo before. He created and maintains the famous vGehtto script repository that almost every VI Perl developer knows about. William is also a vExpert and the No.1 contributor to the VMware developer community. Having not touched Java for 4+ years, William got his first HelloVM with VI Java API working in less than 5 minutes, and got the code converted in about one hour.

Categories: vSphere API Tags: , , ,

4 Rules for Converting Onyx Generated Code

May 5th, 2010 No comments

VMware PM Carter Shanklin (@cshanklin) once gave a great presentation on how to use Onyx with Java development at PEX 2010. I covered it briefly in a previous blog, and left out the “4 rules” hoping Carter would help.

As many of you have already known, Carter moved on to SpringSource division as the PM for tc server. So he has been pretty busy with his transition. With his coverage on both administrator and developer oriented products, he is right on the wave of devops movement. Make sure you follow him at Twitter.

Categories: vSphere API Tags: , ,

Tutorial: Easy vSphere Web Apps with Grails and the VI Java API

May 3rd, 2010 No comments

In a previous post, I blogged about a tutorial on using the open source VI Java API in Groovy by Aaron Sweemer. Two weeks later, he wrote a new tutorial Easy vSphere Web Apps with Grails and the VI Java API.

In his new tutorial, Aaron introduced detailed steps in how to use the VI Java API for a simple web application with Grails framework. The web application displays a web page that lists all the virtual machines with the corresponding guest OS names and whether they support multiple snapshots.

Categories: vSphere API Tags: ,

Really Easy Way to Clone a Session: Yet Another Contribution from NetApp

April 26th, 2010 1 comment

Recently there were questions in the vSphere Java API forum on how to clone a new session from an existing one. Although vSphere Java API wraps around the basic Web Services API cloneSession() method, simply calling the method doesn’t get what you want.

Why? The signature of cloneSession() is as follows. It returns UserSession, which is embedded inside ServiceInstance managed object in vSphere Java API. While using the API, you always starts from the ServiceInstance.

public UserSession cloneSession(String cloneTicket) throws InvalidLogin, RuntimeFault, RemoteException;

In vSphere Java API, the ServiceInstance and UserSession have one to one mapping. Without a new ServiceInstance around the new UserSession, the UserSession is not much helpful.

Luckily, we got yet another contribution from Eric Forgette who works at NetApp. The contributed code includes a new overloaded method cloneSession() method to return a ServiceInstance object.

As I described before, we’ve been trying very hard to keep the vSphere Java API as close to the basic Web Services as possible. In this case, we decided to break the rule a little bit for good reasons, mainly for usability.

Categories: vSphere API Tags: ,

Tutorial: Easy VMware Development with VI Java API and Groovy

April 20th, 2010 5 comments

Every time I google for VI(vSphere) Java API, I get something new. Here is yet another one I just found. It’s a blog article Easy VMware Development with VI Java API and Groovy by Aaron Sweemer. By reading his blog site, I came to know Aaron is actually my colleague at VMware working as a Sr. System Engineer in Cincinnati Ohio. He is the principal blogger at Virtual Insanity.

Invalid property? A Trick With vSphere PropertyCollector

April 14th, 2010 9 comments

As I discussed extensively in my book, the PropertyCollector is very powerful yet not easy to use. There was a question posted at vSphere Java API forum related to the property collector which I think worths sharing here. Although it’s found using vSphere Java API, but it really goes beyond the API to the vSphere API itself.

Virtual Machine, IP Address, and MAC Address: Frequently Confused Concepts

April 13th, 2010 22 comments

Having answered many questions about IP addresses of virtual machines at different occasions, I still see more are coming. I think it’s time to write a blog about it. Hopefully people would search the Internet before raising the question.

First of all, there is a big confusion on the relationship of IP addresses and virtual machines. Many people tend to associate IP addresses with virtual machines, and want to retrieve/change the IP address of a virtual machine.

In fact, a virtual machine is very much like its physical counterpart. It does not have an IP address by itself. In other words, an IP address is NOT an intrinsic attribute of a machine, either virtual or physical. It might have one or more only after an OS is installed. In most cases, it does have one or more IP addresses, which gives the impression that every machine has an IP address.

A virtual machine does have intrinsic attributes such as MAC addresses if NIC cards are configured. Unlike its physical counterpart, a virtual machine’s MAC address can be re-configured. Some software vendors rely on MAC addresses to lock down their licensed software on particular machines. This mechanism can be, therefore, compromised in virtual environments.

Video on vSphere Java API Released at InfoQ

April 9th, 2010 2 comments

While searching Twitter on “vSphere Java”, I found my presentation available today online at InfoQ (many thanks to @arm1433 and @toya256ForRSS). It has both video and slides for more than one hour. The voice was not quite clear in the first one or two minutes. After that it’s pretty good.

This presenation is a complete overview of the open source vSphere Java API. Because the audience then was new to virtualization, the first several minutes covered a little virtualization basics. You can scroll over if you know virtualization already.

Categories: vSphere API Tags: ,

How to Import and Export OVF Packages

April 7th, 2010 110 comments

This article is based on a similar one at vSphere Java API home page. At that time, one of VMware community members sent me an email for samples of using OvfManager APIs. Then I went to office on a Saturday writing two samples, which have been validated by several folks as “working” samples.

The purpose of the samples are to illustrate the vSphere APIs. Let’s take a look at them one by one.

First, ExportOvfToLocal.java. This sample shows how to download either a VM or vApp to your local machine. The typical flow is:

  • Find the VM or vApp
  • Call their exportVm() or exportVApp() methods and get HttpNfcLease
  • Set lease time out
  • Wait for HttpNfcLease until it’s ready
  • From the HttpNfcLease.info property, find the all URLs from which you download the vmdk files
  • Call OvfManager.createDescriptor() API to create the content of ovf and save it to a file along with downloaded vmdk files.
  • Release the lease by calling httpNfcLeaseComplete() method
Categories: vSphere API Tags: ,

Introducing Security Model of VMware vSphere

April 1st, 2010 2 comments

This article introduces you the basic model and terminologies in vSphere security management, for example, privileges, permissions, roles, and how they are related to each other to secure vSphere. It helps you to better manage the vSphere and program the vSphere API. Much of the content is based on my book VMware VI and vSphere SDK by Prentice Hall.

In vSphere, the security model consists of three types of components: privileges, roles, and permissions.

Privileges

A privilege is the basic individual right required to perform an operation. It is statically defined and never changes in a single version of a product. Given the many operations in VI, there are many privileges (for example, the privilege to “power on a virtual machine”). These privileges are represented as strings separated by dots, such as VirtualMachine.Interact.PowerOn.

The operations and privileges are not one-to-one mapping. Many operations do share common privileges like System.View. Therefore, there are many fewer privileges defined than methods. In some exceptional cases, a method requires different privileges depending on the target it operates on and the nature of the operation. The CloneVM_Task() method, for example, requires VirtualMachine.Provisioning.Clone for cloning from one virtual machine to another, VirtualMachine.Provisioning.DeployTemplate for cloning from a template to a virtual machine, and so on.

Roles

The role groups privileges from a user’s perspective. A role is normally named and defined for a group of people who have common responsibilities in the system (for example, administrators). Each role can include zero to multiple privileges. The extreme cases are the predefined “Admin” roles, which by default, includes all the privileges and the NoAccess role, which includes no privileges.

Categories: vSphere API Tags: ,

Fundamentals of vSphere Performance Management

March 31st, 2010 9 comments

Performance monitoring is a critical aspect of vSphere administration. This article introduces you the basic concepts and terminologies in vSphere performance management, for example, performance counters, performance metrics, real time vs historical statistics, etc. Much of the content is based on my book VMware VI and vSphere SDK by Prentice Hall.

Once you understand these basics, the related tools and APIs should be relatively easy. If you are already familiar with vSphere Client performance monitoring or esxtop, they help as well.

Performance Counter

A performance counter is a unit of information that can be collected about a managed entity. PerfCounterInfo data object, shown in Figure 1, represents a performance counter. The property key is an integer that uniquely identifies a performance counter, like a primary key of a table in SQL database, and nothing more. There is no guarantee for a performance counter to have a fixed number. In fact, the same performance counter can have different values in ESX and VirtualCenter. Even for the same type of server, the number could change from version to version. Do not use it outside the context of the server you connect to.

Figure 1 PerfCounterInfo data object

The performance counter can be represented by the following dotted string notation:

3 Ways to Get Hold of Managed Objects in vSphere

March 30th, 2010 No comments

If you have ever used vSphere Web Service API, you must have known that there is no managed object but ManagedObjectReference object. Understanding it helps deepen your understanding of the vSphere API.

Honestly, the ManagedObjectReference is a little confusing by itself. It is in fact a data object but represents a managed object. You can think of a MOR as a pointer in some sense because it’s used to uniquely identify a managed object. Even better, you can think of the “type” and “value” defined in the MOR in the SQL way. The type is like a table name, and the value like the primary key which can uniquely identify a managed object in its type.

MOR is really intended to be used by program and should be carefully limited to the scope of where it comes from. That is why it’s hidden from application developers in vSphere Java API.

Anyway, let’s see how to get hold of MOR objects:

Categories: vSphere API Tags: ,

vSphere Inventory Structure Deep Dive

March 29th, 2010 4 comments

This blog digs into the vSphere inventory structure, and changes in vSphere 4 from VI. It explains the difference between ESX and vCenter inventory tree, why the inventory path you see from vSphere Client doesn’t work with API. Much of the content is adapted from my book VMware VI and vSphere SDK by Prentice Hall.

Inventory vs. Inheritance hierarchy

My previous blog introduced the object model of the vSphere API. The UML diagram there shows how different managed object types are structured in the inheritance hierarchy.

The inventory hierarchy is quite different. It shows how different managed object instances are associated. With this understood, you can easily navigate among different managed objects in inventory tree of both ESX and vCenter. It’s critical for programming vSphere API because navigating the inventory is the primary way to get hold of managed objects.

Categories: vSphere API Tags: ,

Why Some vSphere Java API Methods don’t Work with Old Servers? A Story of Compatibility

March 15th, 2010 1 comment

Many of you already know there are some changes in the vSphere API from 2.5 to 4.0. The changes include 20+ new managed object types, additional properties (including sub-properties that embedded inside the first level properties), and several inheritance structure changes.

Several managed objects like Datastore became the subtype of ManagedEntity in vSphere 4, which is different from the hierarchy in 2.5 where it’s a subtype of ExtensibleManagedObject. The changes came for good reasons – we want permission control over these managed objects.

Vote for vSphere Java API at VMware Labs

March 9th, 2010 2 comments

Several smart bloggers (Eric Sloof, Justin EmersonIan Koenig, Alessandro Perilli) discovered the VMware Labs web site over the weekend. As many pointed out, it’s absolutely cool.

I actually knew it was going to be online this past weekend, but would like to get official announcement from the company before blogging it. The reason I knew the site to go live is because the vSphere Java API I created is one of the first 10 projects.

Categories: vSphere API Tags:

Lightweight Caching Framework in vSphere Java API 2.0

March 7th, 2010 5 comments

In vSphere Java API 2.0, I wrote a lightweight caching framework. It’s still experimental but has a great potential to greatly simplify your development work. Commercial companies already use it in their products.

The motivation behind this framework is simple – instead of keep polling the changes from the server side, you keep a local cache that is made as fresh as possible. The View in the vSphere Perl toolkit is one way to do. It caches all properties of a managed object despite the fact that you don’t need that many at all.

The caching framework in vSphere Java API takes another approach. You tells it what managed objects and what properties you want to be cached. After that, the caching framework does its best to read the properties and keep them as fresh as possible.

Architecturally the caching framework is totally separated from the core of the API. You can take it away without any impact on the rest of the API. This is quite different from other toolkit.

Have enough introduction? Let’s take a look at sample code:

Categories: vSphere API Tags: ,