Defining Policies

This section describes how to create policies for deploying and managing applications through WLOC. It includes the following topics:

Policy Components

Each WLOC policy consists of a constraint and an action or action pipeline. The constraint defines some deployment or runtime requirement of a service, while the action or action pipeline defines one or more actions to take if the service runtime-value is outside the constraint-value range.

For example, a policy can consist of a constraint that defines a runtime requirement of at least two running processes and an action that starts a process if only one is found to be running.

The assignment of a constraint and action to a policy is referred to as the ‘constraint/action binding’.

Listing 6-1 shows a constraint/action binding as part of a service definition in the metadata-config.xml file. In the example, the ‘key’ names are references to the complete constraint and actions definitions located elsewhere in the file

<ns2:service>
    <ns2:name>MyService</ns2:name>
    <ns2:description>MyService</ns2:description>
    <ns2:state>deployed</ns2:state>
    <ns2:priority>0</ns2:priority>
    <ns2:constraint-bindings>
       <ns2:constraint-binding>
           <ns2:constraint-key>MyServicedeploy-key</ns2:constraint-key>
           <ns2:action-key>MyServicestartserviceaction</ns2:action-key>
        </ns2:constraint-binding>
    </ns2:constraint-bindings>
</ns2:service>

It is very important that the constraint/action binding be appropriate to the scope of a policy. For example, a constraint that specifies some service deployment state must be bound to an action that can stage, deploy, or undeploy a service.

Creating Policies

Create a constraint that defines some service deployment state or runtime performance requirement.

Note:

The WLOC Administration Console uses the term Rules to refer to constraints.

Create an action or action pipeline that specifies the action(s) to take if the application runtime does not satisfy the constraint definition. Doing this in the Administration Console effectively binds the action (or action pipeline) with the constraint.

The recommended method of defining a policy is to use the WLOC Administration Console, but you may also directly edit the metadata configuration file (metadata-config.xml). When doing the latter, you must provide three definitions: the constraint binding under the service or process type, the constraint, and the action.

Listing 6-2 provides an XML snippet of a constraint binding. The constraint binding is contained within the service definition as shown in Listing 6-1. Note that the constraint binding contains ‘keys’ to the actual constraint and action definitions elsewhere in the file.

Listing 6-3 provides an XML snippet of the constraint definition referenced in the constraint binding shown above.

     <ns2:deployment-state-constraint>
         <ns2:name>MyService-service-deploy</ns2:name>
         <ns2:key>MyServicedeploy-key</ns2:key>
         <ns2:priority>0</ns2:priority>
         <ns2:state>starting</ns2:state>
         <ns2:evaluation-period>0</ns2:evaluation-period>
      </ns2:deployment-state-constraint>

Listing 6-4 provides an XML snippet of the action defintion referenced in the constraint/action binding shown in Listing 6-2.

<ns2:actions>
        <ns2:action>
            <ns2:name>MyServicestartserviceaction</ns2:name>
            <ns2:key>MyServicestartserviceaction</ns2:key>
            <ns2:impl-class>com.bea.adaptive.actions.internal.StartServiceAction</ns2:impl-class>
            <ns2:adjudicate>false</ns2:adjudicate>
            <ns2:properties/>
        </ns2:action>
</ns2:actions>

For assistance in understanding how to edit the metadata configuration file, use the schema file (BEA_HOME\wloc_10.3\schemas\loc-metadata.xsd) and also refer to the Service Metadata Configuration Schema Reference.

Policy Types

To begin identifying the policies needed to ensure that the managed application deploys and performs as required, it may be useful to categorize policies by purpose or functionality. From this standpoint, policies can be regarded as deployment, runtime, or administrative.

Deployment Policies

A deployment policy defines a desired deployment state (deployed, staged, undeployed) of a managed application and the action(s) to take to if the application does not currently satisfy the desired state. For example, a deployment policy may require a service deployment state of ‘deployed’. If the current service state is not deployed, WLOC will deploy the service.

Table 6-1 indicates the types of constraints and actions that can be used to define deployment policies.

Table 6-1 Deployment Policy Constraints and Actions
Constraint Types	Action Types
Deployment Resource Agreement For more information, see Constraint Types.	Service Notification For more information, see Action Types.

Runtime Policies

Runtime policies are used to adjust the ongoing performance of a managed application and make adaptive runtime adjustments as necessary. Examples:

A policy may define the minimum number of running JVM processes. If a JVM instance fails for some reason and the number of running instances falls below the minimum, WLOC will start an additional JVM instance.
A policy may specify the minimum heap size required and instantiate additional JVM instances if the heap size falls below the minimum required.
A policy may start additional JVM instances if the workload on the application increases, and then stop instances when the workload decreases.
A policy may start additional JVM instances based on known times of increased demand.

Table 6-2 indicates the constraints and actions that can be used to define a runtime policy.

Table 6-2 Runtime Policy Constraints and Actions
Constraints Types	Action Types
Runtime Resource Agreement For more information, see Constraint Types.	Process Resource For more information, see Action Types.

Administrative Policies

An administrative policy defines an administrative action to perform when a constraint is violated. For example, an administrative action can generate an email notification or an Administration Console event message if some constraint is violated.

Table 6-3 indicates the types of constraints and actions that can be used to define an administrative policy.

Table 6-3 Administrative Policy Constraints and Actions
Constraints Types	Action Types
Deployment Runtime For more information, see Constraint Types.	Notification Configuration For more information, see Action Types.

Constraint Types

WLOC provides out-of-box constraint types for defining requirements using a range of common and important measurements of health and performance. Table 6-4 describes the out-of-box constraint types.

Table 6-4 Constraint Types
Type	Description
Deployment	These define the desired deployment state (Deployed, Staged, Undeployed) of a service. In the Administration Console, these are selectable as: Based on deploying a service at a date/time Based on undeploying a service at a date/time Based on a service deployment state
Runtime	These are JVM-based constraints and can be used in various ways, such as specifying the required number of running instances, setting the minimum amount of CPUs to allocate, or generating an event message based on some metric. Runtime constraints based on MBean attributes can be defined using directly observable metrics (heap size) or on functions applied to these metrics (total heap size of all JVMs). For more information, see Constraints Based on MBean Attributes. In the Administration Console, these are selectable as: Based on firing a service event at a date/time Based on firing a process group event at a date/time Based on firing a process group event based on the outcome of an action Based on firing a process group event based on the outcome of another event Based on a named attribute Based on the value of an attribute or function
Resource Agreement	These constraints are used for service placement and JVM creation. When defining the constraint in the Administration Console, it is not bound to an action. In `metadata-config.xml`, the constraint must be bound to an action whose value is INTERNAL. In the Administration Console, these are selectable as: Based on a maximum amount of CPU Based on a share of CPU Based on a minimum amount of memory Based on a maximum amount of memory Based on a share of memory Based on minimum number of processes Based on maximum number of processes Based on software availability Based on IP Address Based on ISO software availability Based on amount of Local Disk Size required

Constraints Based on MBean Attributes

Runtime constraints based on MBean attributes are evaluated against runtime JMX attributes collected from the managed JVM(s). They can be based on directly-observed metric values of attributes or on custom metrics obtained by applying some function on these values for one JVM instance (or some aggregation of JVM instances).

Named Attributes

The WLOC Administration Console provides a set of named constraints, referred to as Smart Pack constraints, that are based on named MBean attributes. When you select one of these constraints, the console will automatically provide the MBean instance name, type, and the attribute name. Table 6-5 describes the Smart Pack constraints.

Table 6-5 Named Attribute Constraints
Constraints	Description
MinFreeHeapSize MaxFreeHeapSize	Minimum and maximum free heap size for any one JVM in the process type.
MinAverageFreeHeapSize MaxAverageFreeHeapSize	Minimum and maximum mean free heap size of all JVMs in the process type.
MinFreePhysicalMemory MaxFreePhysicalMemory	Minimum and maximum free physical memory size for any one JVM in the process type.
MinAverageFreePhysicalMemory MaxAverageFreePhysicalMemory	Minimum and maximum mean free physical memory size of all JVMs in the process type.
MinUsedPhysicalMemory MaxUsedPhysicalMemory	Minimum and maximum used physical memory size for any one JVM in the process type.
MinAverageUsedPhysicalMemory MinAverageUsedPhysicalMemory	Minimum and maximum mean used physical memory size of all JVMs in the process type.
MinJvmProcessorLoad MaxJvmProcessorLoad	Minimum and maximum percent of CPU usage in a range of 0.0 to 1.0. A value of 0.5 equates to 50% of CPU.
MinAverageJvmProcessorLoad MaxAverageJvmProcessorLoad	Minimum and maximum mean percent of CPU usage of all VMs in the process type.

For the purposes of directly editing metadata-config.xml, Listing 6-5 shows an XML snippet containing a named attribute constraint.

<ns2:instance-name>com.bea:Name=myserver,Type=ServerRuntime</ns2:instance-name>
<ns2:instance-type>weblogic.management.runtime.ServerRuntimeMBean</ns2:instance-type>
<ns2:attribute-name>RestartsTotalCount</ns2:attribute-name>
<ns2:constraint-type>max</ns2:constraint-type>
<ns2:value>10</ns2:value>

Custom Metrics

A constraint can be based on simple numerical comparison or more complex functions applied to an MBean attribute. Constraint functions can include metric parameters using the following syntax:

Sum([weblogic.management.runtime.ServerRuntimeMBean|.*|RestartsTotalCount],[weblogic.management.runtime.ServerRuntimeMBean|.*|Port])

The instance name specification allows regular expression syntax so you are not required to use names that may be context-specific. In the following examples, ".*" is used as the instance name, but it could be any regular expression.

Sum — Function
weblogic.management.runtime.ServerRuntimeMBean — Instance type
.* — Instance name
RestartsTotalCount — Attribute name
Port — Second attribute name

Scalars in function definitions are constant numeric values. Scalars cannot be replaced by functions. For example:

For a complete list of WLOC-supplied functions, see “Define custom metrics” in the WLOC Administration Console Online Help.

Listing 6-6 show an XML snippet defining a constraint that uses the MeanofCollection function. Since a function returns a double, it is encapsulated in a double-constraint element. The instance-type element of these constraints is always FUNCTION and the function definition itself is specified in the attribute-name element.

Note that the value in the instance-name element does not have to match the actual function name.

      <ns2:double-constraint>
        <ns2:name>MyConstraint</ns2:name>
        <ns2:key>MyConstraintKey</ns2:key>
        <ns2:priority>0</ns2:priority>
        <ns2:state>deployed</ns2:state>
        <ns2:instance-name>MeanOfCollection</ns2:instance-name>
        <ns2:instance-type>FUNCTION</ns2:instance-type>
        <ns2:attribute-name>MeanOfCollection([weblogic.management.runtime.
            ServerRuntimeMBean|.*|ServerStartupTime])</ns2:attribute-name>
        <ns2:constraint-type>max</ns2:constraint-type>         <ns2:value>10000</ns2:value>
      </ns2:double-constraint>

Action Types

Table 6-6 describes out-of-box actions provided with WLOC. When creating these actions in the WLOC Administration Console, the console prompts for the required parameter values.

Table 6-6 Action Types
Action Type	Description
Service	Actions that start, stop, stage, test, or destroy a service. StageServiceAction StartServiceAction StopServiceAction DestroyServiceAction TestStartServiceAction
Process	Actions that start, stop, destroy, stage, suspend, change the configuration, or gracefully stop an instance of a Java process. StartJavaInstanceAction StopJavaInstanceAction DestroyJavaInstanceAction StageJavaInstanceAction ResumeJavaInstanceAction RemoteAction SuspendJavaInstanceAction JavaInstanceConfigAction
Notification	These actions send different types of notifications. Console EmailNotificationAction JMXNotificationAction JMSNotificationAction SNMPNotificationAction
Resource	Actions that change the maximum, minimum or share of CPU or memory that is available. ChangeMaxCPUAction ChangeMinCPUAction ChangeShareCPUAction ChangeMaxMemoryAction ChangeMinMemoryAction ChangeShareMemoryAction
Configuration	Actions that perform JMX operations on specified managed objects. You can define actions that: Creates an instance of the MBean. Destroys an instance of the MBean. No additional parameters are needed. Sets an MBean attribute to a specified value Invokes an operation on the MBean.

Action Pipelines

Actions can be combined into action pipelines so that a sequence of actions takes place when a constraint is violated.

Action Pipeline Example

To define the actions needed to start a WebLogic Server Admin Server instance, then start a cluster of Managed Server instances, and then send an email notification, you would do the following:

Configuration Guide