Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide

Configuring the Load Balancer

A load balancer configuration is a named configuration in the domain.xml file. Load balancer configuration is extremely flexible:

Each load balancer configuration can have multiple load balancers associated with it, though each load balancer has only one load balancer configuration.
A load balancer services only one domain, though a domain can have multiple load balancers associated with it.

This section describes how to create, modify, and use a load balancer configuration, including the following topics:

Creating an HTTP Load Balancer Configuration

Create a load balancer configuration using the asadmin command create-http-lb-config. Creating an HTTP Load Balancer Configuration describes the parameters. For more information see the documentation for create-http-lb-config, delete-http-lb-config, and list-http-lb-configs.

Table 4–1 Load Balancer Configuration Parameters


Parameter	Description
response timeout	Time in seconds within which a server instance must return a response. If no response is received within the time period, the server is considered unhealthy. The default is 60.
HTTPS routing	Whether HTTPS requests to the load balancer result in HTTPS or HTTP requests to the server instance. For more information, see Configuring HTTPS Routing.
reload interval	Interval between checks for changes to the load balancer configuration file `loadbalancer.xml`. When the check detects changes, the configuration file is reloaded. A value of 0 disables reloading.For more information, see Enabling Dynamic Reconfiguration
monitor	Whether monitoring is enabled for the load balancer.
routecookie	Name of the cookie the load balancer plug-in uses to record the route information. The HTTP client must support cookies. If your browser is set to ask before storing a cookie, the name of the cookie is JROUTE.
target	Target for the load balancer configuration. If you specify a target, it is the same as adding a reference to it. Targets can be clusters or stand-alone instances.

Creating an HTTP Load Balancer Reference

When you create a reference in the load balancer to a stand-alone server or cluster, the server or cluster is added to the list of target servers and clusters the load balancer controls. The referenced server or cluster still needs to be enabled (using enable-http-lb-server) before requests to it are load balanced. If you created the load balancer configuration with a target, that target is already added as a reference.

Create a reference using create-http-lb-ref. You must supply the load balancer configuration name and the target server instance or cluster.

To delete a reference, use delete-http-lb-ref. Before you can delete a reference, the referenced server or cluster must be disabled using disable-http-lb-server .

For more information, see the documentation for create-http-lb-ref and delete-http-lb-ref.

Enabling Server Instances for Load Balancing

After creating a reference to the server instance or cluster, enable the server instance or cluster using enable-http-lb-server . If you used a server instance or cluster as the target when you created the load balancer configuration, you must enable it.

For more information, see the documentation for enable-http-lb-server .

Enabling Applications for Load Balancing

All servers managed by a load balancer must have homogenous configurations, including the same set of applications deployed to them. Once an application is deployed and enabled for access (this happens during or after the deployment step) you must enable it for load balancing. If an application is not enabled for load balancing, requests to it are not load balanced and failed over, even if requests to the servers the application is deployed to are load balanced and failed over.

When enabling the application, specify the application name and target. If the load balancer manages multiple targets (for example, two clusters), enable the application on all targets.

For more information, see the online help for enable-http-lb-application .

If you deploy a new application, you must also enable it for load balancing and export the load balancer configuration again.

Creating the HTTP Health Checker

The load balancer’s health checker periodically checks all the configured Application Server instances that are marked as unhealthy. A health checker is not required, but if no health checker exists, or if the health checker is disabled, the periodic health check of unhealthy instances is not performed.

The load balancer’s health check mechanism communicates with the application server instance using HTTP. The health checker sends an HTTP request to the URL specified and waits for a response. A status code in the HTTP response header between 100 and 500 means the instance is healthy.

Creating a Health Checker

To create the health checker, use the asadmin create-http-health-checke r command. Specify the following parameters:

Table 4–2 Health Checker Parameters


Parameter	Description	Default
url	Specifies the listener’s URL that the load balancer checks to determine its state of health.	“/”
interval	Specifies the interval in seconds at which health checks of instances occur. Specifying 0 disables the health checker.	30 seconds
timeout	Specifies the timeout interval in seconds within which a response must be obtained for a listener to be considered healthy.	10 seconds

If an application server instance is marked as unhealthy, the health checker polls the unhealthy instances to determine if the instance has become healthy. The health checker uses the specified URL to check all unhealthy application server instances to determine if they have returned to the healthy state.

If the health checker finds that an unhealthy instance has become healthy, that instance is added to the list of healthy instances.

For more information see the documentation for create-http-health-checker and delete-http-health-checker.

Additional Health Check Properties for Healthy Instances

The health checker created by create-http-health-checker only checks unhealthy instances. To periodically check healthy instances set some additional properties in your exported loadbalancer.xml file.

Note –

These properties can only be set by manually editing loadbalancer.xml after you’ve exported it. There is no equivalent asadmin command to use.

To check healthy instances, set the following properties:

Table 4–3 Health-checker Manual Properties


Property	Definition
active-healthcheck-enabled	True/false flag indicating whether to ping healthy server instances to determine whether they are healthy. To ping server instances, set the flag to true.
number-healthcheck-retries	Specifies how many times the load balancer’s health checker pings an unresponsive server instance before marking it unhealthy. Valid range is between 1 and 1000. A default value to set is 3.

Set the properties by editing the loadbalancer.xml file. For example:

<property name="active-healthcheck-enabled" value="true"/>
<property name="number-healthcheck-retries" value="3"/>

If you add these properties, then subsequently edit and export the loadbalancer.xml file again, you must add these properties to the file again, since the newly exported configuration won’t contain them.

Exporting the Load Balancer Configuration File

The load balancer plug-in shipped with Sun Java System Application Server uses a configuration file called loadbalancer.xml. Use the asadmin tool to create a load balancer configuration in the domain.xml file. After configuring the load balancing environment, export it to a file.

To export the load balancer configuration

Export a loadbalancer.xml file using the asadmin command export-http-lb-config.

Export the loadbalancer.xml file for a particular load balancer configuration. You can specify a path and a different file name. If you don’t specify a file name, the file is named loadbalancer.xml. load_balancer_config_name. If you don’t specify a path, the file is created in the application_server_install_dir /domains/domain_name /generated directory.

To specify a path on Windows, use quotes around the path. For example, "c:\sun\AppServer\loadbalancer.xml" .

Copy the exported load balancer configuration file to the web server’s configuration directory.

For example, for the Sun Java System Web Server, that location might be web_server_root/config .

The load balancer configuration file in the web server’s configuration directory must be named loadbalancer.xml. If your file has a different name, such as loadbalancer.xml. load_balancer_config_name, you must rename it.

Changing the Load Balancer Configuration

If you change a load balancer configuration by creating or deleting references to servers, deploying new applications, enabling or disabling servers or applications, and so on, export the load balancer configuration file again and copy it to the web server’s config directory. For more information, see Exporting the Load Balancer Configuration File

The load balancer plug-in checks for an updated configuration periodically based on the reload interval specified in the load balancer configuration. After the specified amount of time, if the load balancer discovers a new configuration file, it starts using that configuration.

Enabling Dynamic Reconfiguration

With dynamic reconfiguration, the load balancer plug-in periodically checks for an updated configuration.

To enable dynamic reconfiguration:

When creating a load balancer configuration, use the --reloadinterval option with asadmin create-http-lb-config .

This option sets the amount of time between checks for changes to the load balancer configuration file loadbalancer.xml. A value of 0 disables dynamic reconfiguration. By default, dynamic reconfiguration is enabled, with a reload interval of 60 seconds.
If you have previously disabled it, or to change the reload interval, use the asadmin set command.

After changing the reload interval, export the load balancer configuration file again and copy it to the web server’s config directory, then restart the web server.

Note –

If the load balancer encounters a hard disk read error while attempting to reconfigure itself, then it uses the configuration that is currently in memory. The load balancer also ensures that the modified configuration data is compliant with the DTD before over writing the existing configuration.

If a disk read error is encountered, a warning message is logged to the web server’s error log file.

The error log for Sun Java System Web Server’ is at: web_server_install_dir/webserver_instance /logs/.

Disabling (Quiescing) a Server Instance or Cluster

Before stopping an application server for any reason, you want the instance to complete serving requests. The process of gracefully disabling a server instance or cluster is called quiescing.

The load balancer uses the following policy for quiescing application server instances:

If an instance (either stand-alone or part of a cluster) is disabled, and the timeout has not expired, sticky requests continue to be delivered to that instance. New requests, however, are not sent to the disabled instance.
When the timeout expires, the instance is disabled. All open connections from the load balancer to the instance are closed. The load balancer does not send any requests to this instance, even if all sessions sticking to this instance were not invalidated. Instead, the load balancer fails over sticky requests to another healthy instance.

To disable a server instance or cluster

Run asadmin disable-http-lb-server, setting the timeout (in minutes).

Export the load balancer configuration file using asadmin export-http-lb-config.

Copy the exported configuration to the web server config directory.

Stop the server instance or instances.

Disabling (Quiescing) an Application

Before you undeploy a web application, you want to the application to complete serving requests. The process of gracefully disabling an application is called quiescing. When you quiesce an application, you specify a timeout period. Based on the timeout period, the load balancer uses the following policy for quiescing applications:

If the timeout has not expired, the load balancer does not forward new requests to the application, but returns them to the web server. However, the load balancer continues to forward sticky requests until the timeout expires.
When the timeout expires, the load balancer does not accept any requests for the application, including sticky requests.

When you disable an application from every server instance or cluster the load balancer references, the users of the disabled application experience loss of service until the application is enabled again. If you disable the application from one server instance or cluster while keeping it enabled in another server instance or cluster, users can still access the application.

To disable an application

Use asadmin disable-http-lb-application, specifying the following:
- Timeout (in minutes).
- Name of the application to disable.
- Target cluster or instance on which to disable it.

Export the load balancer configuration file using asadmin export-http-lb-config.

Copy the exported configuration to the web server config directory.

Configuring HTTP and HTTPS Failover

The load balancer plug-in fails over HTTP/HTTPS sessions to another application server instance if the original application server instance to which the session was connected becomes unavailable. This section describes how to configure the load balancer plug-in to enable HTTP/HTTPS routing and session failover.

This section discusses the following topics:

HTTPS Routing

The HTTP Secure (HTTPS) protocol uses Secure Sockets Layer (SSL) to provide encryption an decryption of HTTP requests for secure communication. For HTTPS routing to work, one or more HTTPS listeners must be configured.

The load balancer plug-in routes all incoming HTTP or HTTPS requests to application server instances. However, if HTTPS routing is enabled, an HTTPS request will be forwarded by the load balancer plug-in to the application server using an HTTPS port only. HTTPS routing is performed on both new and sticky requests.

If an HTTPS request is received and no session is in progress, then the load balancer plug-in selects an available application server instance with a configured HTTPS port, and forwards the request to that instance.

In an ongoing HTTP session, if a new HTTPS request for the same session is received, then the session and sticky information saved during the HTTP session is used to route the HTTPS request. The new HTTPS request is routed to the same server where the last HTTP request was served, but on the HTTPS port.

Configuring HTTPS Routing

The httpsrouting option of the create-http-lb-config command controls whether HTTPS routing is turned on or off for all the application servers that are participating in load balancing. If this option is set to false, all HTTP and HTTPS requests are forwarded as HTTP. Set it to true when creating a new load balancer configuration, or change it later using the asadmin set command.

Note –

If https-routing is set to true, and a new or a sticky request comes in where there are no healthy HTTPS listeners in the cluster, then that request generates an error.

Known Issues

The Load Balancer has the following limitations with HTTP/HTTPS request processing.

If a session uses a combination of HTTP and HTTPS requests, then the first request must be an HTTP Request. If the first request is an HTTPS request, it cannot be followed by an HTTP request. This is because the cookie associated with the HTTPS session is not returned by the browser. The browser interprets the two different protocols as two different servers, and initiates a new session.

This limitation is valid only if httpsrouting is set to true .
If a session has a combination of HTTP and HTTPS requests, then the application server instance must be configured with both HTTP and HTTPS listeners.

This limitation is valid only if httpsrouting is set to true.
If a session has a combination of HTTP and HTTPS requests, then the application server instance must be configured with HTTP and HTTPS listeners that use standard port numbers, that is, 80 for HTTP, and 443 for HTTPS. This limitation applies regardless of the value set for httpsrouting.

Configuring Idempotent URLs

An idempotent request is one that does not cause any change or inconsistency in an application when retried. In HTTP, some methods (such as GET) are idempotent, while other methods (such as POST) are not. Retrying an idempotent URL must not cause values to change on the server or in the database. The only difference is a change in the response received by the user.

Examples of idempotent requests include search engine queries and database queries. The underlying principle is that the retry does not cause an update or modification of data.

To enhance the availability of deployed applications, configure the environment to retry failed idempotent HTTP requests on all the application server instances serviced by a load balancer. This option is used for read-only requests, for example, to retry a search request.

Configure idempotent URLs in the sun-web.xml file. When you export the load balancer configuration, idempotent URL information is automatically added to the loadbalancer.xml file.

For more information on configuring idempotent URLs, see Configuring Idempotent URL Requests in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer’s Guide.