Archive

Posts Tagged ‘vSphere API’

A Workaround to Identify NFS based Datastore in vSphere

October 4th, 2010 2 comments

We just had the longest discussion in vSphere Java API forum regarding the “UUID of an NFS datastore.” The question is basically how to find the “UUID” via the vSphere API.

You can create datastores based on either VMFS or NFS. The VMFS can be backed up by local SCSI, or SAN (FC, iSCSI). It’s very easy to find UUID of a VMFS based datastore by calling getUuid() method from the corresponding data object VmfsDatstoreInfo.

For NFS based datastore, it’s a lot complicated. I am glad we digged to the bottom of the issue. Instead of going through the long discussion, I summarize the key takeways from the discussion.

Before jumping into details, let’s clarify one thing: NFS datastore does not have a UUID. (If you want to know more about UUID in vSphere, you should read this blog article.) You can check out the NasDatastoreInfo which does not have uuid property. It does, however, have an identifier like 73ca9790-6dbf88b0, which is not a UUID per se. We will call it simply an ID.

Motivation

You may be wondering why you should care about the ID. It is pretty important in that it’s used in performance stats like the following:

Two Important Tips Reading vSphere API Reference

September 29th, 2010 4 comments

Last week I answered a question in VMware Web Services SDK forum about asterisks in vSphere API reference. Underneath these asterisks comes a note saying “May not be present.” What does it really mean?

The asterisks normally show up after properties or sub-properties defined with a managed object. As it says, it’s possible that there is NO value to the property.

How can it be like this?

There are two major causes. First, it reflects the different implementations of ESX, ESXi and vCenter. As a quick example, you can find many of the properties in the “content” (type: ServiceContent) come with asterisks.

On a vCenter server, you will find values to almost all the properties, but not quite so for ESX/ESXi. But we have one API reference document, so it’s natural to mark whatever possible no value as “may not present.”

Secondly, it may be as such depending on the state of a managed object. For instance, a virtual machine can be a bare machine without an OS installed. Therefore, the “guest” property of the virtual machine could have no value at all.

What does it mean to you?

Object Model of VMware vCloud API: The Big Picture in 2 Minutes

September 16th, 2010 No comments

VMware released the long-awaited vCloud API at VMworld 2010. The API is based on REST with 75 URLs defined in the user related part as you would find in the vCloud API Specification and vCloud API Programming Guide.

I am an OO guy (I am sure many of you are as well), and find it difficult to go through the 75 URLs and numerous XML tags as either input or return. These URLs are like trees in a forest. But where is the forest?

So I decided to create and show you a UML diagram (shown below) so that you can easily capture the key concepts of the vCloud API. In fact, there was a similar diagram in the programming guide of version 0.8.

Why No DatacenterRemovedEvent? A Deep Dive into vSphere Event Model

September 14th, 2010 13 comments

Last week I discussed how to get event type with vSphere API, followed by a comment asking why there is no DatacenterRemovedEvent? Very good question and almost got me there.

vSphere API has a comprehensive object model for event. In version 4.1, we have 474 different types of events representing different things happened in vSphere. When a managed entity is removed, there are normally events associated, for example, VmDeployedEvent, HostRemovedEvent, ClusterDestroyedEvent, ResourcePoolDestroyedEvent, DatastoreDestroyedEvent, DatastoreRemovedOnHostEvent, etc. It’s natural to expect DatacenterRemovedEvent. But you don’t find one.

It’s not only Datacenter which does have DatacenterCreatedEvent and DatacenterRenamedEvent. For Folder type, you find nothing other than VmBeingClonedNoFolderEvent which is not related to lifecycle of Folder at all.

Why are these events missing?

Categories: vSphere API Tags: ,

Creating Your Own Task and Event in vSphere

September 9th, 2010 33 comments

vSphere has a powerful extension mechanism that allows you to add new features as integral part of the platform. Many vendors have already leveraged this by providing plug-ins so that users can manage their components seamlessly within same vSphere Client.

You can actually do more than that with the extension. The following sample shows how to create your own task and event with vSphere API. The code should be self explanatory therefore I don’t elaborate much here. Note that you must run the sample with a vCenter server as extensibility is implemented only in vCenter.

When running the code, you can see a new task created and progresses with 10% every second in the “Recent Tasks” pane of vSphere Client. When the task is done, you will also see a new event posted in the “Tasks & Events” tab of the host you associate the task with.

What can you do with this capability? Here are two typical use cases:

Really Easy Ways to Capture VM Screenshot

September 8th, 2010 7 comments

Since vSphere 2.5, there is a feature allowing you to capture screen shot of a running virtual machine. It’s not well publicized but you can find a short description with screenshotSupported (boolean) in the HostCapability data object. Thanks to Nikita for bringing this up in the comment of the vSphere Java API 2.1 GA post.

Indicates whether the screenshot retrival over https is supported for this host’s virtual machines. If true, a screenshot can be retrieved at the HTTPS relative path /screen?id=<managed object ID of virtual machine or snapshot>. If any of the optional parameters ‘top’, ‘left’, ‘bottom’, and ‘right’ is specified, the returned image will be cropped from the rectangle with upper left corner (left, top) and bottom right corner (right – 1, bottom – 1). These values default to the top, left, bottom and right edges of the image. The client must use an authenticated session with privilege VirtualMachine.Interact.ConsoleInteract on the requested virtual machine or, in the case of a snapshot, the virtual machine associated with that snapshot.

The managed object ID of virtual machine is the value of ManagedObjectReference, which can be easily found using MOB.

Once you have it, you can issue a URL as follows in any browser and get the screen shot in PNG format.

How to Get Metadata of VMware vSphere API?

September 7th, 2010 No comments

VMware vSphere API is defined by WSDL. As discussed in my previous blog REST or SOAP, Web Services is by nature procedural, and it does not support OO (object oriented). This contributes to the learning curve of vSphere Web Service API which is modeled with OO.

What if you want to find out what properties are supported by a particular managed object type in vSphere API? There was a specific question recently in blog comment: how to get valid/supported property paths like summary.hardware.numNics with HostSystem type.

Currently there is no systematically way to get this metadata which is not defined in WSDL. You have to manually read through vSphere API Reference.

Since vSphere Java API 1.0 (a.k.a. VI Java API by then), I have manually added a getter method for every property in the Java API. So the metadata is built in vSphere Java API from the beginning. Whenever there is a manual process, it could be error-prone. As much carefully as I liked, I made mistakes with properties ignored in vSphere Java API occasionally. These mistakes have been immediately patched up upon bug reports or self reviewing.

To get exactly what you want programmatically, you have to do something extra with Java reflection API. Let’s pick HostSystem as an example here.

Ruby to Manage and Automate VMware vSphere?

August 30th, 2010 No comments

As I mentioned in a previous blog, vSphere(VI) Java API can be used in any JVM languages/frameworks. We have samples in Jython, Groovy, Grail. This weekend I got a sample in JRuby shared by our community member Martin Jackson in the API forum. Thanks Martin!

I think it would be fun to share it with you. If you can write Ruby code, you can take advantage of VI Java API for managing and automating vSphere as well. If you have samples leveraging the API to share, I am happy to hear about it.

Now, let us take a look at Martin’s sample code ported from a VI Java API sample.

Announcing vSphere Java API 2.1 GA Release

August 26th, 2010 10 comments

Right after vSphere 4.1 released, VI Java API 2.1 beta supporting vSphere 4.1 was released on July 15. After 40 days, I am pleased to announce GA of the 2.1 release. Many thanks to all vijava community memembers who helped to try 2.1 beta and give feedbacks.

The 2.1 beta is pretty good in terms of quality. I got several emails reporting greeen. I did get several bugs, some of which are carry-overs that should have been fixed in previous releases. Check the end of this blog for a list of bug fixes.

During the beta period, I started a poweredby page which now features 10 companies/products which use vijava API. If you would like your organizations/products included, please let me know.

Enough being said, are you ready to give 2.1 a try? Please feel to download it here. Even you are new to this API, 5 minutes is good enough to have your first HelloVSphere running with this tutorial.

Categories: vSphere API Tags: ,

Restriction with User Name in ESX 4.1

August 23rd, 2010 2 comments

According to a recent post by Duncan, there is an issue with password in ESX(i) 4.1. Only the first 8 characters of a password are taken and validated. A VMware KB article offered solutions to this issue.

Categories: vSphere API Tags: , ,

How to Get Event Type with vSphere API?

August 19th, 2010 12 comments

There is a recent question asking how to get the type of event from vSphere API in my previous blog. On one hand, you can clearly see the types of events on a vSphere Client, for instance “info”, “warning”, “error”, and “user.” On the other hand, you cannot find any information about the type from a given event itself using vSphere API.

Strictly speaking an event just indicates something has happened. That is it. You can categorize it differently depending on your goal. The Event type itself in vSphere API models an event as what it is, not about how you look at it. This is a right design philosophy, but turns out to be a little tricky for you to figure out the type of an event.

How does vSphere Client do the trick?

Categories: vSphere API Tags: , ,

Manage Lockdown Mode with New API in vSphere 4.1

August 17th, 2010 No comments

As a feature, lockdown mode has been added to vSphere 4.0 . Enabling it disables all remote root access to an ESXi machine. Any local changes to the host must be using:

  • DCUI (Direct Console User Interface).
  • vSphere Client or vCLI connecting to vCenter.
  • vSphere Client or vCLI connecting to ESXi with a local user account on the host.

My colleague Duncan Epping has summarized a table showing whether you can change ESXi with different access methods in two modes.

As a general practice for better security, it’s recommended to enable lockdown mode. However the lockdown mode could be breached by adding root user to local groups,

How to Get ESX Version from vCenter?

August 16th, 2010 4 comments

There is a recent question in vSphere(VI) Java API forum about this. On its face, it’s very easy because most people know how to get hold of the version as follows: 

String version = si.getAboutInfo().getVersion();

The si in the above code is the variable of ServiceInstance object. If you have never used the API yet, please try this Getting Started Tutorial which shows how to get your first program running from scratch in 5 minutes

If you are connecting to a vCenter server and try to get the version of a HostSystem the vCenter manages, it’s not so obvious. But it’s definitely doable. Here is the solution assuming you already get hold of the HostSystem object as host variable here: 

String version = host.getConfig().getProduct().getVersion();

Here you know why. First, the aboutInfo is now called product although they are of the same type. Second, it’s hidden within the config property. 

Before taking the code away, I would like to share with you an important tip for better performance. 

Categories: vSphere API Tags: ,

UUID vs. vSphere

August 12th, 2010 4 comments

UUID stands for universally unique identifier (UUID). It’s a 128-bit value. vSphere uses it as IDs for many different types of entities like HostSystem, VirtualMachine, Datastore, etc.

The UUID surfaces to the vSphere API as well. You can find many methods use UUID as parameter or return result. The most commonly used one is the SearchIndex.findByUuid() which find you a virtual machine or a host based on its UUID, either instance or BIOS UUID. The format used for UUID is as follows:

52dc2e26-dbc4-7d05-5fed-019d234379d9

Since 4.0, DistributedVirtualSwitchManager managed object is added and it has a method called queryDvsByUuid(). As reported by VI Java API community, the standard format doesn’t work. The accepted format is like this:

Who Created That VM: Java Version of the Winning Script of VMware Contest

August 3rd, 2010 2 comments

As you recall from my previous blog on the Script-O-Mania contest, Alan Renouf won the first prize with his Who Created That VM script written in PowerCLI. The script leverages implicitly several vSphere APIs, so I think it would be cool to have a Java version. At least we can illustrate how to use these related vSphere APIs.

The following is a sample I rewote using VI Java API for the same purpose except that Alan’s script shows full display name of a user while this Java version shows user name (see the following diagram). Although longer, the Java version can run on any OS, not just Windows.

Categories: vSphere API Tags: ,

How to Create Linked Virtual Machines with vSphere API?

August 2nd, 2010 15 comments

More often than not, you may have several virtual machines based on same software stacks running on the same host. Although they are very much the same, they take as much space as multitude of what one virtual machine takes.

Since vSphere 4.0, things are different. You can significantly reduce the storage usage by a new feature called linked virtual machines. The idea is simple: sharing a common virtual disk among the similar virtual machines. The shared virtual disk serves as a base. On top of that, each virtual machine has its own delta disk. When a guest operating system writes to disk, the data persists to the delta disk. When it reads from disk, the delta disk is checked first before trying the base disk.

As a result, you only need to save one copy of the base disk no matter how many virtual machines you have (up to 8 virtual machines in a linked virtual machine group). One limitation is that you cannot use it with HA cluster.

How to create linked virtual machines? You have two approaches: clone a virtual machine either from a snapshot, or from its current running state.

What’s Deprecated in vSphere 4.1 API?

July 27th, 2010 No comments

In vSphere 4.1, several properties and types have been deprecated. The following table from vSphere Web Services SDK 4.1 release note lists each deprecated API element and its replacement.

Name of deprecated type, method, or property As of vSphere API 4.1, use instead…
Methods
PropertyCollector.CheckForUpdates PropertyCollector.WaitForUpdatesEx
PropertyCollector.RetrieveProperties PropertyCollector.RetrievePropertiesEx
PropertyCollector.WaitForUpdates PropertyCollector.WaitForUpdatesEx
VirtualMachine.AcquireMksTicket VirtualMachine.AcquireTicket
Data Objects
VirtualMachineMksTicket VirtualMachineTicket
Data Object Properties
Categories: vSphere API Tags: ,

Complete List of Managed Object Types in VMware vSphere API

July 19th, 2010 No comments

The following tables list all the managed object types in VI 3.5, vSphere 4 and 4.1. A short description is provided for each type explaining its major responsibilities.

Note that the managed object types are added in an incremental way. The types in older versions are still supported in newer versions. The complete types in a verion include ones in the correpsonding table plus all the ones in all older version tables.

Hope this post gives you a high level overview of functionalities of the vSphere APIs. Check out other blogs such as best practices (1-5, 6-10) on how to use them in general. And don’t forget my book which introduces them extensively with many read to use samples.

Table 1 Managed Object Types in VI 3.5

What’s New in vSphere 4.1 API?

July 15th, 2010 No comments

VMware announced GA of vSphere 4.1 product this Tuesday. Here is the official what’s new in vSphere 4.1. Many bloggers already covered different aspects of the product itself: VMware vSphere 4.1: Advancing the Platform for Cloud ComputingUseful vSphere 4.1 knowledgebase articlesvSphere 4.1 releasedRelease: VMware vSphere 4.1, etc. I don’t repeat these here, but focus on the new APIs in 4.1 release.

In general, the APIs are the programatic “view” of features. Understanding the features helps a lot on understanding the APIs. So I strongly encourage you to read new features of the product itself. Note that not all the new features especially the performance and scalability features are explicitly reflected in API signatures.

vSphere API 4.1 introduces 7 new managed object types:

vSphere 4.1 adds 23 new methods to 10 existing managed object types:

Categories: vSphere API Tags: ,

How to Extend vSphere Java API?

June 21st, 2010 7 comments

I got a request a while back for extending the vSphere Java API. The idea is that the API itself is pretty basic and not high level enough for some applications. For example, if you want to add a virtual NIC to a virtual machine, there is no explicit method for doing this. Fair enough.

Now, how to achieve this?

Three possible approaches

  1. Change the structure of the API. For every managed object type, we have two types: one with implementation, and the other inheriting the first one but really empty. The user can replace the first second one with extra methods as extensions. This approach is smart, but will cause confusion in the future. For instance, we will have many different implementations for the sample types.
  2. Use composition. You can create a new type that contains an instance of a managed object. How to expose the methods of the managed object? You can either manually add them to the containing type, or expose the instance of the managed object so that others can call its methods.
  3. Use inheritance. You can create a new type that inherits a managed object type. Once you get an instance of a normal managed object, you can pass into the constructor of extended managed object type. You can use the extended type anywhere a normal type is expected. Let’s pick VirtualMachine as an example,
Categories: vSphere API Tags: ,