Deploy WebLogic

The Jenkins project announced an unresolved security vulnerability affecting the current version of this plugin (why?):

This plugin deploys any artifacts built on Jenkins to a weblogic target (managed server, cluster ...) as an application or a library component.

Pre-requisites

This plugin works with at least 1.485 jenkins version.
This plugin only deploys ear, war, jar artifacts.

Configuration

System Configuration

Before use it, the plugin has to be configured. It consists of loading the weblogic target configuration, choosing the default JDK to run a deployment task and adding the weblogic library path :

  • for WLS 8.X /pathtojar/weblogic.jar
  • for WLS 10.3 /pathtojar/wlfullclient.jar
  • for WLS 12.1 /pathtojar/wlthint3client.jar.

For building the wlfullclient.jar look at here: http://docs.oracle.com/cd/E12840_01/wls/docs103/client/jarbuilder.html.

Further information at https://docs.oracle.com/middleware/1213/wls/SACLT/basics.htm#SACLT124

Workaround for Weblogic 12.2

For an unknown reason, deployment fails with librairies generated from a weblogic 12.2 product. You can generate and use a wlfullclient-10.3.6.jarwith that I can deploy without any problem onto our WebLogic Server Version: 12.2.1.1.0.

  • Jdk : the jdk used to run a deployment task.

  • Additional classpath : weblogic.jar file path loaded for deployment. If no value is set but the WL_HOME environment variable is found, the plugin will try to load  %WL_HOME%/server/lib/weblogic.jar.
    Depending on the weblogic version the weblogic.jar should be replaced by :

     

 

    • for WLS 10.3 /path/to/jar/wlfullclient.jar

       

    • for WLS 12.1 /path/to/jar/wlthint3client.jar.

Useful Information

If you use authentication mode, you should replace in WLS 12 wlfullclient.jar by wlthint3client.jar. If you have to add many dependencies you can append them like that /path/to/wulfullclient.jar:/path/to/wlthint3client.jar. The separator ':' is platform dependent.

see https://docs.oracle.com/middleware/1213/wls/SACLT/basics.htm#SACLT125

 

 

Oracle Information

"The WebLogic full client, wlfullclient.jar, is deprecated as of WebLogic Server 12.1.3 and may be removed in a future release. Oracle recommends using the WebLogic Thin T3 client or other appropriate client depending on your environment. For more information on WebLogic client types, see WebLogic Server Client Types and Features."

  • Java Options to use : the java options used by the java process when invoking the weblogic library. By default it will be -Xms256M -Xmx256M.

  • Excluding artifact name list : the built artifacts name pattern excluded from post build deployment action.

  • Disable : If checked, the plugin execution is disabled.

  • Configuration File : xml file path containing deployments targets. It has to be [http://host:port/plugin/weblogic-deployer-plugin/defaultConfig/plugin-configuration.xsd\] schema compliant. No validation currently performed. The file can be added through a local path (/usr/users/.../plugin-configuration.xml) or a remote URL (http://xxxxxxxxx/plugin-configuration.xml);

    configuration.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <config xmlns="http://org.jenkinsci.plugins/WeblogicDeploymentPlugin"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://org.jenkinsci.plugins/WeblogicDeploymentPlugin plugin-configuration.xsd"> 
    <weblogic-targets>
        <weblogic-target>
            <name>my_managed_server1</name>
            <host>_weblogic.admin.server.host_</host>
            <port>_weblogic.admin.server.port_</port>
            <login>_weblogic.admin.server.login_</login>
            <password>_weblogic.admin.server.password_</password>
            <authMode>BY_KEY</authMode>
            <userconfigfile>P:\Documents\perso\dev\wls-deploy-plugin\wls_userConfig.properties</userconfigfile>
            <userkeyfile>P:\Documents\perso\dev\wls-deploy-plugin\wls_userConfig.key</userkeyfile>
        </weblogic-target>
        <weblogic-target>
            <name>my_managed_server2</name>
            <host>_weblogic.admin2.server.host_</host>
            <port>_weblogic.admin2.server.port_</port>
            <login>_weblogic.admin2.server.login_</login>
            <password>_weblogic.admin2.server.password_</password>
            <authMode>BY_LOGIN</authMode>
        </weblogic-target>
        <weblogic-target>
            <name>my_managed_server3</name>
            <host>_weblogic.admin.server.host_</host>
            <port>_weblogic.admin.server.port_</port>
            <login>_weblogic.admin.server.login_</login>
            <password>_weblogic.admin.server.password_</password>
            <!-- used to transfer by FTP the component flagged as library to the WL machine -->
            <ftpHost>_weblogic.remote.host_</ftpHost>
            <ftpUser>_weblogic.remote.user_</ftpUser>
            <ftpPassowrd>_weblogic.remote.password_</ftpPassowrd>
            <remoteDir>/remote/path/used/to/transfer/libraries</remoteDir>
        </weblogic-target>
    </weblogic-targets>
    </config>
    

Library Deployment Tip

The ftp parameters are used to deploy libraries. When you checked your artifact deployment as a library deployment, the plugin connects to the ftpHost and transfers the artifact into the remoteDir directory.
Basically, the ftpHost value should be the same as the host value.

Authentication mode

There are 2 kinds of authentication :

  • BY_KEY : uses a keystore file and a config file
  • BY_LOGIN : uses a login/password (this is the default authentication mode).

Since 2.3, the plugin also supports authentication by keystore. To use it, set authMode with BY_KEY value then set userconfigfile/userkeyfile elements. If you forget to specify authMode with BY_KEY value, the plugin uses the default authentication mode BY_LOGIN.

Job Configuration

If the plugin is not configured

If no configuration has been set, the plugin will display an error message

If the plugin is already configured

If the plugin is already configured, jenkins will display the job plugin configuration form.

  • Deployment task list : The list of deployments to run. For each task, some of parameters has to be set :
    • Task name (optional) : The name of the task which will be used to identify it.
    • environment : the targeted weblogic environment. Can be customized.
    • name : the name used by weblogic to display component.
    • Base directory where the resource can be found. If this field is left blank, the plugin will lookup under workspace directory.
    • Built resource to deploy : a regular expression to filter resource which will be deployed.
    • targets: the weblogic target (can be a managed server instance, a cluster either the AdminServer). By default the plugin will use the AdminServer as the target. Many targets can be defined and will be separated by un comma symbol (e.g AdminServer, ManagedServer1, Cluster2). Can be customized.
    • weblogic libraries : If checked, the generated artifact will be deployed as a library component.
    • advanced configuration : See the chapter below Job Advanced configuration.
  • Build failed when deployment failed : If checked, The current build will be flagged as a failed one if the deployment task failed.
  • Force deployment tasks stop on first failure : Useful if you have any task configured and you want to stop the next deployments tasks where an error occurs.
  • Deployment policy : Configure which cause(s) will trigger the deployment action. If 'None specified' is selected, the deployment occurs each time the job builds. If another ones are selected, the deployement action only occurs when the build was triggered by a chosen cause.
  • Deploying only when sources changes : If checked, the deployment action only occurs when the build trigger by a parametrized cause AND the SCM step detects any changes.
  • Projects deployment Dependencies : (experimental) specifies a dependency with others job deploying some artifacts.
Customization of parameters

Some of parameters can also be tokenized with environment variables or even build parameters. Here are these parameters :

    • environment: Instead of setting a fixed value into the configuration file (e.g localhost:7000) you can set a variable like ${WL_HOST}:${WL_PORT}
    • targets: Instead of setting a fixed value (e.g AdminServer) you can set a variable like ${ENV_TARGET} or $TARGET.
    • Base directory where the resource can be found : you can set a variable like ${WORKSPACE}.
    • name: The name parameter can be tokenized (e.g my-war-${MY_VERSION})

Use the build parameter plugin or add some environment variable to set these values

Job Advanced configuration

It's possible to set advanced options like stage mode and command line. It helps user with special needs to override the default behaviour of the plugin.

  • Stage mode : stage, nostage or external stage
  • protocol : t3, t3s, http or https
  • Command line : The command which will be run by the deployer instead of the default ones (undeploy/deploy)
Stage mode

Stage mode define how the artificat will be deployed. By default the plugin use the stage mode 'stage'. Please refer to the weblogic documentation for further information.

Override deployment execution

For advanced users, it can be useful to define the commands that the deployer has to run instead of the default ones, To enable this feature, the user will set different command lines into the 'Command line' field of Job advanced configuration.

These commands has to be ended by the ';' separator. The following plugin token can be added to the command line :

  • {wl.deployment_name} : the 'Name' parameter value
  • {wl.source} :  the resource to deploy (figured out by the plugin)
  • {wl.targets} : the 'Targets' parameter value
  • {wl.host} : the host part of the 'Environment' parameter
  • {wl.port} : the port part of the 'Environment' parameter
  • {wl.deploymentPlan} : the path of the deployment plan of the 'Environment' parameter
  • {wl.login} : the login to authenticate to the server (provided by the configuration file)
  • {wl.password} : the password to authenticate to the server (provided by the configuration file)
  • {wl.user_configfile} : the Deployer configuration file (defined in the configuration file)
  • {wl.user_keyfile} : the private key to authenticate (provided by the configuration file)

Note : only the arguments and parameters can be specified. The java executable used to run the command will be figure out by the plugin with the same algorithm than a default execution.

For instance : the user who prefers run deployment with 'distribute' instead of deploy could be set the following command lines:

command line parameter

-adminurl http://{wl.host}:{wl.port} -user {wl.login} -password {wl.password} -debug -remote -verbose -name {wl.deployment_name} -source {wl.source} -targets {wl.targets} -cancel;
-adminurl http://{wl.host}:{wl.port} -user {wl.login} -password {wl.password} -name {wl.deployment_name} -source {wl.source} -targets {wl.targets} -distribute

Be Careful

Sometimes source path contains special chars like $.To ensure that the plugin well handle the path you can surround the token {wl.source} with quotes like this :

command line parameter

-adminurl http://{wl.host}:{wl.port} -user {wl.login} -password {wl.password} -debug -remote -verbose -name {wl.deployment_name} -source "{wl.source}" -targets {wl.targets} -cancel;

NB : Environment variables and build parameters can also be used.

User Guide

Build status

The build status will be modified according the following rules :

  • the status is set to SUCCESS when :
    • the deployment task is successfully achieved
    • the checkbox "Mark build unstable if deployment was not attempted" is not checked whatever the result of pre-requisite step.
  • If the checkbox "Mark build unstable if deployment was not attempted" is checked, the status is set to UNSTABLE when :
    • at least one of the verification of the deployment task failed (PLUGIN_DISABLED, OTHER_TRIGGER_CAUSE, NO_CHANGES, UNSATISFIED_DEPENDENCIES, PREVIOUS_STATUS_BUILD_FAILED).
    • the deployment task failed and the Build failed when deployment failed parameter is not checked.
  • status is set to FAILED when the deployment task failed and the Build failed when deployment failed parameter is checked.

Check a build deployment status

On the build dashboard a new icon will appear. It displays the deployment status

Check the last successful deployment on main job dashboard

When you click on your job, a dashboard show a new icon with the date of the last successful deployment. If no deployment occurred or always failed. The date will be replaced by 'N/A' label.

View deployment Logs

You can view the deployment logs of each task. Simply click on the 'Deployments Statuses' link or 'Weblogic deployments' link. They will appear one by one in the deployment page.

Disabling deployment task at runtime

A deployment task can be skipped during a job build by setting an env variable or a build parameter following this naming rule (DEPLOY_<task_name>_SKIP) to true.

For instance, if your task names 'task1' you have the possibility to skip its execution by setting a variable named DEPLOY_TASK1_SKIP to true (It could be a boolean build parameter).

Master/slave architecture support

The latest version of the plugin (4.0) supports master/slave architecture. That is to say, the plugin automatically copy weblogic libraries and any kind of configuration to the remote node. Be sure that the right JDK used by the plugin is correctly installed and declared in the node configuration. 

 

Note master/slave architecture

The plugin doesn't copy userkeyfile nor userconfigfile to the remote node. This enhancement will be done in the next version.

 

 

Release Notes

Version 4.1 (September 03, 2017)

JENKINS-45044 - Getting issue details... STATUS

Version 4.0 (August 21, 2017)

Master-Slave architecture support ( JENKINS-44599 - Getting issue details... STATUS ,  JENKINS-36215 - Getting issue details... STATUS )

Note : the copy of userkeyfile and userconfigfile on the remote node is not currently supported.

Merge pull request #8 from mustafau/simplify-global-configuration

JENKINS-45097 - Getting issue details... STATUS

JENKINS-36524 - Getting issue details... STATUS

JENKINS-37077 - Getting issue details... STATUS

Version 3.7 (June 21, 2017)

JENKINS-42802 - Getting issue details... STATUS

Upgrade to 1.580.1 jenkins version

Minor enhancements (simply invoke join instead of start + join, using absolute path of jdk home)

Version 3.6 (Oct 25, 2016)

JENKINS-39029 Fixed NPE for job configured with the plugin verson older than 3.5
JENKINS-38218 Support multiple files validation for extraClasspath field.

Version 3.5 (Sep 04, 2016)

JENKINS-32392 Added the ability to choose the protocol to use during the deployment.
Refactoring deployment policy. LegacyCodeCause and UserCause no more supported.(thanks to mustafa ulu)

Version 3.4 (May 26, 2016)

JENKINS-19962 Added the ability to declare a job successfull when pre-requisite step failed
JENKINS-35161 variable can be used for the Deployment name value
UserCause is now flagged deprecated in the triggers list
Added TimerTrigger to the list of triggers

Version 3.3 (August 31, 2015)

JENKINS-26992 baseDirectory not well replaced
Removed unused org.codehaus.plexus dependency

Version 3.1 (March 31, 2015)

Removed org.codehaus.plexus.FileUtils dependency

Version 3.0 (March 28, 2015)

JENKINS-26992 Supported baseDirectory variable expansion
JENKINS-26366 Implemented Promoted Builds plugin support
JENKINS-23700 By default the plugin searches under workspace directory

Be Careful

This version is not backward compatible. If you used previous version with maven project don't forget to update the maven jobs configuration (fill up base directory which is no more computed).

Version 2.13 (February 16, 2015)

JENKINS-20351 Implemented the recursive search when no base directory is set in freestyle job configuration.
Fixed JENKINS-26901 Not possible to run freestyle job with non-set baseDirectory.

Version 2.12 (December 17, 2014)

JENKINS-24789 Added the possibility to skip a task deployment during a build by setting a build parameter or an env variable.

Version 2.11 (December 16, 2014)

Fixed regression due to an unexpected commit (sad)

Version 2.10 (December 6, 2014)

Fixing bug JENKINS-23701 : Added better control on invalid directory parameter set.
French translation missing
Fixing wrong javadoc
Fixing wrong icon URL.

Version 2.9.1 (December 20, 2013)

Fixing bug JENKINS-20970 : deployment failed due to an unexpected stream closed exception.

Version 2.9 (November 30, 2013)

Handled exception when configuration file uploaded is incorrect.
Added error log on jenkins project selector bean.

Version 2.8 (October 06, 2013)

Fixing bug JENKINS-16007

Version 2.7 (October 04, 2013)

Implementing JENKINS-18685 Added support for customization of deployment targets/environment through build parameters.

Version 2.6 (September 16, 2013)

Implementing JENKINS-19237 Added deployment plan support
Evolution JENKINS-19016 Modified behavior when the step of pre-requisite check failed.

Version 2.5 (July 27, 2013)

Implementing JENKINS-18882 Replaced weblogic icon
Fixing bug JENKINS-18940 token {wl.source} never replaced in command line

Version 2.4 (July 24, 2013)

Implementing JENKINS-17300 and JENKINS-18812 : Added new feature which allow the advanced user to define his own command to run
Fixing bug JENKINS-18881 : NPE when the user viewing deployment result of a skipped execution
Fixing bug JENKINS-18883 : cron value doesn't appear in 'Deploy periodically' field

Version 2.3 (June 26, 2013)

Implementing JENKINS-18467 : stage mode attribute mishandled in job advanced configuration.
Implementing JENKINS-17879 : Supports weblogic authentication by keystore.

Version 2.2 (May 04, 2013)

Implementing JENKINS-17300 : Supports stage mode choice in job configuration.

Version 2.1 (May 03, 2013)

Implementing JENKINS-17301 : Supports jdk configuration per job.

Version 2.0 (Mar 04, 2013)

Implementing JENKINS-16808 : Supports multi-deployment feature.
Implementing JENKINS-16699 : Searched resource pattern or name is traced in the job log

Be Careful

This version is not backward compatible.

Version 1.4 (Feb 11, 2013)

Implementing JENKINS-15696 : Supports freestyle project.

Version 1.3 (Aug 13, 2012)

Implementing JENKINS-14763 : English translation. The English language is the default plugin language.

Version 1.2 (Aug 2, 2012)

Implementing JENKINS-14646 : The old java class or resources prefixed by HudsonXXXX has been refactored to XXXX.
Implementing JENKINS-14626 : As of now, it's possible to filter the artifact name to deploy by regex defined in the job configuration. (Useful for maven multi-module project which generate many artifacts).

Version 1.1 (May 5, 2012)

Forked from Hudson version.

Added JDK selection on global configuration.

Removed task abortion if no compatibility detected between the JDK and the weblogic.Deployer API (As of now, It displays a warning).

Fixed translation and spelling errors.

Added WebLogic Server 10.3 support.