Preface

This document describes the functionality provided by the JBoss Domain (JBoss AS 7.1+, JBoss EAP 6) plugin.

See the Deployit Reference Manual for background information on Deployit and deployment concepts.

Overview

The JBoss Domain plugin is a Deployit plugin that adds the capability to manage deployments and resources on JBoss application server 7.1+ or JBoss EAP 6. The plugin has the capability of managing application artifacts, datasource and other JMS resources via the JBoss Cli, and can easily be extended to support more deployment options or management of new artifacts/resources on JBoss AS.

Features

• Domain and Standalone mode support
• Deployment of application artifacts
  • Enterprise application (EAR)
  • Web application (WAR)
• Deployment of resources
  • Datasource including XA Datasource
  • JMS Queue
  • JMS Topic
• Discovery of Profiles and ServerGroups in Domain

Requirements

• Deployit requirements

  • Deployit: version 3.7+

• Infrastructural requirements

  • JBoss AS versions: 7.1+
  • JBoss EAP versions: 6.x
  • User credentials for accessing the Host and JBoss Cli.

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 JBoss AS specific deployment package. It contains declarations for an Ear, a datasource and a couple of JMS resources.

Manifest-Version: 1.0
Deployit-Package-Format-Version: 1.3
CI-Application: SampleApp
CI-Version: 1.0

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

Name: testDatasource
CI-Type: jbossdm.DatasourceSpec
CI-jndiName: jdbc/sampleDatasource
CI-connectionUrl: jdbc:mysql://localhost/test
CI-driverName: mysql
CI-username: {{DATABASE_USERNAME}}
CI-password: {{DATABASE_PASSWORD}}

Name: testQueue
CI-Type: jbossdm.QueueSpec
CI-jndiName: jms/testQueue

Name: testTopic
CI-Type: jbossdm.TopicSpec
CI-jndiName: jms/testTopic

Using the deployables and deployeds

The following table describes which deployable/container combinations are possible.

Deployable vs. Container table

The following table describes the effect a deployed has on it's container

Deployed Actions Table

Deploying applications

Note that the plugin uses the JBoss Cli to (un)install artifacts and resources. As such, the plugin assumes that the JBoss Domain or Standalone server has already been started. The plugin does not support the starting of the domain or standalone server prior to a deployment.

Standalone Mode

Artifacts (war, ear) and resources (datasources, queues, topics, etc) can be targeted to a StandaloneServer.

Domain Mode

Artifacts (war, ear) can be targeted to either a Domain or ServerGroup. When targeted to a domain, the artifacts are (un)installed on all server groups defined for the domain. For specific targetting of artifacts to certain server groups, you can define the server groups in your environment.

Resources (datasources, queues, topics, etc) can be targeted to either a Domain or Profile. When targeted to a domain, the resources are (un)installed in the "default" profile. For specific targetting of resources to certain profiles, you can define the profiles in your environment.

Discovery

The plugin supports the discovery of Profiles and Server Groups in a Domain.

Here is an example CLI script which discovers a sample Domain:

host = repository.create(factory.configurationItem('Infrastructure/jboss-host', 'overthere.SshHost',
    {'connectionType':'SFTP','address': 'jboss-7','username': 'root','password':'centos','os':'UNIX'}))
jboss = factory.configurationItem('Infrastructure/jboss-host/jboss-domain', 'jbossdm.Domain',
    {'home':'/opt/jboss/7', 'host':'Infrastructure/jboss-host', 'username':"jbossAdmin", "password":"jboss"})

taskId = deployit.createDiscoveryTask(jboss)
deployit.startTaskAndWait(taskId)
cis = deployit.retrieveDiscoveryResults(taskId)
deployit.print(cis)

#discovery just discovers the topology and keeps the configuration items in memory. Save them in Deployit repository
repository.create(cis)

Few things to note about the above discovery example:

• JBoss Domain has a containment relation with a Host (created under a Host), so the server id has been kept as 'Infrastructure/jboss-host/jboss-domain'

Extension points

The plugin is designed to be extended through Deployit's Plugin API type system and jython. The plugin wraps the JBoss Cli with a jython runtime environment, thus allowing extenders to interact with JBoss and Deployit from the script. Note that the jython script is executed on the Deployit Server itself and has full access to the following Deployit objects :

• deployed: The current deployed object on which the operation has been triggered.
• step: The step object that the script is being executed from. Exposes an overthere remote connection for file manipulation and a method to execute JBoss Cli commands.
• container: The container object to which the deployed is targeted to.
• delta: The delta specification that lead to the script being executed.
• deployedApplication: The entire deployed application.

The plugin associates Create, Modify, Destroy, Noop and Inspect operations received from Deployit with jython scripts that need to be executed for the specific operation to be performed.

There also exists an advanced method to extend the 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. Also refer to the Overthere documentation for working with remote files.

Extending the plugin to support JDBC Driver deployment

In this example we will deploy a jdbc driver jar to a Domain or StandaloneServer as a module and register the driver with JBoss datasources subsystem.

Define the deployed and deployable to represent a JDBC Driver

The following synthetic.xml snippet shows the definition of the JDBC Driver deployed. The deployed will be targeted to a Domain or a StandaloneServer. Please refer to the CI reference section of this document to understand the interfaces and class hierarchy of these types.

<type type="jbossdm.JdbcDriverModule" extends="jbossdm.CliManagedDeployedArtifact" 
      deployable-type="jbossdm.JdbcDriver" container-type="jbossdm.CliManagingContainer">
  <generate-deployable type="jbossdm.JdbcDriver" extends="udm.BaseDeployableArchiveArtifact">

  <property name="driverName"/>
  <property name="driverModuleName"/>
  <property name="driverXaDatasourceClassName/>

  <!-- hidden properties to specify the jython scripts to execute for an operation -->
  <property name="createScript" default="jboss/dm/ds/create-jdbc-driver.py" hidden="true"/>
</type>

Defined the create-jdbc-driver.py

from com.xebialabs.overthere.util import OverthereUtils

#create module directory to copy jar and module.xml to
driverModuleName = deployed.getProperty("driverModuleName")
moduleRelPath = driverModuleName.replaceAll("\\.","/")
moduleAbsolutePath = "%s/modules/%s" % (container.getProperty("home"), moduleRelPath)
moduleDir = step.getRemoteConnection().getFile(moduleAbsolutePath);
moduleDir.mkdirs();
#upload jar
moduleJar = moduleDir.getFile(deployed.file.getName())
deployed.file.copyTo(moduleJar)

moduleXmlContent = """
 <?xml version="1.0" encoding="UTF-8"?>
 <module xmlns="urn:jboss:module:1.0" name="%s">
    <resources>
       <resource-root path="%s"/>
    </resources>
    <dependencies>
       <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
 </module>
 """ % (deployed.getProperty("driverModuleName"), deployed.file.getName())

#create module.xml
moduleXml = moduleDir.getFile("module.xml")
OverthereUtils.write(moduleXlContent.getBytes(),moduleXml)

#register driver with the datasource subsystem
driverName = deployed.getProperty("driveName")
xaClassName = deployed.getProperty("driverXaDatasourceClassName")
cmd = '/subsystem=datasources/jdbc-driver=%s:add(driver-name="%s",driver-module-name="%s",driver-xa-datasource-class-name="%s")'      % (driverName, driverName, driverModuleName, xaClasName)
cmd = prependProfilePath(cmd) #prefix with profile if deploying to domain
executeCmd(cmd)  #used to execute a JBoss Cli command.

Extending the plugin with custom control task

The plugin has the capability to add control tasks to CliManagedDeployed or CliManagedContainer. The control task can be specified as a jython script that will be executed on the Deployit Server 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 jython based control task to list jdbc drivers in a StandaloneServer

Synthetic.xml snippet

<type-modification type="jbossdm.StandaloneServer">
  <property name="listJdbcDriversPythonTaskScript" hidden="true" default="jboss/dm/container/list-jdbc-drivers.py"/>
  <!-- Note "PythonTaskScript" is appended to the method name to determine the script to run. -->
  <method name="listJdbcDrivers"/>
</type-modification>

list-jdbc-drivers.py snippet

drivers = executeCmd("/subsystem=datasources:installed-drivers-list")
logOutput(drivers)  #outputs to the step log

Start the StandaloneServer

Synthetic.xml snippet

<type-modification type="jbossdm.StandaloneServer">
  <property name="startShellTaskScript" hidden="true" default="jboss/dm/container/start-standalone"/>
  <!-- Note "ShellTaskScript" is appended to the method name to determine the script to run. -->
  <method name="start"/>
</type-modification>

start-standalone.sh snippet

nohup ${container.home}/bin/standalone.sh >>nohup.out 2>&1 &
sleep 2
echo background process to start standalone server executed.

Upgrade notes

Upgrading from version 3.9.3 or below

Please note, that starting from version 3.9.4 of the plugin jython-standalone dependency does not need to be added to <DEPLOYIT_SERVER_HOME>/lib. It became part of the distribution, and if you have get a conflict due to 2 jython jars being present on the classpath, please resolve it manually by keeping only the latest one.