Dukes Bank Provisioning JBoss instances
From ControlTier
This is part of the DukesBank portion of the ControlTier Demo
Contents |
Overview
In this demo we are going to deploy and start an empty instance of JBoss that will later have the Dukes Bank application deployed to it. This example shows the JBossServer type coordinating the deploy cycle that includes: shutdown, package download, configuration and startup.
The JBossServer type is actually a subtype of Service and therefore inherits deployment and service cycle management commands from the Service type.
See also:
- Dukes Bank and Operations page for information about managing the service runstate (e.g., startup, shutdown, status).
- Dukes Bank and Multiple Nodes page for information on deploying JBoss to more than one Node
Watch a video of this demo (less than 5:00)
Prerequisites
This demo assumes you have completed:
Preparation
Before getting started confirm the JBossServer and Site objects are deployed to CTL.
Run the ctl-project install command for the demo project:
$ ctl-project -p demo -a install "Install" command running for resource: (Site) developmentDukesBank . . . "Install" command running for resource: (JBossServer) developmentDukesBank . . .
Your output should show the Site and JBossServer (among other objects).
You are now ready to run the demo.
Running the Example
You can run any of the Service commands like so: ctl -p demo -t JBossServer -r developmentDukesBank -c <command-name>
If you run the command without the -c <command-name> parameter you will see a listing of commands.
Run Deploy
Run the Deploy command without arguments:
ctl -p demo -t JBossServer -r developmentDukesBank -c Deploy
This command tells the CTL client to "run the Deploy command for the developmentDukesBank object (of type JBossServer) in the demo project".
After the command completes, you should be able to see the management screen of an empty JBoss instance at http://localhost:8180 (or your server's hostname).
You can also run a CTL command to check the status of the JBoss instance like so:
ctl -p demo -t JBossServer -r developmentDukesBank -c Status
begin workflow command (1/1) -> "assertServiceIsUp " ... JBoss is UP. end workflow command (1/1) -> "assertServiceIsUp "
What the Example Shows
You saw a lot of output from the Deploy but what did it do? The nitty gritty is explained in the #How it Works and #The Output sections but here's what occurred at a high level:
- The resource model describing the developmentDukesBank JBossServer was synchronized to the CTL framework. This resource model drives all the automation commands.
- This resource model described where the JBoss instance runs, what packages it uses, what listening port it binds to, as well as, the scripts to use to drive various steps of the end-to-end process.
- Deploy calls the Stop command to shutdown the running JBoss instance in case it had already been running. The shutdown procedure used scripts that are configured for this step.
- One of these scripts used information from the resource model to lookup the JBoss connector port to see if it was listening on that socket. Another command checked the listening port to ensure the service had stopped listening.
- Deploy's next step handled the package installation workflow. This step downloaded, extracted the JBoss server distribution, also part of the resource model.
- During the installation phase of the Zip, a "finish" script was called to customize the JBoss installation by setting permissions and execute bits.
- After the packages were installed, Deploy ran the Configure command which generates several configuration files
- Configuration file generation was handled by Docs-Generate, a command that uses a set of templates to generate into the server/default/conf directory: binds.xml, jboss-service.xml and run.conf
- The final step called by Deploy was to run the Start command which handles the JBoss startup.
- This used two scripts named in the resource model to check if the JBoss was already up and if not to call the JBoss run.sh script. After the run.sh script was called, another command waited until a particular log message was found in the log file.
How it Works
The diagram below describes the resource model for this example. The model describes a JBossServer deployed to one Node. The JBossServer is configured to install a JBossZip package. The service uses two settings to define ports and java options. Lastly, there is an association to a HsqldbRdb resource that represents the JBoss' dependency on the Hypersonic database.
From Workbench you can see the developmentDukesBank JBossServer's resource model from the "Service Manager" page:
You can see one Package assignement along with one Node, the host where developmentDukesBank is deployed.
The developmentDukesBank JBossServer resource model is defined in a project XML file generated into the $CTIER_ROOT/demo. directory. The following sections walk through the XML definition files used to define its resource model. Each type of resource has an associated set of metadata. First the metadata describing the package is reviewed and then the metadata about the Service.
The Package definitions
One package was defined for this example: jboss-4.0.3SP1.zip. This Zip contains the distribution for JBoss 4.0.3SP1.
Package metadata is defined using the package tag. This tag uses a set of attributes to define the various bits of information describing each package.
Below you can see metadata about the jboss-4.0.3SP1.zip file. The metadata includes information like build time, install root directory, version among other properties. This metadata defines a package named "jboss-4.0.3SP1.zip" that is of type, "JBossZip". The normal naming convention for a package is to use its filename as the resource name. The type name (in this case "JBossZip") specifies which Package subtype to use. Package subtypes can provide their own install life cycle implementations. For example, the "JBossZip" type defines an extract command that understands how to extract Zip archives as well as how to perform extra steps like changing permissions and ownerships.
File listing: jboss-4.0.3SP1.zip.xml
<package
type="JBossZip"
name="jboss-4.0.3SP1.zip"
version="4.0.3SP1"
release=""
buildtime=""
arch="noarch"
filename="jboss-4.0.3SP1.zip"
filetype="zip"
base="jboss-4.0.3SP1"
installroot="${resource.attribute.jboss_install_root}"
repoUrl="/zip/zips/jboss-4.0.3SP1.zip"
releasetag=""
installrank="30"
restart="false"
vendor="Red Hat Middleware, LLC."
description="JBoss Enterprise Application Platform package"/>
The Service definition
This section describes the definition of the JBossServer resource. The service definition is broken into two parts: one for settings and the other for the Service itself. The section will walk through the XML definition found in the file listing contained in $CTIER_ROOT/demo/default-object.xml.
Settings
Settings can be used to describe any kind of information that is essentially a named key/value pair.
Below is the XML used to define these settings for the developmentDukesBank JBossServer resource model.
The setting tag is used to define the each setting type and corresponding setting value. You can see two settings:
<!-- JBossServer settings: --> <setting type="JBossPortConfig" name="developmentDukesBank" description="JBoss service bindings port configuration" settingValue="ports-01"/> <setting type="JBossJavaOpts" name="developmentDukesBank" description="JBoss Java options" settingValue="-Djava.naming.provider.url=jnp://localhost:1199"/>
Service
This section describes how to tie the Service resource model together. The resource model describing the example Service entails referencing the setting information just described as well as referencing any packages that should be installed during deployment. For the developmentDukesBank service that means referencing the two settings and the one package.
A service is defined using a deployment tag. The deployment tag uses a set of attributes to name and specify the type of resource (eg name="developmentDukesBank" type="JBossServer"). The installRoot and basedir attributes declare the location of the JBoss installation.
The settings and packages are referenced as resource elements inside the resources element. The node where this JBossServer is to be deployed is referenced in the referrers element.
Here's the XML that ties the service, settings and package information together:
<deployment
type="JBossServer" name="developmentDukesBank"
description="Development environment JBoss server"
basedir="/Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/server/default"
installRoot="/Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1"
startuprank="2">
<resources replace="true">
<resource type="JBossZip" name="jboss-4.0.3SP1.zip"/>
<resource type="JBossPortConfig" name="developmentDukesBank"/>
<resource type="JBossJavaOpts" name="developmentDukesBank"/>
<resource type="HsqldbRdb" name="developmentDukesBank"/>
</resources>
<referrers replace="false">
<resource type="Node" name="strongbad"/>
</referrers>
</deployment>
The Output
The Deploy command is a workflow that calls a sequence of four commands: Stop, Packages-Install, Configure, Start.
You can preview the actions of the Deploy workflow from Workbench. Navigate to the developmentDukesBank[Service] object from the "Service Manager" and press the "Commands" tab. Locate the "Deploy" workflow and press the yellow button to right.
You will see the Process Flow view display workflow structure across the commands that are dispatched by Deploy.
You can see the Deploy workflow has several steps:
- Stop: Shutdown the server (if it is not already stopped)
- Packages-Install: Download, extract and install any package dependencies
- Configure: Perform post package installation configuration steps
- Start: Start up the server.
You can also see that these steps are workflows themselves, each of which has it's own sub structure. Note also that all the commands are running on the Node "centos".
Since there's quite a lot of output messages from Deploy we'll look at each command in turn and examine output from each.
First let's look at the Stop command.
ctl -p demo -t JBossServer -r developmentDukesBank -c Stop
Stop calls assertServiceIsDown command which checks if JBoss is already down.
begin workflow command (1/4) -> "Stop " ... begin workflow command (1/1) -> "assertServiceIsDown " ... alexh 18933 0.2 20.9 325120 108008 ? Sl 01:48 2:53 /home/alexh/ctier/pkgs/jdk1.5.0_17/bin/java -server -Dprogram.name=run.sh -Djava.endorsed.dirs=/home/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/lib/endorsed -classpath /home/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/bin/run.jar:/home/alexh/ctier/pkgs/jdk1.5.0_17/lib/tools.jar org.jboss.Main -c default Error handler caught failed command execution: developmentDukesBank[JBossServer]->assertServiceIsDown. reason: The following error occurred while executing this line: /home/alexh/ctier/ctl/projects/default/modules/JBossServer/commands/assertServiceIsDown.xml:33: shellscript returned: 1 Running handler command: stopServiceWrapper Workflow beginning. commands: stopService,waitforStopEvent begin workflow command (1/2) -> "stopService " ... Shutdown message has been posted to the server. Server shutdown may take a while - check logfiles for completion end workflow command (1/2) -> "stopService " begin workflow command (2/2) -> "waitforStopEvent " ... end workflow command (2/2) -> "waitforStopEvent " end workflow command (1/1) -> "assertServiceIsDown " end workflow command (1/4) -> "Stop "
In this example output, the assertServiceIsDown detected the JBoss instance was was running causing Stop to call stopServiceWrapper, also a workflow that calls two commands: stopService to shutdown JBoss and then waitforStopEvent which checks the JBoss listening port to ensure the service did go down.
If the Stop command was run again, assertServiceIsDown would detect the JBoss instance down and the Stop workflow would have completed then.
Next let's look at the output of the Packages-Install command.
ctl -p demo -t JBossServer -r developmentDukesBank -c Packages-Install
This command is a workflow that iterates over each of the assigned Package resources and for each calls that packages Install command. The Install command is a Package type workflow that kicks off each step in the package installation life cycle.
It's easiest to break up this output and discuss each step.
begin workflow command (2/4) -> "Packages-Install " ... Start: "Install the configured package dependencies for the deployment." Beginning installation for packages: jboss-4.0.3SP1.zip[JBossZip] ... Dispatching command 'assertPackageIsVerified' to objects: jboss-4.0.3SP1.zip[JBossZip] ... starting: jboss-4.0.3SP1.zip[JBossZip]->assertPackageIsVerified ...
The first step in the package installation cycle is assertPackageIsVerified which wraps each of the package installation cycles to ensure a verified result.
Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/JBossZip-head.jar To: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/JBossZip-head.jar Created dir: /Users/alexh/ctier/ctl/projects/demo/modules/JBossZip Expanding: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/JBossZip-head.jar into /Users/alexh/ctier/ctl/projects/demo/modules/JBossZip Attempting to get PlatformZip-head.jar ... Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/PlatformZip-head.jar To: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/PlatformZip-head.jar Created dir: /Users/alexh/ctier/ctl/projects/demo/modules/PlatformZip Expanding: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/PlatformZip-head.jar into /Users/alexh/ctier/ctl/projects/demo/modules/PlatformZip Attempting to get zip-head.jar ... Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/zip-head.jar To: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/zip-head.jar Not modified - so not downloaded zip up to date Attempting to get Package-head.jar ... Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/demo/publish/modules/Package-head.jar To: /Users/alexh/ctier/ctl/var/tmp/downloads/demo/Package-head.jar Not modified - so not downloaded Package up to date
The Package Install command does a couple things:
- downloads the needed command module jar files that contains the Zip specific install cycle commands (eg JBossZip-head.jar).
- checks if the package was previously installed and then calls
installPackagewhich does all the work of getting, extracting and finishing the installation (ie, steps 1-5).
The next bit of output is the workflow run by installPackage a workflow that calls these commands: installDependencies,preapre,get,extract,finish
begin workflow command (1/1) -> "assertPackageIsInstalled -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1" ... Running handler command: installPackage
The installDependencies command checks to see if this Package has package resources assigned to it. The jboss-4.0.3S1.zip package does not but if it had those would have been installed before proceeding to the next step.
begin workflow command (1/5) -> "installDependencies -filename jboss-4.0.3SP1.zip -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip" ... Dispatching command 'Install' to objects: ... end workflow command (1/5) -> "installDependencies -filename jboss-4.0.3SP1.zip -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip"
Next, the prepare command runs. It's job is to perform any pre-install steps. It's a "hook command" and can be configured to call one of your scripts. In this case, nothing special is done.
begin workflow command (2/5) -> "prepare -filename jboss-4.0.3SP1.zip -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip" ... end workflow command (2/5) -> "prepare -filename jboss-4.0.3SP1.zip -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip"
The get command obtains the package archive file from the repository
begin workflow command (3/5) -> "get -filename jboss-4.0.3SP1.zip -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip" ... Created dir: /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip To: /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/jboss-4.0.3SP1.zip end workflow command (3/5) -> "get -filename jboss-4.0.3SP1.zip -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip"
After the package archive is obtained, it is extracted. Besides unzip'ing the file, this command also performs some customization: changing permissions and ownerships.
begin workflow command (4/5) -> "extract -filename jboss-4.0.3SP1.zip -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip" ... Expanding: /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/jboss-4.0.3SP1.zip into /Users/alexh/ctier/demo/elements/development/dukesbank [command.timer.extract: 11.971 sec] command completed successfully. Execution time: 11.971 sec end workflow command (4/5) -> "extract -filename jboss-4.0.3SP1.zip -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip"
Finally, the finish command runs. This like the prepare command is a hook where you can configure your own post-installation procedure to run.
begin workflow command (5/5) -> "finish -filename jboss-4.0.3SP1.zip -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip" ... Deleting: /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/jboss-4.0.3SP1.zip [command.timer.demo.PlatformZip.jboss-4.0.3SP1.zip.finish: 0.171 sec] end workflow command (5/5) -> "finish -filename jboss-4.0.3SP1.zip -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1 -url http://strongbad:8080/jackrabbit/repository/controltier/projects/pkgs/demo/zip/zips/jboss-4.0.3SP1.zip"
The final messages are from the assertPackageisVerified command that checks that the steps completed.
end workflow command (1/1) -> "assertPackageIsInstalled -installroot /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1" [command.timer.demo.Package.Install: 34.045 sec] Workflow completed. execution time: 34.045 sec Executing script: /Users/alexh/ctier/ctl/projects/demo/modules/Package/bin/is-verified.xml ... Package is VERIFIED Completed: Installed packages: jboss-4.0.3SP1.zip[JBossZip] end workflow command (2/4) -> "Packages-Install "
The jboss-4.0.3SP1.zip installation completed and was verified.
After the Packages-Install command, the next command in the Deploy sequence is Configure
ctl -p demo -t JBossServer -r developmentDukesBank -c Configure
The Configure workflow calls Docs-Generate which generates any registered configuration documents from templates. Our developmentDukesBank example produces several of them (bindings.xml, jboss-service.xml, run.conf).
begin workflow command (3/4) -> "Configure " ... begin workflow command (1/1) -> "Docs-Generate " ... Copying 3 files to /home/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/server/default Copying /home/alexh/ctier/ctl/projects/default/modules/JBossServer/templates/jboss-4.0.3SP1/server/default/conf/bindings.xml.template to /home/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/server/default/conf/bindings.xml Copying /home/alexh/ctier/ctl/projects/default/modules/JBossServer/templates/jboss-4.0.3SP1/server/default/conf/jboss-service.xml.template to /home/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/server/default/conf/jboss-service.xml Copying /home/alexh/ctier/ctl/projects/default/modules/JBossServer/templates/jboss-4.0.3SP1/server/default/conf/run.conf.template to /home/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/server/default/conf/run.conf Updating HsqldbRdb module ... Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/default/publish/modules/HsqldbRdb-head.jar To: /home/alexh/ctier/ctl/var/tmp/downloads/default/HsqldbRdb-head.jar Not modified - so not downloaded HsqldbRdb up to date Updating process view file ... Framework info: Type module: /home/alexh/ctier/ctl/projects/default/modules/HsqldbRdb Object directory: /home/alexh/ctier/ctl/projects/default/resources/JBossServer/developmentDukesBank Object properties file: /home/alexh/ctier/ctl/projects/default/resources/JBossServer/developmentDukesBank/var/resource.properties Object process view file: /home/alexh/ctier/ctl/projects/default/resources/JBossServer/developmentDukesBank/var/pview.xml Updating HsqldbRdbSchema module ... Getting: http://strongbad:8080/jackrabbit/repository/controltier/projects/default/publish/modules/HsqldbRdbSchema-head.jar To: /home/alexh/ctier/ctl/var/tmp/downloads/default/HsqldbRdbSchema-head.jar Not modified - so not downloaded HsqldbRdbSchema up to date Updating process view file ... Framework info: Type module: /home/alexh/ctier/ctl/projects/default/modules/HsqldbRdbSchema Object directory: /home/alexh/ctier/ctl/projects/default/resources/JBossServer/developmentDukesBank Object properties file: /home/alexh/ctier/ctl/projects/default/resources/JBossServer/developmentDukesBank/var/resource.properties Object process view file: /home/alexh/ctier/ctl/projects/default/resources/JBossServer/developmentDukesBank/var/pview.xml Generating "hsqldb-ds.xml" for (HsqldbRdb) developmentDukesBank (HsqldbRdbSchema) developmentDukesBank ... Copying 1 file to /home/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/server/default/deploy end workflow command (1/1) -> "Docs-Generate " end workflow command (3/4) -> "Configure "
See Generating_Configuration_Files for information about using Docs-Generate.
The last step in the Deploy workflow is the Start command.
ctl -p demo -t JBossServer -r developmentDukesBank -c Start
The Start workflow calls assertServiceIsUp which checks the process table for a running JBoss instance.
The assertServiceIsUp command detects the JBoss instance is down so Start calls the startServiceWrapper command which is in turn, is a workflow that calls: startService,waitforStartEvent.
begin workflow command (4/4) -> "Start " ... begin workflow command (1/1) -> "assertServiceIsUp " ... JBoss is not UP! Running handler command: startServiceWrapper Workflow beginning. commands: startService,waitforStartEvent begin workflow command (1/2) -> "startService " ... Created dir: /Users/alexh/ctier/demo/elements/development/dukesbank/jboss-4.0.3SP1/server/default/log end workflow command (1/2) -> "startService " begin workflow command (2/2) -> "waitforStartEvent " ... end workflow command (2/2) -> "waitforStartEvent " end workflow command (1/1) -> "assertServiceIsUp " end workflow command (4/4) -> "Start "
The startService command defined in the JBossServer type invokes the JBoss "run.sh" script passing to it the Java options specified in the settings. The waitforStartEvent is called after and checks the JBoss log file until it sees the expected start up string in it.
Summary
In this Demo we covered:
- Viewing the process flow of a workflow command in Workbench
- Using the Deploy command to deploy and start an empty JBoss server
Related demos:
- Dukes Bank Checkout and Build for information on coordinating the build process for the application packages.
- Dukes Bank and Operations for information about managing the service cycle of the JBoss server(e.g., startup, shutdown, status).
Related examples:
