Ant Bundles

The "Ant" bundle type provides advanced support for provisioning by utilizing Ant as its main "recipe engine", thus giving you the ability to use core Ant features in addition to the RHQ features built on top of the Ant infrastructure.

Ant Bundle Distribution Files

You can package together all your bundle's files and its Ant recipe in a bundle distribution file. The bundle distribution file must be either a .zip or .jar file. The recipe must be called "deploy.xml" and it must be found in the top root directory of the distribution file.

Standard Ant Tasks

When writing your Ant bundle receipes, you can use any of the standard Ant tasks, with exceptions specified in the section below. This means standard tasks such as echo, mkdir, et. al. can be used within your Ant bundle recipe to perform custom functions that you need to do in order to fully deploy your bundle content.

Prohibited Standard Ant Tasks

The following standard Ant tasks are prohibited from use within your Ant bundle recipe. You cannot use these Ant tasks when writing Ant bundle recipes.

antcall - using antcall causes RHQ to go into an infinite loop, due to the way the antcall task calls back into the Ant build and re-triggers the rhq bundle task. As a workaround, write your custom Ant targets in a separate build XML file and use the <ant> task instead.

macrodef - you cannot define your own macro definitions in the bundle ANT recipe. There is a bugzilla 728217 reported to see if we can fix this and remove this restriction, but as of right now, macrodef does not work.

Optional Ant Tasks

Your Ant bundle recipes can use several optional Ant tasks in addition to the standard core tasks (with caveats). The optional Ant tasks that RHQ provides to your Ant bundle recipes are:

Ant Recipes

An "Ant Recipe" is nothing more than an Ant script that uses the RHQ tasks to define bundle metadata. An example Ant Bundle recipe could look like this:

<?xml version="1.0"?>
<project name="test-bundle" default="main" xmlns:rhq="antlib:org.rhq.bundle">

    <rhq:bundle name="example" version="1.0" description="an example bundle">
        <rhq:input-property
            name="listener.port"
            description="This is where the product will listen for incoming messages"
            required="true"
            defaultValue="8080"
            type="integer"/>

        <rhq:deployment-unit name="appserver" preinstallTarget="preinstall" postinstallTarget="postinstall" compliance="full">
            <rhq:file name="test-v2.properties" destinationFile="subdir/test.properties" replace="true"/>
            <rhq:archive name="file.zip" exploded="true">
                <rhq:replace>
                    <rhq:fileset includes="**/*.properties"/>
                </rhq:replace>
            </rhq:archive>
            <rhq:ignore>
                <rhq:fileset includes="logs/*.log"/>
            </rhq:ignore>
        </rhq:deployment-unit>
    </rhq:bundle>

    <target name="main" />

    <target name="preinstall">
        <echo>Deploying Test Bundle v1.0 to ${rhq.deploy.dir}...</echo>
        <property name="preinstallTargetExecuted" value="true"/>
        <rhq:audit status="SUCCESS" action="Preinstall Notice" info="Preinstalling to ${rhq.deploy.dir}" message="Another optional message">
           Some additional, optional details regarding
           the deployment of ${rhq.deploy.dir}
        </rhq:audit>
    </target>

    <target name="postinstall">
        <echo>Done deploying Test Bundle v1.0 to ${rhq.deploy.dir}.</echo>
        <property name="postinstallTargetExecuted" value="true"/>
    </target>
</project>

For those familiar with Ant, the first thing you will notice is this looks very similar to any other normal Ant script - and that is because, for the most part, it is! First, it is a valid and well-formed XML file. Second, its root XML element is the standard Ant <project> element. And lastly, it defines targets and tasks just as a normal Ant script does. However, you will notice some RHQ custom tasks in here (e.g. <rhq:bundle>). These define metadata that are RHQ-specific and necessary for the RHQ bundle subsystem to provision the bundle files associated with this recipe. Most of the RHQ tasks you see here essentially define a "model" for what the bundle looks like (or will look like once its provisioned). This is slightly different from normal Ant scripts - since some of this recipe isn't looked at as a script per-se; it is more of a definition of what the bundle consists of.

rhq:bundle

This is the main RHQ task that is required for all Ant bundle recipes. It defines basic information about the bundle. Its child elements define more specific details about what is in the bundle and how it should be provisioned.

attribute name	description
name	The name given to the bundle
version	The version string for this specific bundle. Bundles can have the same name - they are differentiated by their version strings. These version strings normally conform to an OSGi style of versioning (e.g. "1.0.0" or "2.4.1.GA")
description	A human readable description of this specific bundle version. (optional)

rhq:input-property

This is similar to normal Ant properties; however, they carry additional importance because they represent replacement variables that may exist in templatized files found within your bundle (more will be said about templatized files in the rhq:file and rhq:archive task descriptions later).

Built-in Replacement Variables

In addition to the standard built-in replacement variables, all Ant script recipes can use the following replacement variables without needing to define them as input properties:

rhq.deploy.dir : the location where the deployment unit is to be installed
rhq.deploy.id : the unique identifier for the deployment
rhq.deploy.name : the name given to the deployment

All input properties defined will be expected to have their values defined by the user that will provision this bundle. This means that the RHQ user interface will ask the user to provide a value for all input properties defined in the bundle recipe. In the example recipe above, RHQ will expect the user to provide an integer value for the "listener.port" property.

attribute name	description
name	The name of the property. You can refer to this property in the recipe using the standard Ant syntax "${var}".
description	A human readable description of this specific bundle version which the user will see when being asked to provide a value for this property.
required	If true, this property must be given a value; if false, it may be left undefined.
defaultValue	If the user does not define a value for this property, this will be its default.
type	The type of value. Valid types are: string, longString, boolean, integer, long, float, double, password, file, directory

rhq:deployment-unit

Each bundle defines a deployment-unit. A deployment unit can be thought of as a software product, such as an application server or a database or a web server. A deployment unit is made up of one or more archives (e.g. zip files) and/or one or more files (e.g. raw files such as scripts or configuration files).

Only a single deployment unit will be provisioned at any one time (i.e. the Ant recipe will never be asked to deploy more than one deployment unit during any one invocation of Ant).

In future versions of RHQ, multiple deployment-units will be supported in order to provide provisioning of multi-tiered applications. In the current version, however, only a single deployment-unit is supported.

attribute name	description
name	The name of the deployment unit (e.g. "appserver" or "database")
~~manageRootDir~~	A boolean (true,false) that specifies if RHQ is to manage all files in the top root directory where the bundle is deployed. If false, any unrelated files found in the top destination directory will be ignored. Default is true. This attribute is still supported but deprecated. Use the compliance attribute instead.
compliance	This is a new required attribute (as of RHQ 4.9.0) that specifies the handling of the deployment directory similarly to how `manageRootDir` used to in previous versions. The currently supported values of this attribute are: `full` - this means that the contents of the bundle completely replaces the contents of the deployment directory. I.e. after deploying the bundle, the deployment directory contains no other files but those deployed by the bundle. `filesAndDirectories` - This compliance mode makes sure that files and directories that are NOT contained in the bundle are kept in the deployment directory. However the contents of files and directories that ARE present in the bundle are made completely compliant with the bundle. I.e. if the deployment directory contained a directory named "dir" with a file called "a" and the bundle contained the same directory "dir" with a file called "b", then after deploying the bundle, the directory "dir" would only contain the file "b". You may notice that the above 2 supported values exactly correspond to the behavior offered by `manageRootDir` with value `true` or `false` respectively. This change was done to make the behavior of the deployment more explicit as well as a preparation for adding more compliance modes in the future.
preinstallTarget	If defined, this names the Ant target that will be invoked prior to the deployment unit getting installed.(optional)
postinstallTarget	If defined, this names the Ant target that will be invoked after the deployment unit was installed.(optional)

rhq:archive

A bundle can have zero, one or more bundle files called "archives" associated with it. An "archive" is simply a zip or jar file.

attribute name	description
name	The name of the archive file. If the recipe and archive file are packaged together inside a bundle distribution zip file, this name must be the relative path name of the archive file found within the bundle distribution zip file. NOTE: You cannot use ${} property definitions in the value of this attribute.
exploded	If true, the archive's contents will be extracted and stored into the bundle destination directory. If false, the zip file will be compressed and stored in the same relative location as the 'name' attribute indicates (relative to the bundle destination directory).

If your archive file is to be exploded, all files will be extracted starting at the root of the destination directory, regardless of where the zip is located in the bundle distribution file (that is, regardless of the relative path of the 'name' attribute). As a workaround, you could perhaps use a postinstall target in your recipe to move files around after they were extracted from your archive.

rhq:url-archive

This is similar to the rhq:archive, except you can specify a remote archive rather than bundling the archive directly in the bundle distribution file. You specify the location of the remote archive via a URL.

attribute name	description
url	The location of the archive file. This will be downloaded and installed in the destination directory, optionally exploded.
exploded	If true, the archive's contents will be extracted and stored into the bundle destination directory. If false, the zip file will be compressed and stored in the top level destination directory.

For the bundle to be successfully deployed, the URL must be accessible to all agent machines where this bundle is to be deployed. If an agent cannot access the URL, it cannot pull down the archive and thus cannot deploy it on the machine.

rhq:replace

As mentioned earlier, you can define input properties to use as replacement variables that are found in templatized files. A templatize file is simple a file that contains replacement variables that need to be substituted for "real" values when the files are written out to the file system during the time when the bundle is being provisioned. The rhq:replace child tag of rhq:archive tells RHQ which files within the archive are templatized and thus which files need to have their replacement variables replaced with real property values. See Provisioning#Templatizing Files for more information on templatized files and replacement variables.

rhq:ignore

When upgrading a previous deployment, there are times when you want to ignore a set of existing files from that previous deployment. In other words, there may be files that you want to retain after the upgrade. For example, there may be data files or log files you do not want to remove during the upgrade procedure (as might be the case when you upgrade a JBossAS app server - you might want to keep the ...default/logs and ...default/data directories). Use the rhq:ignore tag to indicate which directories and files you want to retain when the bundle is used to upgrade a previous bundle deployment.

rhq:file

In addition to archive files, a bundle may be associated with zero, one or more "raw files" - that is, files that are to be copied as-is without attempting to "unpack" them (like would be done with zip or jar files). A raw file may be templatized, in which case it can be run through the template engine to have its replacement variables replaced. A raw file may be copied inside the deployment unit's destination directory or it may be copied anywhere on the file system, so long as RHQ has write permissions to that location on the file system.

attribute name	description
name	The name of the file. If this bundle file was packaged with the recipe in a bundle distribution file, this name must be the relative path of the file as it exists inside the bundle distribution file. NOTE: You cannot use ${} property definitions in the value of this attribute.
destinationFile	The path on the file system where this file is to be copied when being provisioned. If this is a relative path, it is relative to the deployment unit's "deployment directory" as defined by the `rhq.deploy.dir` property that is automatically set by RHQ and whose value is defined by the user provisioning the bundle. If this is an absolute path, that will be the location on the file system where the file will be copied. Note that this attribute is not just a directory name - it is a pathname that also defines the file's name as it will appear on the file system when it is copied. If 'destinationDir' is specified, you cannot specify 'destinationFile'.
destinationDir	The path on the file system where this file is to be copied when being provisioned. If this is a relative path, it is relative to the deployment unit's "deployment directory" as defined by the `rhq.deploy.dir` property that is automatically set by RHQ and whose value is defined by the user provisioning the bundle. If this is an absolute path, that will be the location on the file system where the file will be copied. Note that this attribute is just a directory name - the name of the file will be the same as the 'name' attribute. If 'destinationFile' is specified, you cannot specify 'destinationDir'.
replace	If true, this file is to be considered a templatized file and therefore will need its replacement variables replaced. See Provisioning#Templatizing Files for more information on templatized files and replacement variables.

If you do not specify either 'destinationFile' or 'destinationDir', the default location will be the same relative path as that of the 'name' attribute. In other words, the raw file will be placed in the same location under the destination directory as it was found in the bundle distribution.

rhq:url-file

This is similar to the rhq:file except you can specify a remote raw file rather than bundling the file directly in the bundle distribution file. You specify the location of the remote file via a URL.

attribute name	description
url	The location of the remote file.
destinationFile	The path on the file system where this file is to be copied when being provisioned. If this is a relative path, it is relative to the deployment unit's "deployment directory" as defined by the `rhq.deploy.dir` property that is automatically set by RHQ and whose value is defined by the user provisioning the bundle. If this is an absolute path, that will be the location on the file system where the file will be copied. Note that this attribute is not just a directory name - it is a pathname that also defines the file's name as it will appear on the file system when it is copied. If 'destinationDir' is specified, you cannot specify 'destinationFile'.
destinationDir	The path on the file system where this file is to be copied when being provisioned. If this is a relative path, it is relative to the deployment unit's "deployment directory" as defined by the `rhq.deploy.dir` property that is automatically set by RHQ and whose value is defined by the user provisioning the bundle. If this is an absolute path, that will be the location on the file system where the file will be copied. Note that this attribute is just a directory name - the name of the file will be the same name as the last path element within the 'url' attribute. If 'destinationFile' is specified, you cannot specify 'destinationDir'.
replace	If true, this file is to be considered a templatized file and therefore will need its replacement variables replaced. See Provisioning#Templatizing Files for more information on templatized files and replacement variables.

If you do not specify either 'destinationFile' or 'destinationDir', the default location will be the destination directory.

rhq:audit

You may have a complex recipe that performs some additional custom tasks. As you do custom processing you may want to inform the server what additional steps your recipe is performing and the results of those steps. You can do this via custom audit trail messages using this tag.

attribute name	description
status	The status of your custom processing. Values are: SUCCESS, WARN, FAILURE. Default is SUCCESS
action	The name of your custom processing step
info	A short summary of what your action is doing or did. Sometimes its the name of the target of the action (like a filename)
message	A brief one or two line message indicating more information about your processing

You can optionally provide longer details about your custom processing through CDATA in your audit tag.

Default Target

You'll notice that in the <project> root element, a default target can be named. RHQ recipes are essentially ANT scripts and thus must define a default target and that default target must exist in the recipe. This default target can be named anything; in the example above it is named "main". You will also notice in the example, the main target is essentially a no-op:

<target name="main" />

That's because RHQ makes it simple for you - there is really nothing extra you need to do by default in order to provision a bundle. All you have to do in your recipe is define metadata describing your bundle distribution (that's what the rhq:bundle task and its children tasks do) and let RHQ handle the rest. If, however, you want to do additional, custom things during the time your bundle distribution is provisioned, you can do those additional things in your own defined pre-install and post-install targets, which is discussed below. The main default target is not invoked.

Install and Post-Install Targets

You have the option to define your own pre-install and post-install Ant targets within your recipe. This allows you to do additional custom things immediately before and after the deployment unit is installed. In the example above, you can see the pre-install and post-install targets do some simple things like echoing out a message and setting a property. These do not really do anything useful; however, the point of these example targets is to illustrate that you can invoke standard Ant tasks in your targets (with caveats) or, if you'd like, one of the optional Ant tasks supported by RHQ).

Using Standalone Ant Bundle Deployer Tool

A standalone Ant bundle deployer command-line tool is provided to simplify development and testing of Ant provisioning bundles. Use this tool to help you develop and package your bundle distribution files. The tool is standalone in that it is a self-contained zipfile that can run outside of any RHQ Servers or Agents. The zipfile can be downloaded by going to the Administration > Downloads page in the RHQ GUI and clicking the Download Bundle Deployer link near the bottom of the page. Once you have downloaded the zipfile, unzip it, e.g.:

cd ~/Applications
unzip ~/Downloads/rhq-bundle-deployer-3.0.0.zip

The above example would create the directory ~/Applications/rhq-bundle-deployer-3.0.0 which would contain this standalone Ant bundle deployer tool.

To deploy a bundle using this bundle deployer tool, first unzip your bundle distribution file that you are testing into a test bundle directory, e.g.:

cd ~/Bundles
mkdir yourbundle
cd yourbundle
unzip yourbundle.zip

After you unzip your bundle distribution file to your test bundle directory (in the above example, that would be "~/Bundles/yourbundle"), that test bundle directory should have the Ant bundle recipe file (called deploy.xml) along with the individual bundle files.

From this new test bundle directory, you can now run the Ant bundle deployer tool - if on Linux, you use rhq-ant, if on Windows, you use rhq-ant.bat. For example:

PATH="~/Applications/rhq-bundle-deployer-3.0.0/bin:$PATH"
rhq-ant -Drhq.deploy.dir=~/Applications/yourapp -Dyour.custom.prop1=value1 -Dyour.custom.prop2=value2

This will install the "yourbundle" bundle to the destination directory "~/Applications/yourapp", as specified by the rhq.deploy.dir property. During installation, the other properties passed on the command line via the -D option would be used to perform template variable replacements on files designated as replacement targets by the recipe. In other words, in the example above, the values of "your.custom.prop1" and "your.custom.prop2" are used to replace the replacement variables of the same name in your bundle's templatized files.

You may optionally pass in a property called rhq.deploy.id - this will represent the identifier of your deployment. The default will be 0 if you do not specify it. When actually deploying bundles via RHQ (that is, through the RHQ GUI), the RHQ server will assign each deployment its own unique ID - this rhq.deploy.id property is a way for you to simulate this assignment of a deployment ID via the bundle deployer tool.

If there already is a previous version of the bundle installed in ~/Applications/yourapp, then that application would be upgraded using the upgrade rules described below. If you plan on testing the upgrade capabilities, ensure that you pass in a unique "rhq.deploy.id" property, as described above.

This standalone Ant bundle deployer tool is used only for testing. More specifically, running this tool does not affect the RHQ Server or Agent. If you install a bundle using this standalone Ant tool, the Server and Agent will know nothing about it.

Upgrade Rules

When provisioning bundles of the Ant Bundle Type, there are two main use-cases. The first is performing an "initial installation" - that means, you are provisioning the bundled software for the very first time. The second is an "upgrade" - that is, you are provisioning a bundle in the same destination directory where you already deployed a previous version of the bundle.

When upgrading, there are rules that are applied to determine what to do with the existing files from the previous deployment.
The rules are as follows, where the first three columns represent a file's MD5 hashcode:

ORIGINAL	CURRENT	NEW	What To Do...
X	X	X	New file is installed over current
X	X	Y	New file is installed over current
X	Y	X	Current file is left as-is
X	Y	Y	New file is installed over current
X	Y	Z	New file is installed over current, current is backed up
none	?	?	New file is installed over current, current is backed up
X	none	?	New file is installed
?	?	none	Current file is backed up and deleted

images/author/images/icons/emoticons/star_yellow.gif denotes that the current file could have been left as-is. If, in the future, we can provide Java with a way to change file permissions or ownership, we would want to copy the new file over the current file and perform the chown/chmod.

Here you can see that there is only one non-trivial case where the new file is not installed, and that is when the original file and the new file have the same hashcode (i.e. was not changed) but the current version of that file was changed (in the trivial case, where there is no new file, nothing is installed and the current file is uninstalled). In this case, since the original file and the new file are identical, the file with the modifications made to the original version (called the "current" version) is presumed to still be valid for the new version, thus we leave the current, modified file in place.

In the case where there is ambiguity as to what the right thing to do is, the current file is backed up prior to being overwritten with the new file. This can occur in two cases: the first is when the current file is a modified version of the original and the new file is different from the original; the second is when there was no original file, but there is now a current file on disk and a new file to be installed. In either case, the current file is backed up before the new file is copied over top the current file. Files that need to be backed up will have its backup copied to new deployment's backup metadata directory, under the backup subdirectory called "backup". If a file that needs to be backed up is referred to via an absolute path (that is, outside the destination directory), it will be copied to the "ext-backup" directory found in the metadata directory.

Note that if your recipe indicated a file should be ignored (see rhq:ignore), it will be left as is. Ignored files should never be files that are packaged in a bundle (i.e. an ignored file is never a bundle file itself). Ignored files are typically files that are generated by the software when it is running, such as log files and data files, and usually need to remain intact. Note that RHQ allows you to upgrade to a "clean" destination directory if you wish to delete all files, including ignored files, prior to upgrading.