# Configuration Guide

# Defining Policies

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

- Policy Components
- Policy Types
- Creating Policies
- Constraint Types
- Action Types
- Action Pipelines

## 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.

Figure 6-1 illustrates the basic constraint/action relationship.

Figure 6-1 Policy Constraint and Actions

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

Listing 6-1 Constraint/Action Binding in metadata-config.xml

    <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

To create a policy, you:

1. 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.

2. 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-2 Constraint/Action Binding

             <ns2:constraint-binding>
                  <ns2:constraint-key>MyServicedeploy-key</ns2:constraint-key>
                  <ns2:action-key>MyServicestartserviceaction</ns2:action-key>
             </ns2:constraint-binding>
         </ns2:constraint-bindings>

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

Listing 6-3 Constraint Definition

         <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.

Listing 6-4 Action Definition

    <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.

These policy types are discussed in the following sections:

- Deployment Policies
- Runtime Policies
- Administrative Policies

### 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.

Note: | Resource Agreement constraints are not bound to an action.

### 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.

Note: | For detailed information about these constraint types, see “Define Constraints” in the WLOC Administration Console Online Help.

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.

Listing 6-5 MBean 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:

    [<type>|<instance name>|<attribute name>]

For example:

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

where

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

A metric parameter can also contain other functions. For example:

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

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

    SumWithScalar([weblogic.management.runtime.ServerRuntimeMBean|.*|RestartsTotalCount],37)

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.

Listing 6-6 Constraint with a Function in Metadata-config.xml

          <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.

Note: | For detailed information about these action types, see “Define Actions” in the WLOC Administration Console Online Help.

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.

Note: | Most actions can also be executed directly from the Administration Console without being bound to a constraint and included in a policy.

## Action Pipelines

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

Note: | If an action fails at any point in the pipeline, the pipeline terminates and no subsequent actions in the pipeline are executed.

#### 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:

1. Define an action that starts the WLS Admin Server instance.
2. Define an action that starts the Managed Server instances.
3. Define an action that sends e-mail notification when the server instances start up.
4. Define an action pipeline that consists of all these actions.
5. Create a policy with an appropriate constraint and bind the pipeline to the constraint.