To understand the ESX Agent Manager API, we have to first explain the Agent, which is essentially Agent Virtual Machine. The agent virtual machine can be hardware drivers for your ESXi server, or simply software, i.e, virus scan, that should be deployed on each ESXi. They could have been designed and installed directly on ESXi via VIB, but it would increase the risk of destablizing ESXi due to access to lower level APIs of ESXi. To lower the risk, the driver VM idea came up – if the driver VM crashes the ESXi is still solid even though some service may be affected.
In many ways, a driver or agent VM is like a typical virtual machine except that it serves special purpose for the ESXi that it runs on. In that sense, it should be regarded as part of the ESXi rather than a normal workload. Consequently, it should never be VMotioned to any other hosts.
As you can expect, the agent virtual machines show up in vSphere Clients and vSphere Web Client as other virtual machines. When you try to operate on them, you would get reminder dialog box that it’s an agent VM, “This entity is managed by solution vSphere Agent Manager. It’s not recommended to modify it directly. Instead use the management console for the solution if you want to make changes. Do you want to proceed?” For more details, please check out William’s blog here.
The right place to manage them on the GUI is the vCenter Solution Manager which you can find from the Home in vSphere Client (You can do similar on vSphere Web Client too). With the vCenter Solution Manager, you can find “vSphere ESX Agent Manager” on the left side list. When it’s selected, you would see 4 tabs on the right side pane: Summary, Virtual Machines, vService Providers, Management. You can explore the functionality there.
From the vSphere API side, how to tell a virtual machine is an agent virtual machine? There is no obvious field that tags a virtual machine as an agent virtual machine. If you look closely and deeply, you would find two key/value pairs in the config.extraConfig property of the VirtualMachine managed object type:
“eam.agent.agencyMoId” : “agency-10″
“eam.agent.ovfPackageUrl” : “manually-managed-ovf”
The second key/value also says that it’s an agent virtual machine manually deployed and managed. The other option is to let the agency to take care of it automatically, but you have to provide a valid URL for it to download.
When there are more than one ESXi server, an instance of a type of agent VM should be running on each of them. Ideally, you can manage all the instances of an agent VM like a single entity. This is exactly why ESXi Agent Manager API is designed.
To use ESX Agent Manager API, you need to download the vSphere SDK from VMware. In parallel with the vsphere-ws directory is the eam directory which contains the wsdl, API reference documentation, and a few samples.
At the high level, ESX Agen Manager API is not complicated – it has only 5 managed object types: EsxAgentManager, Agency, Agent, EamObject, and EamTask. Implementation wise, it uses exactly the same SOAP as vSphere Web Service APIs. If you are familiar with the vSphere Web Service APIs already, the EsxAgentManager is like the ServiceInstance which is the starting point of the API. The agency represent a group of same type of virtual machines that run on different ESXi hosts. The Agent represent one instance of the agent virtual machine. The EamObject is the super type of all of EsxAgentManager, Agency, and Agent. The last one EamTask is there probably by mistake as there is no property, no method defined; neither is used by any other types. The ESX Agent Manager API reference has a good high level overview with a few diagrams on the process, states, and UML class diagrams.
The challenge of using the ESX Agent Manager API is how to take care of the authentication with the vSphere APIs. By itself, the ESX Agent Manager cannot login to the vCenter server directly. It must be part of a server extension whose certificate is registered with vCenter before hand. For the certificate to be passed through to vCenter server, the reversed proxy should be used.
Out of the box, the open source vijava API does not support ESX Agent Manager. Significant work is needed to support ESX Agent Manager API. As companies contacted me for the support, I’ve developed the extension on top of vijava APIs. The extended API has been used in a company’s product. Should you need to use agent VMs, the extended API, and/or consulting, please feel free to contact me: steve __AT__ doublecloud.org.