Agency APIs

An Agency handles the deployment of a single type of agent virtual machine and any associated VIB bundle, on a set of compute resources.

For a solution to deploy multiple types of agents, it must create multiple agencies by using createAgency on EsxAgentManager (see CreateAgency).

Creating an agency is a long-running process. vSphere ESX Agent Manager must install VIBs, configure hosts, install agent virtual machines and do many more things. Each of these steps can take a considerable amount of time. vSphere ESX Agent Manager can also encounter problems when creating the agency. In this case, the solution must remediate the problem. See Issue for a description of the kinds of issue that vSphere ESX Agent Manager will raise. Similarly, removing an agency from vSphere ESX Agent Manager is also a long-running process that involves many steps. Removing an agency can also raise issues.

Use the goalState and status properties to show the progress of creating or removing an Agency. The goalState and status properties are found in the runtime information of an Agency (see status in runtime):

• goalState. The goal state describes the overall goal of an Agency. The goal state can be enabled or uninstalled:
  • enabled. The Agency continuously deploys VIBs and agent virtual machines, powers on agent virtual machines, and monitors agents for issues.
  • uninstalled. The Agency uninstalls any installed VIBs and powers off and deletes any deployed agent virtual machines.
• status. The status of the Agency regarding the given goal state. Status can be either red, yellow or green:
  • red. An issue is preventing the Agency from reaching its desired goal state. See issue in runtime for the types of issues that can block this Agency.
  • yellow. The Agency is actively working to reach the desired goal state. For the enabled goal state, this means that this Agency is currently installing VIBs, deploying agent virtual machines, and powering them on.
  • green. The Agency has reached the desired goal state. The Agency is no longer actively scheduling new tasks but is monitoring the vCenter Server for changes that might conflict with this Agency's goal state.

The following image shows in general terms how the status changes in the life-cycle of an Agency.

"Agency degraded" means that something has happened in the vCenter Server that causes this Agency to actively schedule new tasks to reach the goal state. For example, adding a host to a cluster covered by the scope of the Agency, which causes ESX Agent Manager to install a VIB and deploy an agent virtual machine on the new host. A solution should monitor the list of issues associated with this Agency.

The solution can poll runtime.