Preface

This document describes the functionality provided by the IBM WebSphere Application Server (WAS) plugin.

Refer to Deployit Reference Manual for background information on Deployit and deployment concepts.

Overview

The WAS plugin is a Deployit plugin that adds capability for managing deployments and resources on an existing WebSphere application server. It offers out of the box support for deploying/undeploying application artifacts, datasources, JMS resources and other Java EE resources and WAS configurations. See the Features section below for details. It can easily be extended to support more deployment options or management of new artifacts/resources on WAS.

Features

• Deploys and undeploys Java EE application artifacts:
  • Enterprise applications (EAR)
  • Web applications (WAR)
  • Enterprise JavaBeans (EJB JAR)
  • Creates and removes Java EE resources:
    • Oracle datasources
    • DB2 datasources (type 2 and type 4)
    • V5 default JMS resources: queues, topics and connection factories.
    • WebSphere MQ JMS resources: queues, topics and connection factories.
    • SIB JMS resources: queues, topics, connection factories and destinations.
• Creates and removes WAS configuration elements:
  • Shared libraries
  • Virtual hosts
• Discovers WAS topologies: cells, nodes, clusters, server, web servers.

Requirements

• Deployit requirements
  • Deployit: version 3.6+
  • IBM WebSphere Application Server Standard and Network Deployment: 6.1, 7.0 and 8.0 (Unix and Windows)
  • Other Deployit Plugins: None

Usage in Deployment Packages

The plugin works with the standard deployment package of DAR format. Please see the Packaging Manual for more details about the DAR format and the ways to compose one.

The following is a sample MANIFEST.MF file that can be used to create a WebSphere specific deployment package. It contain declarations for an Ear, an Oracle datasource spec and a couple of JMS resources.

Manifest-Version: 1.0
Deployit-Package-Format-Version: 1.3
CI-Application: PetClinic-ear
CI-Version: 1.0-was

Name: PetClinic-1.0.ear
CI-Name: PetClinic
CI-Type: jee.Ear

Name: sampleOracleDatasource
CI-Type: was.OracleDatasourceSpec
CI-jndiName: jdbc/sampleOracleDatasource
CI-jdbcProvider: Oracle JDBC Driver
CI-datasourceHelperClassname: com.ibm.websphere.rsadapter.Oracle10gDataStoreHelper
CI-username: {{DATABASE_USERNAME}}
CI-password: {{DATABASE_PASSWORD}}

Name: sampleSibQueueDestination
CI-Type: was.SibQueueDestinationSpec
CI-busName: sampleSIBus

Name: sampleSibQueue
CI-Type: was.SibQueueSpec
CI-queueName: sampleSibQueueDestination
CI-busName: sampleSIBus
CI-description: sample sib queue

Using the deployables and deployeds

The following table shows the possible containers a deployable can be targeted to and the deployed that will be created as a result of that.

Deployed actions table

The following table shows the actions taken when creating, modifying or destroying a deployed.

Discovering WAS middleware

Deployit can scan your environment for as far as possible and create Configuration Items in its repository based on the configurations it encounters during the scan. This process is knows as discovery.

The CIs discovered during discovery will help you in setting up your infrastructure in an easy way. However, they need not be complete: some CIs contain properties that can not be automatically discovered, like passwords. These specific kind of properties will still need to be entered manually.

Because discovery is part of the Deployit plugin suite, the exact discovery functionality available varies depending on the middleware platforms present in your environment.

The following steps comprehend discovery:

1. Create a CI representing the starting point for discovery (often a Host CI).
2. Start discovery passing this CI.
3. Store the discoverd CIs in the repository.
4. Complete the discovered CIs manually by providing missing needed properties.
5. Add the discovered CIs to an environment.

Note however that the last step of discovery is optional. The discovered CIs will be stored under the Infrastructure root node in the repository and may be added to an environment at some later time.

Create a Configuration Item starting point

The first step taken in discovery is to create a starting point to kick off the process from. This starting point consists of a Configuration Item specifying at least the host that discovery should start at. Depending on the middleware you are trying to discover, additional parameters may be needed.

Following is an example of how to start discovery for a WebSphere Application Server (WAS). First a CI is created for the host itself and next a Configuration Item is created for the deployment manager running on that ost. The deployment manager CI will be the starting point for discovery.

    # Create a CI with the required discovery parameters filled in
    wasHost = factory.configurationItem('Infrastructure/rs94asob.k94.corp.com', 'overthere.SshHost', {
            'address':'was-61',
            'username':'root',
            'password':'rootpwd',
            'os':'UNIX',
            'accessMethod':'SSH_SFTP'
        })

    repository.create(wasHost)

    # Now create a WAS deployment manager
    dmManager = factory.configurationItem(wasHost.id + '/wasDM', 'was.DeploymentManager', {
            'host':'Infrastructure/rs94asob.k94.corp.com',
            'version':'WAS_61',
            'wasHome':'/opt/ws/6.1/profiles/dmgr',
            'username':'wsadmin',
            'password':'wsadmin'})

Note 1: Right now possible values for version are: WAS_61, WAS_70, WAS_80.

Note 2: Last segment of Configuration Item id ("wasDM" in this example) should match your WebSphere cell name.

Start discovery passing a Configuration Item

After the CI starting point has been created, it can be used to perform discovery. The Deployit CLI discovery functionality is synchronous, which means that the CLI will wait until the discovery process finishes.

The process of discovery works exactly like a regular task:

deployit> taskId = deployit.createDiscoveryTask(dmManager)
deployit> deployit.startTaskAndWait(taskId)
deployit> discoveredCIs = deployit.retrieveDiscoveryResults(taskId)

Note there are no single- or double quotes around dmManager, because it's an object and not a string. The result of this command will be an object containing a list of discovered CIs.

Store the CIs in the repository

Deployit returns a list of discovered middleware CIs. Note that these are not yet persisted. To store them in the repository, use the following code:

    repository.create(discoveredCIs)

Complete discovered middleware CIs

The easiest way to find out which of the discovered CIs require additional information is by printing them. Any CIs that contain passwords (displayed as '********') will need to be completed. To print the stored CIs, the following code can be used:

    for ci in discoveredCIs: deployit.print(repository.read(ci.id));

Note: the created CIs can also be edited in the GUI using the Repository Browser.

Adding CIs to Environments

Middleware that is used as a deployment target must be grouped together in an environment. Environments are CIs and like all CIs, they can be created from the CLI. The following command can be used for this:

    env = factory.configurationItem('Environments/DiscoveredEnv', 'udm.Environment') 

Add the discovered CIs to the environment:

    env.values['members'] = [ci.id for ci in discoveredCIs]

Note that not all of the discovered CIs should necessarily be stored in an environment. For example, in the case of WAS, some nested CIs may be discovered of which only the top-level one must and can be stored.

Store the new environment:

    repository.create(env)

The newly created environment can now be used as a deployment target.

Note: the user needs specific permission to store CIs in the database. See the Deployit System Administration Manual.

Extending the WAS plugin

The WAS plugin is designed to be extended through Deployit's Plugin API type system and through the use of custom, user defined WAS Python scripts.

The WAS plugin associates Create, Modify, Destroy and Inspect operations received from Deployit with WAS Python scripts that need to be executed for the specific operation to be performed. The operation specific script is given a Python object representation of the Deployed that triggered the operation. The script is then executed using wsadmin.

There also exists an advanced method to extend the WAS plugin, but the implementation of this form of extension needs to be written in the Java programming language and consists of writing so-called Deployed contributors, PlanPreProcessors and Contributors.

Please refer to the Customization Manual for a detailed explanation of the type system and advanced methods of customization of plugins.

Extending using XML and Python scripts

The easiest way of extending the WAS plugin is by using XML and Python scripts. In this way no Java code needs to be written. Extending the behaviour of the plugin is done by simply defining the necessary deployables and deployeds for the specific environment. When Deployit starts up, it reads a file called synthetic.xml from the server class-path, i.e. the ext directory of the server.

This file contains the type definitions of the deployables and the deployeds, i.e. the information about the types and their properties. In addition to that, it defines which Python scripts should be executed for a particular operation, as mentioned above. The scripts have all the information from the Deployed at their disposal to perform their work.

As an example, this is the type definition of a virtual host as it appears in synthetic.xml:

<type type="was.VirtualHost" extends="was.Resource" deployable-type="was.VirtualHostSpec" container-type="was.Cell">
    <generate-deployable type="was.VirtualHostSpec" extends="was.Deployable" />
    <property name="createScript" default="was/virtualhost/create-virtual-host.py" hidden="true" />     
    <property name="destroyScript" default="was/virtualhost/destroy-virtual-host.py" hidden="true" />
    <property name="inspectScript" default="was/virtualhost/inspect-virtual-host.py" hidden="true" />   
    <property name="aliases" kind="set_of_string" description="Virtual host aliases - enter alias as: hostname:port" />
</type>

Looking at this type definition more closely, it indicates that a virtual host, the type of which is was.VirtualHost will be created on its target infrastructure, called container, with a container-type of was.Cell; On WAS a virtual host may be created on a cell and that is exactly what this definition means.

The attribute extends tells the plugin what resource is extended by this definition. In this case it's a simple basic resource so it extends the type was.Resource. Since multiple virtual hosts may be created this way, each with its own set of properties, a specification of what will be deployed is created, a so-called deployable-type, and is itself of type was.VirtualHostSpec.

Within the type definition, there is the possibility of specifying properties of exactly how the virtual host is to be created. The first property is called createScript and specifies the script to be executed by wsadmin for the creation of the virtual host. An extension of this plugin could specify a different creation script. The plugin comes with a default creation script (createScript):

create-virtual-host.py

import re

pattern = re.compile('^[^:]+:\d{,5}')
virtualHostParent = AdminConfig.getid('/Cell:%s/' % (deployed.container.cellName))
attributes = [['name', deployed.name]]
attributes.append(['aliases', [[['hostname', alias.split(':')[0]], ['port', alias.split(':')[1]]] 
                    for alias in deployed.aliases if pattern.match(alias) != None]])
re.purge()

print "Creating virtual host %s on target scope %s with attribute(s) %s" % (deployed.name, virtualHostParent, attributes)
AdminConfig.create('VirtualHost', virtualHostParent, attributes)

This script also shows that aliases are also created for the specified virtual host. Aliases may be specified using the property aliases and it takes a set of strings. An example of this property is:

<property name='aliases' kind='set_of_string' value='www.my-domain.com:80,www.proxy-domain.com:8443'/>

In addition to a creation script, a destruction script (destroyScript) must also be specified:

destroy-virtual-host.py

virtualHostContainmentPath = '/Cell:%s/VirtualHost:%s' % (deployed.container.cellName, deployed.name)
virtualHostId = validateNotEmpty(AdminConfig.getid(virtualHostContainmentPath),
"Cannot find virtual host with id: %s" % (virtualHostContainmentPath))

print "Destroying virtual host %s" % (deployed.name)
AdminConfig.remove(virtualHostId)

Finally, a modification script (modifyScript) may also be specified. If that is not present, the destruction script is invoked to remove the resource with the old settings and then the creation script is invoked to create the resource with the new settings.

Adding a property

The architecture of the WAS plugin enables the tranfer of properties from the deployed - was.VirtualHost in this example - to the accompanying Python scripts defined with the properties createScript and destroyScript. In order for this to be possible, the properties are bound to an object called deployed and can be accessed as deployed.<property-name>. This can be seen in the creation script, where the property aliases is available as deployed.aliases and the name of the virtual host as deployed.name. Using this convention as many properties as needed by the scripts can be bound to the type definition. Care should be taken that the scripts use the same type as specified in the definition, so if a property defines a kind=integer, the script should also treat the value of this property as being of type integer.

An example of adding another property is:

<property name='index-range' kind='integer' value='999' description='maximum index of an array of 1000 items'/>

Fixing a property

In the case where it is necessary that a specific property should always contain a fixed predefined value, the attribute hidden=true should be used on the definition of the property. This way an end-user, who is performing the deployment using the Deployit user interface, won't be able to see this property and therefore not have the possibility of modifying it. Usually this is done for the Python scripts which once written are not allowed to be changed by an end-user.

Using the example of the previous section and wanting to fix the maximum range, the example becomes:

<property name='index-range' kind='integer' value='999' hidden='true' description='maximum index of an array of 1000 items'/>

Inspection

One thing left to be mentioned is the property called inspectScript. When the Domain manager of WAS is known, it is possible for Deployit to discover on its own most of the WAS topology automatically. This specific script is called upon by Deployit when it's trying, in our example, to discover a virtual host on a WAS cell. Following is the default script implementation shipped with the WAS plugin:

inspect-virtual-host.py

print "Inspecting virtual host %s" % (deployed.name)

virtualHostContainmentPath = '/Cell:%s/VirtualHost:%s' % (deployed.container.cellName, deployed.name)
virtualHostId = validateNotEmpty(AdminConfig.getid(virtualHostContainmentPath),
"Cannot find virtual host %s" % (virtualHostContainmentPath))

inspected('name', AdminConfig.showAttribute(virtualHostId, 'name'))
aliases = AdminConfig.getid(virtualHostContainmentPath + '/HostAlias:/').split()
inspected('aliases', [AdminConfig.showAttribute(alias,'hostname') + ':' +
AdminConfig.showAttribute(alias,'port') for alias in aliases if alias != ""])

In the above script, discovered information is handed back to the plugin by use of the inspected method. This method takes two parameters, the first one being the name of the discovered item or property and the second one the actual value. The value should be representable as either a string, or a list of strings. The declaration of this method can be found in the Plugin API in the file base.py.

More information about the process of discovery and how to use it can be found in the Command Line Interface (CLI) manual.

Execution order

A deployment process consists of a series of steps that are executed sequentially. Plugins offer the ability to influence the order of execution of the steps contributed to the deployment process in relation to other contributed steps and operations, not necessarily contributed by the same plugin(s), that are part of the deployment process.

The order of execution allows for the chaining of scripts or operations to create a logical sequence of events. In order to specify the order, properties with the name of createOrder and destroyOrder may be used with an attibute called default to specify the order ordinal. For example, the following synthetic.xml snippet says that creation of the virtual host, default=60, will happen before any step with a higher order, for example default=70, but after any step with a lower order, i.e. lower than default=60.

<type type="was.VirtualHost" extends="was.Resource" deployable-type="was.VirtualHostSpec" container-type="was.Cell">
    <generate-deployable type="was.VirtualHostSpec" extends="was.Deployable" />

    <property name="createScript" default="was/virtualhost/create-virtual-host.py" hidden="true" />
    <property name="createVerb" default="Deploy" hidden="true" />
    <property name="createOrder" kind="integer" default="60" hidden="true" />

    <property name="destroyScript" default="was/virtualhost/destroy-virtual-host.py" hidden="true" />
    <property name="destroyVerb" default="Undeploy" hidden="true" />
    <property name="destroyOrder" kind="integer" default="30" hidden="true" />

    <property name="inspectScript" default="was/virtualhost/inspect-virtual-host.py" hidden="true" />   
    <property name="aliases" kind="set_of_string" description="Virtual host aliases - enter alias as: hostname:port" />
</type>

Notice that the destroyOrder has a low order, because when executing a deployment the virtual host should be destroyed before it can be created again.

Extending the plugin with custom control task

The plugin has the capability to add control tasks to ExtensibleDeployed or PythonManagedContainer. The control task can be specified as a python script that will be executed using wsadmin on the target host or as an OS shell script that will be run on the target host. The OS shell script is first processed with FreeMarker before being executed.

Creating a python script control task to test datasources

Synthetic.xml snippet

<type-modification type="was.Datasource">
  <method name="testDatasource" script="was/resources/ds/test-ds.py" language="python"/>
</type>

test-ds.py snippet

datasource = AdminConfig.getid("%s/JDBCProvider:%s/DataSource:%s/" %
 (deployed.container.containmentPath, deployed.jdbcProvider, deployed.name))
if datasource == '':
  print "WARN: No JDBC DataSource '%s' found. Nothing to do" % (deployed.name)
else:
  print "Testing JDBC DataSource '%s' (config ID '%s')" % (deployed.name, datasource)
  AdminControl.testConnection(datasource)

Creating an os script control task to start the DeploymentManager

Synthetic.xml snippet

<type-modification type="was.DeploymentManager">
  <method name="start" script="was/container/start-dm" language="os"/>
</type>

start-dm.sh snippet for *nix

${container.wasHome}/bin/startManager.sh

start-dm.bat snippet for windows

${container.wasHome}\bin\startManager.bat