vSphere ESX Agent Manager API

Managed Object - Agency

Property of: AgencyIssue, AgentRuntimeInfo, EsxAgentManager, ExtensibleIssue
Returned by: CreateAgency, QueryAgency
Extends: EamObject
See also: AgencyConfigInfo, Agent, EamObjectRuntimeInfo, Issue, vim.VirtualMachine
Since: 1.0

Managed Object Description

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 EsxAgentManager#createAgency(Agency.ConfigInfo,String)).

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 Agency#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 Agency#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 Agency#runtime().

Properties

Name	Type	Description
agent*	vmodl.ManagedObjectReference to a Agent[]	An array of agents deployed by this agent manager. Requires view privileges.
config	AgencyConfigInfo	The configuration of this `Agency`. Specifies how this `Agency` deploys its agents and VIBs. Requires view privileges.
owner*	xsd:string	The principal name of the user that owns this `Agency`. If the agency is owned by a VC extension, this method returns null. Requires view privileges. *Since* vEAM API 6.0
runtime	EamObjectRuntimeInfo	Gets the runtime information for this agency. Requires view privileges.
solutionId	xsd:string	The ID of the solution that owns this `Agency`. If the agency is owned by a VC extension, this is the extension's key. Otherwise, this is same as Agency#owner(). The users in the latter case are either regular or solution users. Requires view privileges.
Properties inherited from EamObject
None

*May not be present

Methods

Methods defined in this Managed Object
AddIssue, Agency_Disable, Agency_Enable, AgencyQueryRuntime, DestroyAgency, QueryAgent, QueryConfig, QuerySolutionId, RegisterAgentVm, Uninstall, UnregisterAgentVm, Update
Methods inherited from EamObject
QueryIssue, Resolve, ResolveAll

AddIssue

Deprecated.

Adds an issue to this agency. Issue#key and Issue#time is overwritten so that Issue#key becomes unique on this server and Issue#time is the current time.

Requires modify privileges.

Required Privileges: None
Since: vEAM API 2.0

Parameters

Name

Type

Description

_this

vmodl.ManagedObjectReference

A reference to the Agency used to make the method call.

issue P

Issue

A new issue.

Since vEAM API 2.0

P Required privilege: issue

Return Value

Type	Description
Issue	The same issue where the key and time is set.

Faults

Type	Description
vmodl.fault.InvalidArgument
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="AddIssue" type="eam:AddIssueRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="AddIssueResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="eam:Issue"/>
               </sequence>
            </complexType>
         </element>

Agency_Disable

Deprecated. its definition is not consistent across agent VMs and VIBs. It is impossible to be defined since there is no corresponding state of ESXi vibs.

Sets the goal state of this Agency to disabled. This powers off any powered on agent virtual machines, but continues provisioning agents to hosts that are added to the compute resources in the agency's scope, and removes agents from hosts that are taken out of the scope.

Requires modify privileges.

Required Privileges: None

Parameters

Name	Type	Description
_this	vmodl.ManagedObjectReference	A reference to the Agency used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="Agency_Disable" type="eam:Agency_DisableRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="Agency_DisableResponse">
            <complexType/>
         </element>

Agency_Enable

Deprecated. since agencies are always created as enabled. In addition, enabling already uninstalled agency is not supported.

Sets the goal state of this Agency to enabled. This causes the agency to continuously deploy and monitor agents.

Requires modify privileges.

Required Privileges: None

Parameters

Name	Type	Description
_this	vmodl.ManagedObjectReference	A reference to the Agency used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="Agency_Enable" type="eam:Agency_EnableRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="Agency_EnableResponse">
            <complexType/>
         </element>

AgencyQueryRuntime

Deprecated. Use #runtime() instead

Gets the runtime information for this agency.

Requires view privileges.

Required Privileges: None

Parameters

Name	Type	Description
_this	vmodl.ManagedObjectReference	A reference to the Agency used to make the method call.

Return Value

Type	Description
EamObjectRuntimeInfo	The runtime information.

Faults

Type	Description
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="AgencyQueryRuntime" type="eam:AgencyQueryRuntimeRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="AgencyQueryRuntimeResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="eam:EamObjectRuntimeInfo"/>
               </sequence>
            </complexType>
         </element>

DestroyAgency

Destroys this Agency. Any agents that the Agency has are removed. Until the agents have been removed, it is possible to view the runtime state of this Agency but it is not possible to modify its configuration or change its goal state. After all agents have been removed, any subsequent call on this Agency will throw a ManagedObjectNotFound exception.

Requires modify privileges.

Required Privileges: None

Parameters

Name	Type	Description
_this	vmodl.ManagedObjectReference	A reference to the Agency used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="DestroyAgency" type="eam:DestroyAgencyRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="DestroyAgencyResponse">
            <complexType/>
         </element>

QueryAgent

Deprecated. Use #agent() instead

An array of agents deployed by this agent manager.

Requires view privileges.

Required Privileges: None

Parameters

Name	Type	Description
_this	vmodl.ManagedObjectReference	A reference to the Agency used to make the method call.

Return Value

Type	Description
vmodl.ManagedObjectReference to a Agent[]

Faults

Type	Description
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QueryAgent" type="eam:QueryAgentRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QueryAgentResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

QueryConfig

Deprecated. Use #config() instead

The configuration of this Agency. Specifies how this Agency deploys its agents and VIBs.

Requires view privileges.

Required Privileges: None

Parameters

Name	Type	Description
_this	vmodl.ManagedObjectReference	A reference to the Agency used to make the method call.

Return Value

Type	Description
AgencyConfigInfo	The configuration of this `Agency`.

Faults

Type	Description
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QueryConfig" type="eam:QueryConfigRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QueryConfigResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="eam:AgencyConfigInfo"/>
               </sequence>
            </complexType>
         </element>

QuerySolutionId

Deprecated. Use #solutionId() instead

The ID of the solution that owns this Agency. If the agency is owned by a VC extension, this is the extension's key. Otherwise, this is same as Agency#owner(). The users in the latter case are either regular or solution users.

Requires view privileges.

Required Privileges: None

Parameters

Name	Type	Description
_this	vmodl.ManagedObjectReference	A reference to the Agency used to make the method call.

Return Value

Type	Description
xsd:string	The solution ID.

Faults

Type	Description
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QuerySolutionId" type="eam:QuerySolutionIdRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="QuerySolutionIdResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:string"/>
               </sequence>
            </complexType>
         </element>

RegisterAgentVm

Deprecated. use automatically provisioned VMs and register hooks to have control post provisioning and power on

Adds an agent VM to this agency. Used if manuallyProvisioned is set to true. The method does nothing if the agent VM is already registered with this agency.

Requires modify privileges.

Required Privileges: None
Since: vEAM API 2.0

Parameters

Name

Type

Description

_this

vmodl.ManagedObjectReference

A reference to the Agency used to make the method call.

agentVm P

vmodl.ManagedObjectReference
to a vim.VirtualMachine

The managed object reference to the agent VM.

Since vEAM API 2.0

P Required privilege: agentVm

Return Value

Type	Description
vmodl.ManagedObjectReference to a Agent

Faults

Type	Description
vmodl.fault.ManagedObjectNotFound
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="RegisterAgentVm" type="eam:RegisterAgentVmRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="RegisterAgentVmResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

Uninstall

Sets the goal state of this Agency to uninstalled. This initiates the uninstallation of this Agency, which causes all agents to be removed.

The best practice when destroying an agency is to call uninstall, wait for the runtime status to turn green, and then invoke Agency#destroyAgency(). When waiting for this Agency to be uninstalled the solution can then attend to and resolve any raised issues.

Requires modify privileges.

Required Privileges: None

Parameters

Name	Type	Description
_this	vmodl.ManagedObjectReference	A reference to the Agency used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="Uninstall" type="eam:UninstallRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="UninstallResponse">
            <complexType/>
         </element>

UnregisterAgentVm

Deprecated. use automatically provisioned VMs and register hooks to have control post provisioning and power on

Removes an agent VM to this agency. Used if manuallyProvisioned is set to true. The method does nothing if the agent VM is not registered with this agency.

Requires modify privileges.

Required Privileges: None
Since: vEAM API 2.0

Parameters

Name

Type

Description

_this

vmodl.ManagedObjectReference

A reference to the Agency used to make the method call.

agentVm P

vmodl.ManagedObjectReference
to a vim.VirtualMachine

The managed object reference to the agent VM.

Since vEAM API 2.0

P Required privilege: agentVm

Return Value

Type	Description
None

Faults

Type	Description
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="UnregisterAgentVm" type="eam:UnregisterAgentVmRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="UnregisterAgentVmResponse">
            <complexType/>
         </element>

Update

Updates the agency configuration used by this Agency to deploy agents and VIBs. vSphere ESX Agent Manager generates a diff between the old configuration and the new one and updates the Agency accordingly.

Requires modify privileges.

Required Privileges: None

Parameters

Name Type Description

_this vmodl.ManagedObjectReference A reference to the Agency used to make the method call.

config P

AgencyConfigInfo

The new configuration for this Agency

Since 1.0

P Required privilege: config

Return Value

Type	Description
None

Faults

Type	Description
InvalidAgencyScope	Thrown if one or more compute resources in the scope cannot be found in vCenter or there is no configured resource pool or folder where the VMs to be deployed.
InvalidAgentConfiguration	Thrown if one or more agent configurations are invalid.
InvalidUrl	Thrown if either the agent virtual machine URL or VIB URL cannot be parsed or if the resource refered to cannot be downloaded.
vmodl.RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="Update" type="eam:UpdateRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:eam="urn:eam" xmlns:vim25="urn:vim25" xmlns:reflect="urn:reflect" name="UpdateResponse">
            <complexType/>
         </element>