On this page:
On this page:
The Universal Agent uses rulebooks to manage the deployment and maintenance of runtime agents. This topic introduces rulebooks and strategies for applying them.
A rulebook is a JSON-formatted configuration file that contains the rules that define runtime agent instances. Entries in the rulebook direct the Universal Agent to install, stop, or start agents.
When you start the Universal Agent, the Universal Agent applies a rulebook. The rulebook contains general settings, subject to condition evaluation logic, for the Universal Agent, along with rules for individual types of runtime agents. When you add a runtime agent rule to the rulebook, the Universal Agent subject to the rule retrieves the runtime agent from the repository and installs it in the
monitor directory in the Universal Agent home. The
monitor directory contains the base install directories for each runtime agent.
The Universal Agent can run in two modes:
controller-book.json. This rulebook is thus shared by all instances of the Universal Agent that are running in controller mode.
The rulebook directory, <universal_agent_home>/rulebook, resides on the machine where the Universal Agent is installed.
The modes operate as follows:
controller-book.json. If the Universal Agent can not get the rulebook from the Controller, it looks at the rulebook directory to see if an older copy of
controller-book.jsonexists there. If a copy exists locally, it is used as the rulebook. Otherwise, the Universal Agent uses the
default.jsonrulebook file from the rulebook directory; this is also the rulebook used if the Universal Agent can't connect to the Controller.
local.jsonfrom the rulebook directory and uses that file as the rulebook. Any rulebook from the Controller is ignored.
Local rulebooks are also located in the rulebook directory:
You can put the Universal Agent into local mode using the Universal Agent CLI. You can tell if the Universal Agent is operating in local mode by the presence of a
local.json file in the rulebook directory. If present, the Universal Agent is in local mode; otherwise, it is in Controller mode.
The Universal Agent reads the rulebook at regular intervals and applies changes in the rulebook as they occur, reporting the event to the Controller. By default, the Universal Agent checks the rulebook every 300 seconds (5 minutes).
For testing and initial investigatory work, you may want to reduce this interval to induce more frequent polling. Use the interval property to change the polling frequency.
The basic parts of a rulebook are shown in the following example:
The example rulebook contains three rules that define three runtime agents, two Java app agents and one Machine Agent. The example shows the following fields:
The following sections provide more information on the config and rules fields.
The rulebook example above describes settings that runtime agents use to connect to the Controller and how the agent instance is identified in the Controller UI. These settings correspond to values typically configurable for the runtime agents, particularly for the Java app agent configuration file,
With the Universal Agent, you can set any of the usual properties found in the runtime agent configuration file. You refer to the properties in the Universal Agent configuration files with the identical names contained in
controller-info.xml, except that the hyphen in the name is replaced by an underscore.
Specifically, the rulebook supports the following properties:
For more information on their use, see the
controller-info.xml inline comments and Administer App Server Agents.
When you set the connection values in the rulebook, the Universal Agent updates the controller-info.xml on disk for the runtime agent. The following values are taken from universalagent.yaml if they are not specified in the rulebook:
Specifying the values in the rulebook, however, enables you to configure the Universal Agent and its configured runtime agents to talk to different Controllers, if needed.
The rules section in the Universal Agent rulebook contains rules governing the presence and status of a runtime agent on the Universal Agent host. The default rulebook,
default.json, is installed with the following predefined machine agent rule:
The fields for each rule are:
javafor the Java App Agent
machinefor the Machine Agent
Universal Agent groups are a way to manage multiple Universal Agents as a logical group. By default, Universal Agents are part of the default group and run the default rulebook,
default-controller. As additional Universal Agents start and register with the controller, they join the default group.
You can create your own groups and add Universal Agents to them using the Universal Agent REST API.
A Universal Agent can be part of multiple groups. When the Universal Agent is added to the groups and those groups have different rulebooks, the controller sends multiple rulebooks to the Universal Agent and the rulebooks are logically merged into a single rulebook.
The resulting merged rulebook is written to controller-book.json. You should not attempt to modify this rulebook directly.
You can use conditions to specify criteria for applying rules. In the simplest (and default) case, the value can simply be set to "true" to enable the rule. You can also create test conditions that enable or disable the rule based on the environment in the Universal Agent host.
Condition field syntax in Universal Agent rulebooks is similar to conditions in Python—the condition should evaluate to a Boolean expression with identification data keys as the operands (which should match the regular expression "[a-zA-Z0-9_]+").
To install only on Linux machines and given the "platform_system" environment variable, you could specify the following condition:
Notice that single quotes in the value are escaped.
As another example, the following condition checks for Linux and a version of the Universal Agent higher than 4.3:
Operators you can use are:
Instead of using dynamically evaluated conditions, you can put the static values of true or false in the condition field. When used in this way, the condition field gives you a convenient way to individually enable or disable rules.
To uninstall a runtime agent, remove the rule for it in the rulebook and save the file.
The Universal Agent first stops the runtime agent, if it is running, and then uninstalls the runtime agent from the application or machine and removes the directory for it.