Automating WebLogic Platform Application Provisioning: A Case Study

by Chengjiang (Andy) Lin
05/09/2005

Abstract

BEA WebLogic Platform application provisioning is the process of preparing and providing a valid WebLogic Platform environment to support subsequent usage by the deployed applications. In a previous article, an overview was provided on what to expect when promoting a WebLogic Platform 8.1 application from development to production through multiple stages. In this article, the focus is on automating the application provisioning process at each stage using tools that are available for use with the WebLogic Platform product. This should enable you to automatically create the necessary environment in which WebLogic applications should run.

Introduction

WebLogic Platform application provisioning is the process of preparing and providing a valid WebLogic Platform environment to support subsequent usage by the application. The WebLogic Platform environment typically consists of three types of resources: domain-level resources (such as JDBC Connection Pools, and DataSources), customer applications, and production data (such as security roles, cache policies, Portal metadata, and Trading Partner Management data). When promoting a WebLogic application from development to production through multiple stages, these resources need to be properly provisioned at each stage. Given the complexity of configuring domain-level and application-scoped resources, application provisioning is not a trivial process and is often manual-intensive and error-prone. It is therefore highly desirable to automate the provisioning process to improve production efficiency and reliability, and at the same time reduce IT cost.

This article first discusses the challenge with automating the application provisioning process. It then provides an overview of the provisioning tools available with the WebLogic Platform. Through case studies on some common scenarios such as moving from development to production, rapid production replication, production data provisioning, and differential provisioning, this article demonstrates how these provisioning tools can be effectively used to automate the provisioning process.

The examples provided in this article are abstracted from some real customer provisioning scenarios. The WebLogic Scripting Tool (WLST) sample scripts and domain templates referenced in this article have been developed and tested on WebLogic Platform 8.1 Service Pack 4. In the coming WebLogic Platform release, JSR-88 will be supported. Therefore, some resources now configured at domain level will be packaged as application-scoped resources. This should make our lives a little easier with application provisioning automation.

Note that this article is not intended to be a tutorial on using the provisioning tools such as Domain Template Builder or WLST. You can find more information on these tools through the links provided in the References section.

The Challenge

To run WebLogic Platform applications, you must create a domain that includes the appropriate WebLogic Platform components, as well as application-scoped resources. Figure 1 depicts an example promoting process that takes an application through four stages: development, integration, QA/staging, and production. In production, WebLogic Platform application provisioning also involves setting up a cluster subnet and proxies per application deployment requirements.

Figure 1
Figure 1. Application promotion from development to production

In a typical development stage, multiple developers will be concurrently working on a project with each focusing on different modules. Developers are likely to have their own working domains (development-mode, single server with local database) as their sandbox, using a source control tool to facilitate team development. In a development-mode domain, BEA WebLogic Server and BEA WebLogic Workshop will automatically provision some application resources, such as Entity Bean tables, AsyncDispatcher queues, and conversation state tables. These resources need to be explicitly provisioned in a production-mode domain. The QA/staging environment normally mimics the real production environment, which typically consists of one or more cluster domains, along with dedicated database servers, load balancers, and commercial certificates. Security and high availability are critical in production, while they may be wholly absent from the development environment. In addition, if you use different IP addresses or ports for the managed servers in production, you also need to update your application modules and regenerate the EAR file for custom deployment.

When promoting WebLogic Platform applications from development to production through multiple stages, it is critical to automate the process to ensure a successful production deployment. The key challenge for provisioning automation is to identify and capture what exactly needs to be configured to support proper deployment of the applications, carry that information forward through each stage, and then apply any configuration customizations that are necessary for the target environment.

WebLogic Platform provides a rich set of system tools such as the Configuration Wizard, the Domain Template Builder, and the WebLogic Scripting Tool (WLST) to facilitate provisioning automation. For a complete list of tools, refer to the WebLogic Platform Deployment Guide. The WebLogic Platform also ships with a set of predefined domain templates, to help customers with initial domain configuration, and a set of extension templates for adding well-defined applications and services to existing domains. Depending on the characteristics of various provisioning scenarios, they can be categorized into the template-based approach and the WLST-based approach. Note that these approaches can be effectively combined to address complex provisioning scenarios.

Template-based Provisioning

The predefined domain and extension templates contain the main attributes and files required for building or extending a particular WebLogic domain. After you have added new resources and applications to your domain, you can use the Domain Template Builder to create a custom domain template, which can be used later for creating a target domain through the Configuration Wizard.

The template-based approach leverages the Domain Template Builder functionality to capture the various configuration details and artifacts of the current domain. To use the template-based approach, you would start with a working domain. It can be a single server development domain or a clustered production domain. In addition, you should have a thorough understanding of the existing domain so as not to miss out on including critical configuration information when creating the template. During template creation you have an opportunity to customize the settings of some domain resources, but you can also opt to apply customization in a later stage when you are actually configuring the domain using the created template.

WLST-based Provisioning

WebLogic Server Scripting Tool (WLST) is a command-line scripting interface (built with Jython) that you use to interact with and configure a WebLogic Server. WLST supports both online and offline modes of operation. WLST Online operates while connected to a running server. WLST Offline adds commands to support Configuration Wizard functionality, enabling creation and extension of WebLogic domains without being connected to a running server. WLST Offline supports the predefined domain templates provided with WebLogic Platform, as well as custom domain templates created using the Template Builder tool.

The WLST-based provisioning approach leverages the WLST Offline and WLST Online functionality to record the various domain configuration details in a set of WLST scripts and use these scripts along with some predefined or custom domain templates to create the target domain. Using the WLST-based approach, you can easily change domain configuration through scripts, and effectively track configuration changes through source control. For more information on using WLST, visit the dev2dev CodeShare project wlst for sample scripts and best practices.

In the next few sections, we will delve into some common provisioning use cases to demonstrate and compare the use of the template-based approach and the WLST-based approach.

Use Case: Moving from Development to Staging/Production

This use case represents a common provisioning scenario with high demand on automation. Typically, the development environment is dramatically different from the production environment, which makes the WLST-based approach a better fit compared to the template-based approach. Through a hypothetical scenario, we will illustrate how to combine WLST Offline and Online scripts to configure a desired production domain.

In this example, let's say the development team has implemented two applications: one BEA WebLogic Integration application and one BEA WebLogic Portal application. Both applications are deployed in a single platform domain with a single server instance. Moving to staging and production, the team wants to configure two separate clusters ( wliCluster and wlpCluster) in a single platform domain, one for deploying the WebLogic Integration application and the other for deploying the WebLogic Portal application. The Configuration Wizard and WLST Offline support auto-configuration for a single-cluster domain only. When configuring multiple clusters (for example, a wliCluster and a wlpCluster) in a single Platform domain through Configuration Wizard, domain-level resources will be automatically targeted to the first cluster (in this case, the wliCluster). Therefore, the target of some resources (such as the portal-related applications and resources) needs to be reassigned. The combination of WLST Offline and Online scripts can effectively address the specific requirements of configuring a multicluster domain.

In general, WLST Offline scripts can be used to configure the resources for any single cluster domain. For example, a WLST Offline script can add users, add managed servers, add additional JMS queues, customize JDBCConnectionPools, and so on. Since WLST Offline is based on the Config Wizard framework, it supports some nice auto-configuration features, but it has the same constraints on configuring multiple clusters. After the first cluster (wliCluster) is created, the portal-related applications and resources need to be untargeted from the wliCluster.

cd('/')

unassign('Application', 'paymentWSApp','Target', 'wliCluster')

unassign('Application', 'taxWSApp','Target', ' wliCluster ')

unassign('JDBCConnectionPool', 'portalPool','Target', ' wliCluster ')

unassign('JDBCDataSource','p13n_trackingDataSource', 'Target', ' wliCluster ')

unassign('JDBCDataSource', 'p13nDataSource','Target', ' wliCluster ')

unassign('JDBCTxDataSource','portalFrameworkPool', 'Target', ' wliCluster ')

The following WLST Online scripts illustrate the configuration of the second cluster ( wlpCluster) and proper retargeting of the portal-related resources to the wlpCluster.

def create_wlpcluster(cluster_config):



 clusterName, clusterAddr,multicastAddr,multicastPort, mss = cluster_config



 # create the cluster

 cluster = auto_createCluster(clusterName,clusterAddr, multicastAddr, multicastPort)



 # create the managed servers

 for msConfig in mss:

   managedserver = auto_createManagedServer(msConfig,cluster)



 # add the cluster to the target list of the following resources

 wlst.cd('/')



 jcf = wlst.getTarget('JMSConnectionFactory/' + 'cgQueue')

 if jcf != None:

   jcf.addTarget(cluster)



 poolList='portalPool','cgPool','cgJMSPool-nonXA'

 for poolName in poolList:

   pool = wlst.getTarget('JDBCConnectionPool/' + poolName)

   if pool != None:

     pool.addTarget(cluster)

  

 dsList='p13n_trackingDataSource','p13nDataSource'

 for dsName in dsList:

   ds = wlst.getTarget('JDBCDataSource/' + dsName)

   if ds != None:

     ds.addTarget(cluster)



 txdsList='portalFrameworkPool','cgDataSource','cgDataSource-nonXA'

 for txdsName in txdsList:

   txds = wlst.getTarget('JDBCTxDataSource/' + txdsName)

   if txds != None:

    txds.addTarget(cluster)



 wlst.cd('Application/' + 'JWSQueueTransport')



 ejb = wlst.getTarget('EJBComponent/' + 'QueueTransportEJB')

 if ejb != None:

   ejb.addTarget(cluster)

 wlst.cd('/')

Let's take a closer look at a portion of this script:

dsList='p13n_trackingDataSource','p13nDataSource'

for dsName in dsList:

  ds = wlst.getTarget('JDBCDataSource/' + dsName)

  if ds != None:

  ds.addTarget(cluster)

What this does is loop through the names of the DataSources that we know should be targeted to the new wlpCluster. For each DataSource, we first call the getTarget() method to get the DataSource object, and then we add the wlpCluster to its target list.

The complete sample scripts can be downloaded from the wlst CodeShare project.

In addition to configuring domain-level resources, we also need to support automatic provisioning (or migration as it is sometimes called) of critical production data, such as the WebLogic security realm, WebLogic Portal metadata, and WebLogic Integration metadata. Refer to the Production Data Provisioning section for more information.

Use Case: Rapid Production Replication

This use case depicts a particular provisioning scenario where the customer already has a working production domain properly configured on the administration server machine, and needs to replicate the same configuration to many managed server boxes in a WebLogic cluster domain. It is tedious and error-prone to run GUI-based tools on multiple remote machines. The template-based approach seems to be a good fit to automate the replication process. We illustrate how to use Domain Template Builder to capture what is in the production domain.

Assume this hypothetical domain is a WebLogic Integration cluster domain, called wlicluster, and that the customer originally was created using the Configuration Wizard with the WLI domain template. The following resources were subsequently deployed and configured to support the application needs:

  • An application, called tradeHubApp.ear, which uses message broker channels and event generators, and invokes a third-party adapter

  • A distributed queue, called egDistQueue, and its corresponding queue members

  • A JMS Event Generator, tradeHubJMSEG, that is associated with egDistQueue and an existing channel file

  • A third-party adapter, called kodo, with target to the cluster

Now we need to create a custom domain template to capture this entire configuration. By default the Template Builder will include files directly referenced by the domain. Other files needed by the deployed applications, such as the JMS Event Generator jar file and the third-party adapter files, can be added to the template through the Add File window (Figure 2).

Figure 2
Figure 2. Add files when creating a custom domain template.

For the aforementioned production domain, we need to add the following files:

  • Add the <wliconfig> folder to <Domain Root Directory> (note that you do not need to include the managed server subfolders under <wliconfig>)

  • Add the <script> folder to <Domain Root Directory>

  • Add the jar file corresponding to tradeHubJMSEG event generator (that is, WLIJmsEG_tradeHubJMSEG.jar) to <Domain Root Directory>

  • Add the DefaultAuthorizer.ldift file to <Domain Root Directory> since it defines default authorization roles and policies for accessing message broker channels

  • Add the adapter implementation folder to <Application Root Directory>/wlicluster

The above demonstrates a list of domain and application resources that have been captured in a domain template. If you have additional resources (such as security roles and policies), you will need to capture those resources separately using other tools provided by WebLogic Platform. The next use case illustrates how to use these tools to provision production data.

Use Case: Production Data Provisioning

In general, data in a WebLogic Platform production environment consists of security roles, cache policies, Portal metadata, Trading Partner Management (TPM) data, and other data that are typically stored in a variety of persistence stores such as embedded LDAP, external database, and repository files. The focus of this use case is on automating the process of production data provisioning.

WebLogic domain-level tables

Each WebLogic domain template (except the basic WebLogic Server domain template) has a predefined set of SQL files that needs to be loaded into the target database before the servers can be started. For example, the WebLogic Portal domain template defines the Content Management Database Objects and WSRP Objects tables that need to be loaded before you start a WebLogic Portal domain. These domain-level tables will be loaded to the production database and shared by all the servers in the domain. You can load these tables through the Configuration Wizard during domain creation, or through the loadDB() function in WLST Offline, which is depicted in the following scripts:

readTemplate('D:\<WL_HOME>\common\templates\domains\platform.jar')

existingPoolName = 'cgJMSPool-nonXA'

cd ('/')

cd ('JDBCConnectionPool/' + existingPoolName)

cmo.setDriverName('oracle.jdbc.driver.OracleDriver')

cmo.setUserName('E2EDCDB')

cmo.setPassword('E2EDCDB')

cmo.setURL('jdbc:oracle:thin:@<DBMS_HOST>:<PORT>:<DBMS_NAME>')

loadDB('9i',existingPoolName)

closeTemplate()

WebLogic Security realm

Each WebLogic Platform domain is configured with a default security realm that is typically stored in embedded LDAP. Each security realm consists of a set of configured security providers, users, groups, security roles, and security policies. The default realm can be customized to support various security requirements such as replacing a security provider and adding users. To support migration of security data from one realm to another, WebLogic Platform offers specific exporting/importing utilities through WebLogic Console and MBean interfaces.

BEA WebLogic Enterprise Security policy data

BEA WebLogic Enterprise Security (WLES) services use several distinct categories of policies to protect applications and resources. To enable you to transfer your policy data easily to a production environment, WLES provides Policy Export/Import tools. Policy exporting allows you to output data from the policy database to text files called policy files. These policy files can be imported back to the same or another policy database using the Policy Import tool. These tools have command-line interfaces that can be easily integrated to enable automation.

WebLogic Portal metadata

When you configure and customize WebLogic Portal applications, there are various portal objects (such as entitlements and delegated administration) stored in the embedded LDAP and the portal database. The WebLogic Portal Propagation Utility enables Portal administrators to move data from one stage to another selectively, with the ability to filter metadata that should not be propagated and to leave untouched destination data that should not be updated. Note that this tool is currently on dev2dev, and will be supported in the next release of the WebLogic Platform.

WebLogic Integration TPM data

Trading Partner Management (TPM) data includes trading partner profiles, certificates from keystores, service definitions, and service profiles. The Bulk Loader is a command-line tool that you can use to import, export, and delete TPM data. The Bulk Loader imports an XML representation of TPM data, and it exports an XML file.

bulkloader [-verbose] [-config <blconfig.xml>] [-wlibc]

 -import <data.xml>

 -export <data.xml> [-nokeyinfo] [-select <selector.xml>]

BEA Liquid Data for WebLogic server settings

BEA Liquid Data for WebLogic server settings include Data Sources, Custom Functions, and Stored Queries. The settings are stored in repository files under the <ldrepository> folder. The following Ant script depicts how to invoke the Liquid Data tool to import server settings from the Ldconfig.xml file. The same class also supports exporting of the server settings.

<java classname="com.bea.ldi.util.CfgImpExp" fork="true">

 <classpath>

  <pathelement location="<WL_HOME>/server/lib/weblogic.jar"/>

  <pathelement location="<REPOSITORY_DIR>/import-export-tools/CfgImpExp.jar"/>

  <pathelement location="<WL_HOME>/liquiddata/server/lib/wlldi.jar"/>

 <pathelement location="<WL_HOME>/liquiddata/server/lib/castor-0.9.3.9.jar"/>

 <pathelement location="<WL_HOME>/liquiddata/server/lib/xercesImpl.jar"/>

 <pathelement location="<WL_HOME>/liquiddata/server/lib/APP-INF/lib/LDS.jar"/>

 </classpath>

 <arg line="<ADMIN_ADDR> <ADMIN_PORT> <ADMIN_USERNAME> <ADMIN_PASSWORD> 

 import <DOMAIN_HOME>/ldrepository/import_export/LDconfig.xml"/>

</java>

Application-specific tables

In a production-mode domain, WebLogic Server will not attempt to automatically provision the dependent resources when you deploy an application. For example, if your application contains conversational web services or Entity Beans, you need to load the conversation state table and Entity Bean tables before you deploy your application. Since you understand what needs to be provisioned, it can be easily automated through scripts. For more information on loading conversation state table and Entity Bean tables, refer to the previous article.

The need for automating production data provisioning is evidenced by the variety of production data in a typical platform environment. While some of them can be provisioned through WLST Online/Offline scripts, others can be exported or imported through specific tools provided by WebLogic Platform (for example, Portal Propagation utility and WLES Import/Export). In some rare cases, you might need to use database-level tools to export or import critical information stored in external database instances.

Differential Provisioning

As the production environment evolves, there may be a need to apply further customization to the existing environment. For example, the administrator may need to change some security provider in the realm, or update existing cache policies. This is sometimes referred to as differential provisioning. Most of the differential provisioning actions are carried out through WebLogic Console and MBean calls. You can also use the template-based approach or the WLST-based approach to support various differential provisioning needs.

For example, you can use WLST Online to configure an additional JMS queue as a distributed queue, and set up the corresponding physical queue members across the cluster. One code sample in the wlst CodeShare project demonstrates how to add Application AsyncRequest Queues as Distributed Queues to a Cluster. Another code sample illustrates how to configure embedded LDAP or external LDAP through WLST Online.

While WebLogic Console and WLST Online scripts support differential provisioning to live servers, WLST Offline along with extension templates can be used to provision additional applications and services, such as JDBC or JMS components, and startup/shutdown classes. To apply extension templates, you need to shut down servers. The following WLST Offline script demonstrates a differential provisioning scenario where a WebLogic Workshop domain is first created, and the WebLogic Integration extension template is applied to the WebLogic Workshop domain using the addTemplate() and updateDomain() operations. As a result, you have a domain that supports both WebLogic Workshop and WebLogic Integration functionality.

readTemplate('<WL_HOME>/common/templates/domains/wlw.jar')

cd('/')

cd('Security/mydomain')

cd('User/weblogic')

cmo.setPassword('weblogic')

setOption('OverwriteDomain', 'true')

writeDomain('<BEA_HOME>/user_projects/domains/wlw-wli')

closeTemplate()

readDomain('<BEA_HOME>/user_projects/domains/wlw-wli')

setOption('ReplaceDuplicates','false')

addTemplate('<WL_HOME>/common/templates/applications/wli.jar')

updateDomain()

closeDomain()

Conclusion

Automating WebLogic Platform application provisioning through multiple stages requires a thorough understanding of the specific requirements at each stage and employing the right tools and utilities to implement the automation. In this article, we focused on the template-based approach and the WLST-based approach, and illustrated how to use these approaches effectively to automate some common provisioning scenarios.

Acknowledgements

I would like to thank Michael Meiner, Michael Zanchelli, Venkat Padmanabhan, and Juan Andrade for their review and comments.

References

Chengjiang (Andy) Lin is a senior software engineer at BEA Platform Engineering Team. Over the last 4 years at BEA, Andy has made contributions in areas including Platform Integration, Web Service Interoperability, WebLogic Clustering and Domain Provisioning Tools.