Configuring Services

This section describes configuration tasks associated with WLOC services. It contains the following sections:

Overview

A service is a set of processes managed by WLOC. A process is typically a stack that contains the JVM, the application container, and application logic. For example, a service can be used to manage one or more WebLogic Server instances a domain.

Services and Process Groups

A typical service manages a group of processes that are logically related and organized in process groups. When configuring a process group, you need to specify information required by WLOC to instantiate it, including:

When defining the process group, the console prompts for information about its processes. Table 5-1 describes in more detail the information needed to define a process group.

Table 5-1 Process Group Configuration
Process Group Attribute	Description
Process Group	A string identifier for the process group.
Number of Processes	The number of processes required for the process group.
Name	Name of the initial JVM instance. For each additional instance, a numeric suffix is added to the name.
Description	A description of the JVM.
Main Class or Main JAR	The class or JAR file that instantiates this process.
Host	The fully-qualified host name where the JVM resides.
Starting Port	The starting port number for the machine where the JVMs reside. The first process instance uses this port number. For each additional instance, the port address is incremented by 1.
Classpath	The classpath for the class or JAR file that instantiates this process. For information about obtaining classpath information, see Classpath.
JVM Arguments	JVM arguments to use with the command that instantiates the process. These arguments are passed as java options. Separate each Java argument using a space. For more detailed information, see JVM Arguments.
Java Arguments	Command line arguments needed for running the application in this JVM. These are passed to the java main class as arguments.
Username and password	Security credentials making a JMX connection to the JVM. These will be the default values for all subsequently created processes.
Instance Directory	The directory where the JVM instance resides.
Native Lib Directory	The directory where the JVM native libraries reside. The value will be passed to jvm args as `-Djava.library.path`
Use Native JMX	Flag that specifies whether or not to use JMX connection native JMX MBean server.
SSH Enabled	Flag that specifies whether or not SSH is enabled for the instance.
Protocol	Protocol used for JMX connections (`iiop`, `iiops`, `http`, and `https`).
Ready metric	Information about the metric that WLOC obtains from the JVM instance and uses to determine whether or not a process is available. For more detailed information, see Ready Metrics.
Process Requirements	The required minimum and maximum number of processes.
Resource Requirements	The required minimum and maximum amount of CPU and memory. For more information, see Resource Requirements.
Software Requirements	The name and directory location of the software required by the process.
Manual Placement Addresses	Suggested IP addresses for placement of the process. Doing this supplements WLOC’s internal placement algorithm, which searches for the set of placement locations that would work given the constraints of memory, CPU capacity, software availability, and IP addresses.

Configuring a Service

The primary tool for defining services is the WLOC Administration Console. Services you define or modify using the console will take place in real time. See the WLOC Administration Console help system for step-by-step instructions.

When defining the service’s processes in the console, you can manually enter the required information or use a number of helper functions the console provides for importing much of the information. These include:

It is also possible to define or modify a service by directly editing the metadata configuration file. The location and name of this file is:

Note that direct modifications to the file do not take effect until the Controller is restarted. In addition, manual changes are not validated or error-checked until they are loaded by the next controller boot.

There are number of resources to help you obtain more information about metadata-config.xml file. This includes:

The metadata schema file. The name and location of this file is BEA_HOME\WLOC_HOME\schemas\loc-metadata.xsd. This file may may also be accessed at http://edocs.bea.com/wloc/docs10/schemaref/metadata/loc-metadata.xsd.
The Service Metadata Configuration Schema Reference.
The sample metadata configuration file provided when WLOC is installed. The name and location of this file is: BEA_HOME\user_projects\controller\config\metadata-config.xml.SAMPLE.

Resource Requirements

When using the console to define a service’s processes, the console solicits information about the service’s resource requirements. This information constitutes the service’s out-of-gate deployment policies and is saved in the form of constraints and actions.

Resource requirements specify the required amount physical computing resources for each instance in a process group. For example, to create a process group that includes a WebLogic Server domain, specify resource requirements for running all WebLogic Server instances. You can specify that a WebLogic cluster needs a minimum of 400 MHz of CPU cycles and 400 MB of RAM and can scale up to a maximum of 800 MHz of CPU and 800 MB of RAM.

These requirements do not include resources needed to run software outside of the process group, but declared as a dependency. For example, if a process group specifies that it requires a RDBMS system, the resource requirements do not include computing resources for the RDBMS.

Resource requirements are specified in terms of minimum and maximum amounts. The minimum requirement specifies the smallest amount of resources that must be reserved for exclusive use by a process group. As the resources consumed by a process group approach the minimum, a WLOC policy can request additional resources up to the maximum requirement.

WLOC may not be able to actually obtain additional resources if all available resources are being consumed by other WLOC resource pools or non-WLOC applications. For example, Figure 5-1 shows a hypervisor resource pool containing two WLOC resource pools. Although the pool provides 600 MB of memory, the WLOC Resource Pool has two services, each configured for a minimum of 200 MB and maximum of 400 MB. While both services can consume the minimum required memory (200 MB) at the same time, they cannot simultaneously consume the maximum. In Figure 5-1, service 1 is consuming 400 MB, so the total amount of consumed memory is 600 MB. Service 2 cannot use additional memory until service 1 decreases its memory consumption.

Ready Metrics

WLOC needs to know when a process has successfully started and is ready for work. This is made possible by specifying the process group’s ready metric. When defined, the action to start an instance is not considered complete until the ready metric is satisfied. If the ready metric isn't satisfied in a configurable amount of time, then the instance is considered failed and will be stopped.

Table 5-2 Ready Metric
Ready Metric Attribute	Description
Instance Name	The name of the MBean that has the attribute to test. Example: `com.bea:Name=AdminServer,Type=ServerRuntime`
Attribute	The name of the MBean attribute to test. Example: `state`. For more information about the format to use to specify MBean attributes, see WebLogic Server MBean Reference.
Value	A constant value to test the MBean attribute against. This field is valid only if the Operator is set to `Value` `Equals`. For example: RUNNING.
Operator	The operator (`Value Equals` or `Value` `Exists`).
Value Type	The value type (Integer, Long, Float, Double, Boolean, Date, String). The default is `Integer`.
Wait	(Optional) The number of milliseconds to wait after the ready metric constraint is satisfied before the process is considered ready.

Table 5-3 specifies a ready metric that reports a JVM instance is in RUNNING state:

Table 5-3 WebLogic Server Instance Ready Metric Configuration
Ready Metric Attribute	Value
Ready metric instance	Name=com.bea:AdminServer,Type=ServerRuntime
Attribute	State
Value	RUNNING
Operator	ValueEquals
Value Type	String
Wait	30000

JVM Arguments

For proper operation and tuning, managed applications must typically start with a specific set of JVM arguments . For each process group, you can specify the JVM arguments to use when the process starts.

The WLOC plain agent uses a management server to obtain the current CPU and memory use of a service. For plain agents, you must be sure to turn on the management server. To do so, include the following JVM arguments in the process group specification. Note that the port number must be a unique on each machine. The default port is 7091.

For JVMs running on JRockit before version 150_11, use the following single argument:

For JVMs running on JRockit version 150_11 and above, use the following two arguments:

These arguments are not needed for process groups managed by a Hypervisor Agent.

Listing 5-3 provides an example of the JVM arguments as contained in metadata-config.xml.

<ns2:jvm-args>
	<ns2:arg>-Xmx128m</ns2:arg>
	<ns2:arg>-Xms64m</ns2:arg>
	<ns2:arg>-da</ns2:arg>
	<ns2:arg>-cp</ns2:arg> 	
	<ns2:arg>CLASSPATH=C:\bea\patch_weblogic921\profiles\default\
	sys_manifest_classpath\weblogic_patch.jar;C:\bea\WEBLOG~1\server\
	lib\weblogic_sp.jar;C:\bea\WEBLOG~1\server\lib\weblogic.jar;C:\bea\
	WEBLOG~1\server\lib\webservices.jar;</ns2:arg>
	<ns2:arg>-Dwls.home=C:\bea\weblogic92\server</ns2:arg>
	<ns2:arg>-Dweblogic.management.discover=true</ns2:arg>
	<ns2:arg>-Dweblogic.Name=AdminServer</ns2:arg>
	<ns2:arg>-Dweblogic.management.username=weblogic</ns2:arg>
	<ns2:arg>-Dweblogic.management.password=weblogic</ns2:arg>
	<ns2:arg>-Djava.security.policy=C:\bea\weblogic92\server\lib\
	weblogic.policy</ns2:arg>
	<ns2:arg>-Dweblogic.RootDirectory=C:\bea\user_projects\domains\
	WLOCdomain</ns2:arg>
</ns2:jvm-args>

Classpath

Among the JVM required arguments is the classpath needed to start the JVM instance. This section describes how to obtain the classpath in different environments.

JVMs on Plain Agents

For WebLogic Server, execute the setDomainEnv command and obtain the WLS classpath by echoing CLASSPATH environment variable. Examples:

Windows — \bin\setDomainEnv.cmdSolaris/Linux — ./bin/setDomainEnv.sh

For generic Java applications, set the classpath based on application installation on plain agent host. Examples:

Windows — c:\apps\myapp\lib\myapp1.jar;C:\apps\myapp\lib\myapp2.jarSolaris/Linux — /apps/myapp/lib/myapp1.jar;C:/apps/myapp/lib/myapp2.jar

LiquidVMs

Classpath elements can be sourced anywhere from LiquidVM file system. If the element is in the iso, the path must begin with '/appliance' since the iso is mounted on '/appliance'. If the element is in a NFS share, then the path must begin with the NFS mount point. If the element is in the local disk, then the path would begin with '/'.

For WLS-VE 9.2v1.0, the standard classpath as set by the commonStartVE script is:

/bea/patch_weblogic921/profiles/default/sys_manifest_classpath/weblogic_patch.jar:/appliance/java/lib/tools.jar:/appliance/bea/weblogic92/server/lib/weblogic.jar:/appliance/bea/weblogic92/server/lib/webservices.jar

WLS-VE 9.2v1.1 standard classpath as set by the commonStartVE script is:

/bea/patch_weblogic922/profiles/default/sys_manifest_classpath/weblogic_patch.jar:/appliance/java/lib/tools.jar:/appliance/bea/weblogic92/server/lib/weblogic.jar:/appliance/bea/weblogic92/server/lib/webservices.jar:

For generic Java application on LVM, an example classpath is as follows:

/mynfs/patches/myapp_patch1.jar:/patches/myapp_patch2.jar:/appliance/applications/myapp/lib/myapp1.jar:/appliance/applications/myapp/lib/myapp2.jar

Service Deployment

The state of a service is undeployed until it is started. When the service is started, the following occurs:

The Controller evaluates the process requirements of each process group in the service.
The Controller compares the resource pools available for each process group in the service against the resource agreements and eliminates any resource pools that cannot host the service.
To determine the resource pool on which to place the service, the Controller uses the placement algorithm specified when the service was defined.
The Controller stages each instance individually. When the minimum number of processes from each group is started, the service is deployed.
The Controller evaluates the runtime policy and initiates the specified actions when a constraint is violated.
The Controller continually evaluates the runtime policy using information if obtains from the managed application.

Deploying Services in Virtualized Environments

When WLOC deploys a service, it first searches for the set of placement organizations that match the given constraints for memory, CPU, and such factors as software and IP address. A service’s placement-algorithm attribute affects placement organization and specifies whether you want VMs placed into pools so that there is as little memory resource left over as possible (PreferSmaller) or as much left over as possible (PreferLarger). The default is PreferLarger.

Configuration Guide