4 Understanding Cluster Configuration

Learn how the information that defines the configuration of a Oracle WebLogic Server cluster is stored and maintained, and the methods you can use to accomplish configuration tasks.

Note:

Information in this section pertains to configure a WebLogic domain in which the server instances are not clustered.

This chapter includes the following sections:

• Cluster Configuration and config.xml
  The config.xml file is an XML document that describes the configuration of a WebLogic Server domain.
• Role of the Administration Server
  The Administration Server is the WebLogic Server instance that configures and manages the WebLogic Server instances in its domain.
• How Dynamic Configuration Works
  WebLogic Server allows you to change the configuration attributes of domain resources dynamically—while server instances are running. In most cases you do not need to restart the server instance for your changes to take effect. When an attribute is reconfigured, the new value is immediately reflected in both the current runtime value of the attribute and the persistent value stored in config.xml.
• Application Deployment for Clustered Configurations
  Here is a brief introduction to the application deployment process.
• Methods of Configuring Clusters
  You can configure clusters using any one of several WebLogic Server administration tools and methods, such as the Configuration Wizard, WebLogic Server Administration Console, FMWC, WebLogic Server API, WLST, and Java Management Extensions (JMX).

Cluster Configuration and config.xml

The config.xml file is an XML document that describes the configuration of a WebLogic Server domain.

The config.xml file consists of a series of XML elements. The <domain> element is the top-level element, and all elements in the domain descend from the <domain> element. The <domain> element includes child elements, such as the <server>, <cluster>, <application>, and so on. These child elements may have children of their own. For example, the <server> element includes the child elements <WebServer>, <SSL>, and <Log>. The <application> element includes the child elements <EJBComponent> and <WebAppComponent>.

Each element has one or more configurable attributes. An attribute defined in config.dtd has a corresponding attribute in the configuration API. For example, the Server element has a ListenPort attribute, and likewise, the weblogic.management.configuration.ServerMBean has a ListenPort attribute. Configurable attributes are readable and writable, that is, ServerMBean has a getListenPort and a setListenPort method.

To learn more about the config.xml file, see Domain Configuration Files in Understanding Domain Configuration for Oracle WebLogic Server.

Role of the Administration Server

The Administration Server is the WebLogic Server instance that configures and manages the WebLogic Server instances in its domain.

A domain can include multiple WebLogic Server clusters and non-clustered WebLogic Server instances. Strictly speaking, a domain could consist of only one WebLogic Server instance. However, in that case that sole server instance would be an Administration Server, because each domain must have exactly one Administration Server.

There are varieties of ways to invoke the services of the Administration Server to accomplish configuration tasks, as described in Methods of Configuring Clusters. Whichever method you use, the Administration Server for a cluster must be running when you modify the configuration.

When the Administration Server starts, it loads the config.xml for the domain. It looks for config.xml in the directory:

ORACLE_HOME/user_projects/domains/domain_name/config

where domain_name is a domain-specific directory, with the same name as the domain.

Note:

Do not add non-configuration files in the config directory or subdirectories. Non-configuration files include log (.log) and lock (.lck) files. Administration Server replicates the config directory in all Managed Server instances. Storing non-configuration files in the config directory can cause performance issues in the domain.

Each time the Administration Server starts successfully, a backup configuration file named config.xml.booted is created in the domain directory. In the unlikely event that the config.xml file should be corrupted during the lifetime of the server instance, it is possible to revert to this previous configuration.

Figure 4-1 shows a typical production environment that contains an Administration Server and multiple WebLogic Servers instances. When you start the server instances in such a domain, the Administration Server is started first. As each additional server instance is started, it contacts the Administration Server for its configuration information. In this way, the Administration Server operates as the central control entity for the configuration of the entire domain.

Figure 4-1 WebLogic Server Configuration

Description of "Figure 4-1 WebLogic Server Configuration"

• What Happens if the Administration Server Fails?
  

What Happens if the Administration Server Fails?

The failure of an Administration Server for a domain does not affect the operation of Managed Servers in the domain. If an Administration Server for a domain becomes unavailable while the server instances it manages (clustered or otherwise) are up and running, those Managed Servers continue to run. If the domain contains clustered server instances, the load balancing and failover capabilities supported by the domain configuration remain available, even if the Administration Server fails.

Note:

If an Administration Server fails because of a hardware or software failure on its host machine, other server instances on the same machine may be similarly affected. However, the failure of an Administration Server itself does not interrupt the operation of Managed Servers in the domain.

For instructions on re-starting an Administration Server, see Avoiding and Recovering from Server Failure in Administering Server Startup and Shutdown for Oracle WebLogic Server.

How Dynamic Configuration Works

WebLogic Server allows you to change the configuration attributes of domain resources dynamically—while server instances are running. In most cases you do not need to restart the server instance for your changes to take effect. When an attribute is reconfigured, the new value is immediately reflected in both the current runtime value of the attribute and the persistent value stored in config.xml.

However, not all configuration changes are applied dynamically. For example, if you change a Managed Server's ListenPort value, the new port will not be used until the next time you start the Managed Server. The updated value is stored in config.xml, but the runtime value is not affected.

The WebLogic Server Administration Console validates attribute changes, checking for out-of-range errors and data type mismatch errors, and displays an error message for erroneous entries.

Once the WebLogic Server Administration Console has been started, if another process captures the listen port assigned to the Administration Server, you should stop the process that captured the port. If you are not able to remove the process that captured the listen port, edit the config.xml file to change the ListenPort value.

Application Deployment for Clustered Configurations

Here is a brief introduction to the application deployment process.

For more information about introduction to the application deployment process, see Deploying Applications to Oracle WebLogic Server.

For instructions on how to perform common deployment tasks, see Deploy Applications.

• Deployment Methods
  
• Introduction to Two-Phase Deployment
  
• Guidelines for Deploying to a Cluster
  

Deployment Methods

You can deploy an application to a cluster using following methods:

• WebLogic Server Administration Console and Fusion Middleware Control (FMWC)

  The WebLogic Server Administration Console and FMWC are graphical user interfaces (GUI) to the Administration Service.

• weblogic.Deployer

  The weblogic.Deployer utility is a Java-based deployment tool that provides a command-line interface to the WebLogic Server deployment API.

• WebLogic Scripting Tool (WLST)

  The WLST is a command-line interface that you can use to automate domain configuration tasks, including application deployment configuration and deployment operations.

These deployment tools are discussed in Deployment Tools in Deploying Applications to Oracle WebLogic Server.

Regardless of the deployment tool you use, when you initiate the deployment process, specify the components to be deployed and the targets to which they will be deployed (your cluster or individual server instances within the cluster or domain).

The Administration Server for the domain manages the deployment process, communicating with the Managed Servers in the cluster throughout the process. Each Managed Server downloads components to be deployed, and initiates local deployment tasks. The deployment state is maintained in the relevant MBeans for the component being deployed. See Deployment Management API.

Note:

You must package applications before you deploy them to WebLogic Server. See Packaging Applications Using wlpackage in Developing Applications for Oracle WebLogic Server.

Introduction to Two-Phase Deployment

In WebLogic Server, applications are deployed in two phases. Before starting, WebLogic Server determines the availability of the Managed Servers in the cluster.

• First Phase of Deployment
  
• Second Phase of Deployment
  

First Phase of Deployment

During the first phase of deployment, application components are distributed to the target server instances, and the planned deployment is validated to ensure that the application components can be successfully deployed. During this phase, user requests to the application being deployed are not allowed.

Failures encountered during the distribution and validation process will result in aborted deployment on all server instances (including those upon which the validation succeeded). Files that have been staged will not be removed; however, container-side changes performed during the preparation will be reverted.

Second Phase of Deployment

After the application components have been distributed to targets and validated, they are fully deployed on the target server instances, and the deployed application is made available to clients.

When a failure is encountered during the second phase of deployment, the server starts with one of the following behaviors:

• If a failure occurs while deploying to the target server instances, the server instance will start in ADMIN state. See ADMIN State in Administering Server Startup and Shutdown for Oracle WebLogic Server.

• If cluster member fails to deploy an application, the application that failed to deploy is made unavailable.

Guidelines for Deploying to a Cluster

Ideally, all Managed Servers in a cluster should be running and available during the deployment process. Deploying applications while some members of the cluster are unavailable is not recommended. Before deploying applications to a cluster, ensure that all Managed Servers in the cluster are running and reachable by the Administration Server.

Note:

If you deploy an application to a Managed Server that is partitioned at the time of deployment—running but not reachable by the Administration Server—problems accessing the Managed Server can occur when that Managed Server rejoins the cluster. During the synchronization period, while other clustered Managed Servers re-establish communications with the previously partitioned server instance, user requests to the deployed applications and attempts to create secondary sessions on that server instance will fail. The risk of this circumstance occurring can be reduced by setting ClusterConstraintsEnabled, as described in Enforcing Consistent Deployment to All Configured Cluster Members in Deploying Applications to Oracle WebLogic Server.

Cluster membership should not change during the deployment process. After initiating deployment, do not:

• add or remove Managed Servers to the target cluster.

• shut down Managed Servers in the target cluster.

• WebLogic Server Supports "Relaxed Deployment" Rules
  

WebLogic Server Supports "Relaxed Deployment" Rules

Previous versions of WebLogic Server imposed these restrictions on deployment to clusters:

• No partial deployment: If one or more of the Managed Servers in the cluster are unavailable, the deployment process is terminated, and an error message is generated, indicating that unreachable Managed Servers should be either restarted or removed from the cluster before attempting deployment.

• Pinned services cannot be deployed to multiple Managed Servers in a cluster: If an application is not deployed to the cluster, you can deploy it to only one Managed Server in the cluster.

• Deployment to a Partial Cluster is Allowed
  
• Deploying to Complete Clusters in WebLogic Server
  
• Pinned Services can be Deployed to Multiple Managed Servers.
  

Deployment to a Partial Cluster is Allowed

By default, Oracle WebLogic Server allows deployment to a partial cluster. If one or more of the Managed Servers in the cluster are unavailable, the following message may be displayed:

Unable to contact "servername". Deployment is deferred until "servername" becomes available.

When the unreachable Managed Server becomes available, deployment to that server instance will be initiated. Until the deployment process is completed, the Managed Server may experience failures related to missing or out-of-date classes.

Deploying to Complete Clusters in WebLogic Server

You can ensure that deployment is only performed if all Managed Servers in the cluster are reachable by setting ClusterConstraintsEnabled. When ClusterConstraintsEnabled is set to "true", a deployment to a cluster succeeds only if all members of the cluster are reachable and all can deploy the specified files. See Enforcing Consistent Deployment to All Configured Cluster Members in Deploying Applications to Oracle WebLogic Server.

Pinned Services can be Deployed to Multiple Managed Servers.

It is possible to target a pinned service to multiple Managed Servers in a cluster. This practice is not recommended. The load-balancing capabilities and scalability of your cluster can be negatively affected by deploying a pinned service to multiple Managed Servers in a cluster. If you target a pinned service to multiple Managed Servers, the following message is printed to the server logs:

Adding server servername of cluster clustername as a target for
module modulename. This module also includes server servername that
belongs to this cluster as one of its other targets. Having multiple
individual servers in a cluster as targets instead of having the entire
cluster as the target can result in non-optimal load balancing and
scalability. Hence this is not usually recommended.

Methods of Configuring Clusters

You can configure clusters using any one of several WebLogic Server administration tools and methods, such as the Configuration Wizard, WebLogic Server Administration Console, FMWC, WebLogic Server API, WLST, and Java Management Extensions (JMX).

• Configuration Wizard

  The Configuration Wizard is the recommended tool for creating a new domain or cluster. See Introduction in Creating WebLogic Domains Using the Configuration Wizard.

  For more information about creating and configuring a cluster, see Clusters in Creating WebLogic Domains Using the Configuration Wizard.

• WebLogic Server Administration Console and FMWC

  The WebLogic Server Administration Console and FMWC are GUI to the Administration Service. They allow you to perform a variety of domain configuration and monitoring functions.

• WebLogic Server API

  You can write a program to modify the configuration attributes, based on the configuration API provided with WebLogic Server. This method is not recommended for initial cluster implementation.

• WebLogic Scripting Tool (WLST)

  The WLST is a command-line scripting interface that system administrators and operators use to monitor and manage WebLogic Server instances and domains. See Understanding the WebLogic Scripting Tool.

• Java Management Extensions (JMX)

  JMX is the Java EE solution for monitoring and managing resources on a network. WebLogic Server provides a set of MBeans that you can use to configure, monitor, and manage WebLogic Server resources through JMX.