Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

7.6. Limits and Considerations for Ant Recipes

7.6.1. Unsupported Ant Tasks

As stated in Section 7.4.1, “Supported Ant Tasks”, most standard Ant tasks are supported for use in bundle recipes, but there are some tasks which are not supported:
  • <antcall> (instead, use <ant> to reference a separate XML file in the bundle which contains the Ant targets)
  • <macrodef> and macro definitions

7.6.2. Symlinks

The Java utilities library (java.util.zip) included for the bundling system does not support symbolic links. Therefore, bundle recipes and configuration files cannot use symlinks.
Symlinks may be an issue for an application server (such as EAP or EPP) which was installed initially from an RPM and then compressed to be used in a bundle. The RPMs available from Red Hat Network contain operating system-specific symlinks which would cause failures during provisioning.
If it is necessary to reference shared libraries or other files (which would normally be referenced with a symlink), then include the required libraries in an archive with the bundle and use an Ant task to extract the files when deploying the bundle. For example: 
<untar src="abc.tar.gz" compression="gzip" dest="somedirectory"/>

7.6.3. WARNING: The Managed (Target) Directory and Overwriting or Saving Files

One important thing to consider with an Ant recipe is how to handle files in the deployment directory. (This is touched on in Section 2.3, “File Handling During Provisioning”.)
By default, deploying or updating a bundle replaces everything in the deployment directory, either by overwriting it or deleting it. The file handling rules are very similar to RPM package upgrade rules. This is very simplified, but the provisioning process responds in one of two ways to existing files the deployment directory:
  1. The file in the current directory is also in the bundle. In this case, the bundle file always overwrites the current file. (There is one exception to this. If the file in the bundle has not been updated and is the same version as the local file, but the local file has modifications. In that case, the local file is preserved.)
  2. The file in the current directory does not exist in the bundle. In that case, the bundle deletes the file in the current directory.
The behavior for #2, when a file is deleted, can be changed by settings in the Ant recipe.
There are three ways to manage if and how files are preserved during provisioning: manageRootDir, <rhq:ignore>, and cleanDeployment.
manageRootDir

All of the information about the application being deployed is defined in the <rhq:deployment-unit> element in a bundle recipe. The manageRootDir attribute on the <rhq:deployment-unit> element sets how the provisioning process should handle existing files in the deployment directory.

The default value is manageRootDir=true which means that the provisioning process deletes any other files in the root directory.

Note

Any existing content in the root directory is backed up before it is deleted, so it can be restored later.
The backup directory is /home/.rhqdeployments/resourceID/backup.
Alternately, the value can be set to false, which tells the provisioning process to ignore any existing files in the root directory, as long as there is not a corresponding file in the bundle.
The manageRootDir attribute applies to both the initial deployment and upgrade operations, so this can be used to preserve files that may exist in a directory before a bundle is ever deployed.
See Section 7.7.3, “rhq:deployment-unit”.

Note

When a bundle will no longer be used on a resource, it can be entirely removed from the filesystem. This is called purging. The way that the provisioning system handles files when purging a bundle mirrors that way that it handles files when provisioning a system. By default, purging a bundle deletes everything in the deployment directory. If the manageRootDir option is set in the bundle, then the provisioning process removes all of the files and directories associated with the bundle and leaves unrelated files and directories intact.
<rhq:ignore>

There can be files that are used or created by an application, apart from the bundle, which need to be preserved after a bundle deployment. This can include things like log files, instance-specific configuration files, or user-supplied content like images. These files can be ignored during the provisioning process, which preserves the files instead of removing them.

To save files, use the <rhq:ignore> element and list the directories or files to preserve. 
<rhq:ignore>
    <rhq:fileset>
        <include name="logs/*.log"/>
    </rhq:fileset>
</rhq:ignore>
The <rhq:ignore> element only applies when bundles are updated; it does not apply when a bundle is initially provisioned.
Also, the <rhq:ignore> element only applies to file that exist outside the bundle. Any files that are in the bundle will overwrite any corresponding files in the deployment directory, even if they are specified in the <rhq:ignore> element.
See Section 7.7.10, “rhq:ignore”.
Clean Deployment

Both manageRootDir and <rhq:ignore> are set in the recipe. At the time that the bundle is actually provisioned, there is an option to run a clean deployment. The clean deployment option deletes everything in the deployment directory and provisions the bundle in a clean directory, regardless of the manageRootDir and <rhq:ignore> settings in the recipe.

See Section 9.5, “Deploying a Bundle to a Clean Destination”.