How to use a deployment plan ?

So far, I've been working with several clients who have a strong need to override some values, according to the target environment when they are deploying their archive.

BEA/Oracle offers such a mechanism from WebLogic Server 9, which is called "Deployment Plan".

It is quite well exposed in the official documentation : http://edocs.bea.com/wls/docs91/deployment/plan.html

You also may take a look at Understanding Deployment Plan Contents

 

How does it look like and how does it work ?

Here is a sample of a plan.xml :

<?xml version='1.0' encoding='UTF-8'?> 
<deployment-plan 
    xmlns=http://www.bea.com/ns/weblogic/deployment-plan
    xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
    xsi:schemaLocation="http://www.bea.com/ns/weblogic/deployment-plan
http://www.bea.com/ns/weblogic/deployment-plan/1.0/deployment-plan.xsd"> 
    <application-name>sample</application-name>
    <variable-definition>
        <variable>
            <name>MyNewSessionTimeout</name>
            <value>600</value>
        </variable>
    </variable-definition> 
    <module-override>
        <module-name>DatasourceCaller.war</module-name>
        <module-type>war</module-type>  
        <module-descriptor external="true"> 
            <root-element>weblogic-web-app</root-element> 
            <uri>WEB-INF/weblogic.xml</uri> 
            <variable-assignment>
                <name>MyNewSessionTimeout</name>
                <xpath>/weblogic-web-app/session-descriptor/timeout-secs</xpath>
            </variable-assignment>
        </module-descriptor> 
        <module-descriptor external="false">
            <root-element>web-app</root-element>
            <uri>WEB-INF/web.xml</uri> 
        </module-descriptor>  
        <module-descriptor external="true"> 
            <root-element>wldf-resource</root-element> 
            <uri>META-INF/weblogic-diagnostics.xml</uri> 
        </module-descriptor>  
    </module-override> 
    <config-root>D:\BEA_ROOT\applications\sample\plan</config-root> 
</deployment-plan>

The mechanism works by first defining a variable with a value (blue section) and then assigning it to an application (purple section).

As you can see XPath is used to qualify the path of the attribute to update. For instance, here it's "/weblogic-web-app/session-descriptor/timeout-secs".

You will notice that the XPath indicated is simply the path to that attribute in the following weblogic.xml deployment descriptor.

<?xml version="1.0" encoding="UTF-8"?> 
    <weblogic-web-app 
        xmlns=http://www.bea.com/ns/weblogic/90
        xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
        xsi:schemaLocation="http://www.bea.com/ns/weblogic/90 http://www.bea.com/ns/weblogic/920/weblogic-web-app.xsd">
        <session-descriptor>
            <timeout-secs>600</timeout-secs>
        </session-descriptor> 
    </weblogic-web-app>

How do I know if there's already a plan linked to my application ?

Well, that part is easy to answer. Either you have :

Or :

See the difference ? :)

 

How do I create a deployment plan ?

Console

When you go on the console, on your deployment, you will see a tab called "Configuration > General".

Here you will be able to see some tuning values defined for your application.

If you did not configure your deployment descriptor accordingly, some default values will be displayed like :

 

Modifying these values will lead to the creation of a deployment plan.

Save you plan where you want to and you're done.

 

weblogic.PlanGenerator

BEA offers a tool dedicated to plan creation. As every tool, you first have to set your classpath first to be able to use it.

(This can be done by executing the script setWLSEnv). Here is an example of how it works. 

java weblogic.PlanGenerator

-all // option exporting all the editable options

-plan samplePlan.xml // the name of the plan to be generated

myApp

Full Ex : java weblogic.PlanGenerator -all -plan mySamplePlan.xml D:\BEA_ROOT\user_projects\applications\sample\sample.war 

 

Then you should normally have the following message as a result : 

Generating plan for application D:\BEA_ROOT\user_projects\applications\sample\sample.war

Export option is: all Exporting properties...

Saving plan to C:\Documents and Settings\mbutton\samplePlan.xml...

<14 avr. 2008 15 h 07 CEST> <Info> <J2EE Deployment SPI> <BEA-260086>

<The descriptor information at D:\Temp\[...]\weblogic.xml was saved to configuration area.>

<14 avr. 2008 15 h 07 CEST> <Info> <J2EE Deployment SPI> <BEA-260072>

<Saved configuration for application, sample.war>

 

To better understand the different categories of options available, read the documentation : Understanding Deployment Property Classifications

Personnaly, I encountered some problems using it.

Actually, some attributes are considered as non-editable when generating the plan, but if you manually override them, it works ...

Then, I would advise you to use this tool for a first shot and then modify it with your values.

(So far, all the values I changed through a plan were successfully updated).

 

Hand :)

It's a xml file, then you may write it from the beginning. I wouldn't advise you to do so because the chances of getting an error are much higher.

But if you're really willing to do it yourself, take a look at http://www.bea.com/ns/weblogic/90/weblogic-deployment-plan.xsd, it should help.

 

How do I link it to my deployment ?

Console

Unfortunately, through the console, when you deploy a new application, you cannot reference the deployment plan directly.

You will have to install your application and then update it. First, check the application then "Update" button :

Then change the plan path to reflect the actual location of your deployment plan and update the whole stuff.

 

Or there is another way to take the plan into account, but as I said earlier it's not visible from the console.

You'll have to respect a certain directory structure to have your deployment plan automatically bound to your application.

I will advise you to follow the best practices described by BEA : Steps for Creating an Application Installation Directory.

To sum up, your directory should look like :

SampleApplication
	----> V1
	  ----> app
	    ----> SampleApplication.war
	   ----> plan
	    ----> plan.xml
	----> V2
	  ----> app
	    ----> SampleApplication.war
	  ----> plan
	    ----> plan.xml
 

And then when you will deploy the open directory V1 or V2, the sample application will be deployed as well as the associated deployment plan.

 

weblogic.Deployer

You may update your application and specify the plan to use : 

java weblogic.Deployer -username weblogic -password weblogic -adminurl t3://localhost:7001 -update-name SampleApplicationBis -plan SamplePlan.xml 

(If you're wondering why the action is 'update' and not 'redeploy', read Understanding Redeployment Behavior for Deployment Configuration Changes)

The result will be displayed like that : 

weblogic.Deployer invoked with options: -username weblogic -adminurl t3://localhost:7001 -update -name SampleApplicationBis -plan SamplePlan.xml
<21 aout 2008 08 h 55 CEST> <Info> <J2EE Deployment SPI> <BEA-260121> <Initiating update operation for application,

SampleApplicationBis [archive: null], to configured targets.>
Task 3 initiated: [Deployer:149026]update application SampleApplicationBis on AdminServer.
Task 3 completed: [Deployer:149026]update application SampleApplicationBis on AdminServer.
Target state: update completed on Server AdminServer 

Or you may install your application for the very first time : 

java weblogic.Deployer -username weblogic -password weblogic -adminurl t3://localhost:7001 -deploy -name SampleApplicationBis -plan SamplePlan.xml  

You will have a similar result than when updating (see above). 

WLST

It is of course possible to use WLST to deploy the application and the deployment plan or simply to update an application.

 

How can I check that my values have been taken into account ?

Console

Through the console, simply go to the "Configuration > General" tab of your deployment and check the new values

(if they belong to this section, else you will have to check thanks to WLST, described later in this section).

 

WLST

The console is fine, but you can't see all. Nor can you with WLST :) But it's much more complete.

For that, just connect to the server on which the application is deployed (if you're not in development mode, it is normally NOT your administration server).

For instance, let's assume we've got a admin server listening on port 7001 and a managed server listening on 7011.

You app is deployed on the managed server, then you will type : 

connect ('weblogic', 'weblogic', 't3://localhost:7011') // Using the same credentials than the admin

serverRuntime() // Allows you to switch to the runtime tree

cd ('ApplicationRuntimes') // You always will have to go in that directory

cd ('ApplicationSampleBis') // This is the name of our application (you may have to go in a directory representing the EAR prior to reach the WAR)

cd('ComponentRuntimes') // You always will have to go in that directory

cd ('AdminServer_/sample') // Change to the directory whose name is composed of your server name and the context root of you app (type ls() if you want to be sure)

ls()

 

And the result will show you the runtime values. For instance, before :

 

And after :

 

Troubleshooting

"My values are not updated : what am I missing ?" Well, I won't pretend I'm going to solve your problem, but let's try :)

First, check that your plan is defined in the console as stated in the "How do I know if there's already a plan linked to my application" section.

If it's the case, check that the name you defined in your plan, for the module is correct. WLST will give you the component name (in serverRuntime tree) :

And it must be the same in your plan : 

<module-override>
<module-name>Extract</module-name>
<module-type>war</module-type> 

And last but not least, the values you want to override MUST have been defined in your deployment descriptor. It's an override, not a definition. 

Links

If you're French, I would advise you to go the excellent post of my colleague Benoit Moussaud : http://blog.xebia.fr/2008/04/17/les-plans-de-deploiement-weblogic/

Mots clés Technorati : WebLogic,Deployment Plan,weblogic.Deployer,weblogic.PlanGenerator