27.5. Creating Ant Bundles
Bundles are archive files that is stored on the server and then downloaded by an agent to deploy to a platform or resource. A bundle distribution is comprised of two elements:
- An Ant recipe file named
deploy.xml - Any associated application files. These application files can be anything; commonly, they fall into two categories:
- Archive files (JAR or ZIP files)
- Raw text configuration files, which can include tokens where users define the values when the bundle is deployed
Note
The process and guidelines for actually creating an Ant recipe are outside the scope of this documentation. This document outlines the options and requirements for using Ant recipes specifically to work with the JBoss ON provisioning system.
For basic instructions, options, and tutorials for writing Ant tasks, see the Apache Ant documentation at http://ant.apache.org/manual/index.html.
27.5.1. Supported Ant Versions
| Software | Version |
|---|---|
| Ant | 1.8.0 |
| Ant-Contrib | 1.0b3 |
27.5.2. Additional Ant References
Provisioning relies on Ant configuration and tasks, so a good understanding of the Ant build process is beneficial. There are several resources for additional Ant information:
Ant Information Resources
- Apache Ant Documentation Main Page
- Ant Build File Documentation
- Liquibase Database Schema Tasks
- Ant-Contrib Documentation
27.5.3. Breakdown of an Ant Recipe
The Ant recipe for JBoss ON bundles is the same basic file as a standard Apache Ant file and is processed by an integrated Ant build system in JBoss ON. This Ant recipe file must be bundled in the top directory of the distribution ZIP file and be named
deploy.xml.
The JBoss ON Ant recipes allows all of the standard tasks that are available for Ant builds, which provides flexibility in scripting a deployment for a complex application. The JBoss ON Ant recipe must also provide additional information about the deployment that will be used by the provisioning process; this includes information about the destination and, essentially, metadata about the application itself.
Example 27.1. Simple Ant Recipe
For provisioning, the Ant recipe is more of a definition file than a true script file, although it can call Ant targets and do pre- and post-provisioning operations. As with other Ant scripts, the JBoss ON Ant recipe uses a standard XML file with a <project> root element and defined targets and tasks. The elements defined in the <rhq:bundle> area pass metadata to the JBoss ON provisioning system when the project is built.
The first part of the
deploy.xml file simply identifies the file as an an script and references the provisioning Ant elements.
<project name="test-bundle" default="main" xmlns:rhq="antlib:org.rhq.bundle">
The next element identifies the specific bundle file itself. The provisioning system can manage and deploy multiple versions of the same application; the <rhq:bundle> element contains information about the specific version of the bundle (including, naturally enough, an optional version number).
<rhq:bundle name="Example App" version="2.4" description="an example bundle">
All that is required for a recipe is the <rhq:bundle> element that defines the name of the application. However, the bundle element contains all of the information about the application and, importantly, how the provisioning system should handle content contained in the application.
The first item to address is any templatized property that is used in a configuration file. This is covered in Section 27.5.5, “Using Templatized Configuration Files”. Any token used in a configuration file must be defined in the recipe for it to be realized (to have a value supplied) during provisioning. For the
port token defined in Section 27.5.5, “Using Templatized Configuration Files”, the <rhq:input-property> element identifies it in the recipe. The name argument is the input_field value in the token, the description argument gives the field description used in the UI and the other arguments set whether the value is required, what its allowed syntax is, and any default values to supply. (This doesn't list the files which use tokens, only the tokens themselves.)
<rhq:input-property
name="listener.port"
description="This is where the product will listen for incoming messages"
required="true"
defaultValue="8080"
type="integer"/>
There is a single element which identifies all of the content deployed by the bundle, the <rhq:deployment-unit> element. The entire application — its name, included ZIP or JAR files, configuration files, Ant targets — are all defined in the <rhq:deployment-unit> parent element.
The name and any Ant targets are defined as arguments on <rhq:deployment-unit> directly. In this, the name is appserver, and one preinstall target and one postinstall target are set.
<rhq:deployment-unit name="appserver" preinstallTarget="preinstall" postinstallTarget="postinstall" compliance="filesAndDirectories">
There is one other critical element on the <rhq:deployment-unit> element: the compliance argument. Provisioning doesn't simply copy over files; as described in Section 27.1.3, “File Handling During Provisioning”, it remakes the directory to match what is in the bundle. If there are any existing files in the deployment directory when the bundle is first deployed, they are deleted by default. Setting compliance to filesAndDirectories means that the provisioning process does not manage the deployment directory — meaning any existing files are left alone when the bundle is deployed.
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.
Any configuration file is identified in an <rhq:file> element. The
name is the name of the configuration file within the bundle, while the destinationFile is the relative (to the deployment directory) path and filename of the file after it is deployed.
<rhq:file name="test-v2.properties" destinationFile="conf/test.properties" replace="true"/>
Bundles can contain archive files, either ZIP or JAR files. Every archive file is identified in an <rhq:archive> element within the deployment-unit. The <rhq:archive> element does three things:
- Identify the archive file by name.
- Define how to handle the archive. Simply put, it sets whether to copy the archive over to the destination and then leave it as-is, still as an archive, or whether to extract the archive once it is deployed. This is called exploding the archive. If an archive is exploded, then a postinstall task can be called to move or edit files, as necessary.
- Identify any files within the archive which contain tokens that need to be realized. This is a child element, <rhq:fileset>. This can use wildcards to include types of files or files within subdirectories or it can explicitly state which files to process.
<rhq:archive name="MyApp.zip" exploded="true">
<rhq:replace>
<rhq:fileset>
<include name="**/*.properties"/>
</rhq:fileset>
</rhq:replace>
</rhq:archive>
Another possible child element sets how to handle any files within the deployment directory that are not part of the bundle. For example, the application may generate log files or it may allow users to upload content. By default, the provisioning process cleans out a directory from non-bundle content every time a bundle is provisioned. However, logs, user-supplied data, and other types of files are data that should remain intact after provisioning. Any files or subdirectories which should be ignored by the provisioning process (and therefore preserved) are identified in the <rhq:ignore> element. In this case, any
*.log files within the logs/ directory are saved.
<rhq:ignore>
<rhq:fileset>
<include name="logs/*.log"/>
</rhq:fileset>
</rhq:ignore>
</rhq:deployment-unit>
</rhq:bundle>
This only applies to upgrading a bundle, meaning after the initial deployment.
The last elements set the Ant tasks to run before or after deploying the content, as identified initially in the <rhq:deployment-unit> arguments. Most common Ant tasks are supported (as described in Section 27.5.4, “Using Ant Tasks”). This uses a preinstall task to print which directory the bundle is being deployed to and whether the operation was successful. The postinstall task prints a message when the deployment is complete.
<target name="main" />
<target name="preinstall">
<echo>Deploying Test Bundle v2.4 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 v2.4 to ${rhq.deploy.dir}.</echo>
<property name="postinstallTargetExecuted" value="true"/>
</target>
</project>
Section 27.5.8, “A Reference of JBoss ON Ant Recipe Elements” lists the different JBoss ON elements in the Ant recipe file. For information on standard Ant tasks, see the Apache Ant documentation.
27.5.4. Using Ant Tasks
An Ant bundle distribution file is just an Ant recipe and its associated files. As Section 27.5.3, “Breakdown of an Ant Recipe” shows, the Ant recipe is the expected
deploy.xml file with some JBoss ON-specific elements. An Ant bundle distribution file supports more complex Ant configuration, including Ant tasks and targets.
27.5.4.1. Supported Ant Tasks
Any standard Ant task can be run as part of the Ant bundle provisioning (with the exception of <antcall> and <macrodef>). This includes common commands like echo, mkdir, and touch — whatever is required to deploy the content fully.
Important
The <antcall> element cannot be used with the Ant recipe. <antcall> calls a target within the
deploy.xml file, which loops back to the file, which calls the <antcall> task again, which calls the deploy.xml file again. This creates an infinite loop.
To perform the same operations that would be done with <antcall>, use the <ant> task to reference a separate XML file which contains the custom Ant targets. This is described in Section 27.5.4.3, “Calling Ant Targets”.
Important
The macrodef call, and therefore macro definitions, are not supported with Ant bundles.
Along with the standard Ant tasks, Ant bundle recipes can use optional Ant tasks:
- See Section 27.5.2, “Additional Ant References” for links to comprehensive Ant-Contrib resources.
27.5.4.2. Using Default, Pre-Install, and Post-Install Targets
As with other Ant tasks, the <project> allows a default target, which is required by the provisioning system. This is a no-op because the Ant recipe mainly defines the metadata for and identifies files used by the provisioning process. Other operations aren't necessary. This target is required by Ant, even though it is a no-op target. Use pre- and post-install targets to perform tasks with the bundle before and after it is unpacked.
For example:
<target name="main" />
Additionally, JBoss ON provisioning tasks can define both pre- and post-install targets. This allows custom tasks, like simple progress messages or setting properties.
27.5.4.3. Calling Ant Targets
As mentioned in Section 27.5.4.1, “Supported Ant Tasks”, using <antcall> does not work in an Ant bundle recipe; it self-referentially calls the <rhq:bundle> task in an infinite loop. However, it is possible to process tasks that are outside the default target. This can be done using pre- and post install targets (Section 27.5.4.2, “Using Default, Pre-Install, and Post-Install Targets”).
- In
deploy.xmlfor the Ant recipe, add a <rhq:deployment-unit> element which identifies the Ant target.<rhq:deployment-unit name="jar" postinstallTarget="myExampleCall">
- Then, define the target.
<target name="myExampleCall"> <ant antfile="another.xml" target="doSomething"> <property name="param1" value="111"></property> </ant> </target> - Create a separate
another.xmlfile in the same directory as thedeploy.xmlfile. This file contains the Ant task.<project name="another" default="main"> <target name="doSomething"> <echo>inside doSomething. param1=${param1}</echo> </target> </project>
27.5.5. Using Templatized Configuration Files
A bundle can contain configuration files for an application. These configuration files can use hard-coded values or they can use tokens that are filled in (automatically or with user-supplied values) when the bundle is actually deployed.
Note
For a user-defined token to be realized, it must be referenced in the recipe so that the bundle deployment wizard will prompt for the value, using the <rhq:input-property> key in the Ant recipe. For examples, see Section 27.5.8.2, “rhq:input-property” and Section 27.5.3, “Breakdown of an Ant Recipe”.
User-defined tokens can be any property; the values are supplied through the provisioning UI and inserted into the templatized configuration file.
The token key is a simple attribute-value assertion, with the input_field as the element in the UI and the property being the value in the configuration file. The property of user-defined tokens must contain only alphanumeric characters, an underscore (_), or a period (.); no other characters are allowed.
input_field=@@property@@
For example, to set a port number token in a configuration file, define the property:
port=@@listener.port@@
The user-defined token then must be noted in the recipe, so that the provisioning process knows to realize the phrase. To configure a property in an Ant recipe, add a <rhq:input-property> key in the Ant XML file.
For example:
<rhq:input-property
name="listener.port"
... />
The provisioning wizard prompts for a value for all of the user-defined tokens referenced in the recipe.
Figure 27.3. Port Token During Provisioning
Along with user-defined variables that can be specified in the recipe file, there are variables that are made implicitly available to recipes. These tokens can be used in a templatized file as a user-defined variable without having to define the token template in the recipe itself.
| Token | Description |
|---|---|
| rhq.deploy.dir | The directory location where the bundle will be installed. |
| rhq.deploy.id | A unique ID assigned to the specific bundle deployment. |
| rhq.deploy.name | The name of the bundle deployment. |
Additionally, some tokens can be realized by the provisioning process pulling information from the local system. These values, listed in Table 27.3, “System-Defined Tokens”, are taken either from the Java API or from Java system properties. They can be inserted directly in the templatized configuration file without having to put a corresponding entry in the recipe. For example:
@@rhq.system.hostname@@
| Token Name | Taken From... | Java API |
|---|---|---|
| rhq.system.hostname | Java API | SystemInfo.getHostname() |
| rhq.system.os.name | Java API | SystemInfo.getOperatingSystemName() |
| rhq.system.os.version | Java API | SystemInfo.getOperatingSystemVersion() |
| rhq.system.os.type | Java API | SystemInfo.getOperatingSystemType().toString() |
| rhq.system.architecture | Java API | SystemInfo.getSystemArchitecture() |
| rhq.system.cpu.count | Java API | SystemInfo.getNumberOfCpus() |
| rhq.system.interfaces.java.address | Java API | InetAddress.getByName(SystemInfo.getHostname()).getHostAddress() |
| rhq.system.interfaces.network_adapter_name.mac | Java API | NetworkAdapterInfo.getMacAddress() |
| rhq.system.interfaces.network_adapter_name.type | Java API | NetworkAdapterInfo.getType() |
| rhq.system.interfaces.network_adapter_name.flags | Java API | NetworkAdapterInfo.getAllFlags() |
| rhq.system.interfaces.network_adapter_name.address | Java API | NetworkAdapterInfo.getUnicastAddresses().get(0).getHostAddress() |
| rhq.system.interfaces.network_adapter_name.multicast.address | Java API | NetworkAdapterInfo.getMulticastAddresses().get(0).getHostAddress() |
| rhq.system.sysprop.java.io.tmpdir | Java system property | |
| rhq.system.sysprop.file.separator | Java system property | |
| rhq.system.sysprop.line.separator | Java system property | |
| rhq.system.sysprop.path.separator | Java system property | |
| rhq.system.sysprop.java.home | Java system property | |
| rhq.system.sysprop.java.version | Java system property | |
| rhq.system.sysprop.user.timezone | Java system property | |
| rhq.system.sysprop.user.region | Java system property | |
| rhq.system.sysprop.user.country | Java system property | |
| rhq.system.sysprop.user.language | Java system property |
27.5.6. Processing JBoss ON Properties and Ant Properties
As described in Section 27.5.5, “Using Templatized Configuration Files”, JBoss ON defines its own recipe properties, in <rhq:input-property> tags. These are input properties; at the time the bundle is deployed, the server parses the configuration in the file and prompts for any input properties. It then deploys the bundle using those user-defined values.
JBoss ON also supports using Ant <property> tags — but in a more limited way than a normal Ant build system.
Deploying a bundle has two steps: creating the bundle entity in the JBoss ON server and then installing that bundle on a managed resource, through the JBoss ON agent. Unlike a normal Ant build system, these steps happen on different machines.
It is critical to understand that the systems — and, therefore, the environments — where these two build steps are run are different. It affects the overall processing workflow for bundles and limits the Ant build process.
When a bundle is uploaded (created), the JBoss ON server checks the Ant recipe to see what bundle files are required. This means that it processes the <rhq:bundle> element for the archive file <rhq:archive> and any other associated content.
At this point, the server has not processed any bundle configuration or evaluated any properties, either JBoss ON input properties or Ant proprties. This is because many JBoss ON input properties are environment-specific, and attempting to expand those properties would result in different bundle configuration (such as Java version, operating system version, and even filesystem location) than what is required when the bundle is ultimately deployed on the managed platform.
By moving all of the Ant processsing over to the JBoss ON agent platform, the way that Ant properties are processed is different than on a typical Ant build server. In a typical Ant implementation, Ant properties can be used to templatize core elements of the recipe, such as filenames and version numbers. However, since the Ant script is not run on the JBoss ON server, any templatized properties cannot (yet) be expanded. This means that required configuration — such as the archive name, other files, names, and version numbers — cannot be templatized in either Ant properties or JBoss ON input properties. They must be set explicitly or left empty so that the server prompts for the value. Another way of saying it is that properties used when the script is actually run are ignored, while required properties require a defined value up front. A templatized value at this point in the configuration is treated as a literal value.
27.5.7. Limits and Considerations for Ant Recipes
27.5.7.1. Unsupported Ant Tasks
As stated in Section 27.5.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
27.5.7.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"/>
27.5.7.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 27.1.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:
- 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.)
- 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: compliance, <rhq:ignore>, and cleanDeployment.
compliance
All of the information about the application being deployed is defined in the <rhq:deployment-unit> element in a bundle recipe. The compliance attribute on the <rhq:deployment-unit> element sets how the provisioning process should handle existing files in the deployment directory.
The default value is compliance=full 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 filesAndDirectories, 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 compliance 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.
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 compliance option is set to filesAndDirectories 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.
Clean Deployment
Both compliance 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 compliance and <rhq:ignore> settings in the recipe.
27.5.8. A Reference of JBoss ON Ant Recipe Elements
27.5.8.1. rhq:bundle
Contains the definition for the main JBoss ON-related Ant task that is required for any Ant bundle recipe. This element defines basic information about the bundle and is the parent element for all of the specific details about what is in the bundle and how it should be provisioned.
| Attribute | Description | Optional or Required |
|---|---|---|
| name | The name given to the bundle. | Required |
| version | The version string for this specific bundle. Bundles can have the same name, but each bundle of that name must have a unique version string. These version strings normally conform to an OSGi style of versioning, such as 1.0 or 1.2.FINAL. | Required |
| description | A readable description of this specific bundle version. | Optional |
Example 27.2. rhq:bundle
<rhq:bundle name="example" version="1.0" description="an example bundle">
27.5.8.2. rhq:input-property
Adds a property to the bundle task that defines a template token that must have its value supplied by a user at the time the bundle is deployed. This is similar to standard Ant properties.
Note
All of the system properties and Ant-specific tokens listed in Section 27.5.5, “Using Templatized Configuration Files” are available to be used as templatized tokens in bundle configuration without having to set a <rhq:input-property> definition.
All input properties set some parameter that must have its value defined by a user when the bundle is provisioned on a resource, and the fields to enter those values are automatically generated in the JBoss ON UI bundle deployment wizard.
| Attribute | Description | Optional or Required |
|---|---|---|
| name | The name of the user-defined property. Within the recipe, this property can be referred to by this name, in the format ${property_name}. | Required |
| description | A readable description of the property. This is the text string displayed in the JBoss ON bundle UI when the bundle is deployed. | Required |
| type |
Sets the syntax accepted for the user-defined value. There are several different options:
| Required |
| required | Sets whether the property is required or optional for configuration. The default value is false, which means the property is optional. If this argument isn't given, then it is assumed that the property is optional. | Optional |
| defaultValue | Gives a value for the property to use if the user does not define a value when the bundle is deployed. | Optional |
Example 27.3. rhq:input-property
<rhq:input-property
name="listener.port"
description="This is where the product will listen for incoming messages"
required="true"
defaultValue="8080"
type="integer"/>27.5.8.3. rhq:deployment-unit
Defines the bundle content — such as applications or configuration files — being deployed by the bundle. A deployment unit can be simple text files, archives, or a full software product, including an application server, web server, or database. A deployment unit can have multiple archive and configuration files associated with it.
Only a single deployment unit is provisioned at a time by the provisioning process, so there can be only one <rhq:deployment-unit> element in a bundle recipe.
| Attribute | Description | Optional or Required |
|---|---|---|
| name | The name of the application. | Required |
| compliance |
Sets whether JBoss ON should manage all files in the top root directory (deployment directory) where the bundle is deployed. If filesAndDirectories, any unrelated files found in the top deployment directory (files not included in the bundle) are ignored and will not be overwritten or removed when future bundle updates are deployed. The default is full, which means that the provisioning process manages all files and directories and removes or overwrites anything not in the bundle.
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.
| Optional |
| preinstallTarget | An Ant target that is invoked before the deployment unit is installed. | Optional |
| postinstallTarget | An Ant target that is invoked after the deployment unit is installed. | Optional |
Example 27.4. rhq:deployment-unit
<rhq:deployment-unit name="appserver" preinstallTarget="preinstall" postinstallTarget="postinstall">
27.5.8.4. rhq:archive
Defines any archive file that is associated with deploying the application. An archive can be a ZIP or JAR file. A bundle doesn't require an archive file, so this element is optional.
Note
This must have an explicit value for the name. It will not process an Ant ${} property definition.
| Attribute | Description | Optional or Required |
|---|---|---|
| name |
The filename of the archive file to include in the bundle.
Important
If the archive file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the name must contain the relative path to the location of the archive file in the ZIP file.
| Required |
| exploded | Sets whether the archive's contents will be extracted and stored into the bundle destination directory (true) or whether to store the files in the same relative directory as is given in the name attribute (false). If the files are exploded, they are extracted starting in the deployment directory. Post-install targets can be used to move files after they have been extracted. | Optional |
| destinationDir | The directory where this archive or its exploded results are to be copied. If this is a relative path, it is relative to the deployment directory given by the user when the bundle is deployed. If this is an absolute path, that is the location on the filesystem where the file will be copied. This attribute sets the directory for the file to be copied to. The actual file name is set in the name attribute. | Optional |
Example 27.5. rhq:archive
<rhq:archive name="file.zip">
<rhq:replace>
<rhq:fileset>
<include name="**/*.properties"/>
</rhq:fileset>
</rhq:replace>
</rhq:archive>See Also
27.5.8.5. rhq:url-archive
Defines remote archive to use, which is accessed through the given URL. This is similar to
rhq:archive except that the server accesses the archive over the network rather than including the archive directly in the bundle distribution file.
| Attribute | Description | Optional or Required |
|---|---|---|
| url |
Gives the URL to the location of the archive file. The archive is downloaded and installed in the deployment directory.
Note
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.
| Required |
| 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.
Note
If the files are exploded, they are extracted starting in the deployment directory. Post-install targets can be used to move files after they have been extracted.
| Optional |
| destinationDir | The directory where this archive or its exploded results are to be copied. If this is a relative path, it is relative to the deployment directory given by the user when the bundle is deployed. If this is an absolute path, that is the location on the filesystem where the file will be copied. This attribute sets the directory for the file to be copied to. The actual file name is set in the name attribute. | Optional |
Example 27.6. rhq:url-archive
<rhq:url-archive url="http://server.example.com/apps/files/archive.zip">
<rhq:replace>
<rhq:fileset>
<include name="**/*.properties"/>
</rhq:fileset>
</rhq:replace>
</rhq:url-archive>See Also
27.5.8.6. rhq:file
Contains the information to identify and process configuration files for the application which have token values that must be realized. Normally, configuration files are copied directly from the bundle package into the deployment directory. The <rhq:file> element calls out files that require processing before they should be copied to the destination. The attributes on the <rhq:file> element set the name of the raw file in the bundle distribution ZIP file and the name of the target file that it should be copied to.
Raw files can be included with the archive files that contain properties or configuration for the application. These configuration files can be templatized with user-defined or system-defined tokens, like those listed in Section 27.5.5, “Using Templatized Configuration Files”. Any templatized files that are included in the bundle distribution file that are templatized must be listed in the Ant recipe so that they are processed and the tokens are realized.
Note
This must have an explicit value for the name. It will not process an Ant ${} property definition.
| Attribute | Description | Optional or Required |
|---|---|---|
| name |
The name of the raw configuration file.
Important
If the configuration file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the name must contain the relative path to the location of the file within the ZIP file.
| Required |
| destinationFile |
The full path and filename for the file on the destination resource. Relative paths must be relative to the final deployment directory (defined in the
rhq.deploy.dir parameter when the bundle is deployed). It is also possible to use absolute paths, as long as both the directory and the filename are specified.
Note
If the destinationDir attribute is used, the destinationFile attribute cannot be used.
| Required, unless destinationDir is used |
| destinationDir |
The directory where this file is to be copied. If this is a relative path, it is relative to the deployment directory given by the user when the bundle is deployed. If this is an absolute path, that is the location on the filesystem where the file will be copied.
This attribute sets the directory for the file to be copied to. The actual file name is set in the
name attribute.
If the
destinationFile attribute is used, the destinationDir attribute cannot be used.
| Required, unless destinationFile is used |
| replace | Indicates whether the file is templatized and requires additional processing to realize the token values. | Required |
Example 27.7. rhq:file
<rhq:file name="test-v2.properties" destinationFile="subdir/test.properties" replace="true"/>
If neither the
destinationDir nor the destinationFile attribute is used, then the raw file is placed in the same location under the deployment directory as its location in the bundle distribution.
27.5.8.7. rhq:url-file
As with
rhq:file, contains the information to identify and process configuration files for the application which have token values that must be realized. This option specifies a remote file which is downloaded from the given URL, rather than being included in the bundle archive.
| Attribute | Description | Optional or Required |
|---|---|---|
| url |
Gives the URL to the templatized file. The file is downloaded and installed in the deployment directory.
Note
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.
| Required |
| destinationFile |
The full path and filename for the file on the destination resource. Relative paths must be relative to the final deployment directory (defined in the
rhq.deploy.dir parameter when the bundle is deployed). It is also possible to use absolute paths, as long as both the directory and the filename are specified.
Note
If the destinationDir attribute is used, the destinationFile attribute cannot be used.
This attribute must give both the path name and the file name.
| Required, unless destinationDir is used |
| destinationDir |
The directory where this file is to be copied. If this is a relative path, it is relative to the deployment directory given by the user when the bundle is deployed. If this is an absolute path, that is the location on the filesystem where the file will be copied.
This attribute sets the directory for the file to be copied to. The actual file name is set in the
name attribute.
If the
destinationFile attribute is used, the destinationDir attribute cannot be used.
| Required, unless destinationFile is used |
| replace | Indicates whether the file is templatized and requires additional processing to realize the token values. | Required |
Example 27.8. rhq:url-file
<rhq:url-file url="http://server.example.com/apps/files/test.conf" destinationFile="subdir/test.properties" replace="true"/>
If neither the
destinationDir nor the destinationFile attribute is used, then the raw file is placed in the same location under the deployment directory as its location in the bundle distribution.
27.5.8.8. rhq:property
Note
The <rhq:property> task is an extension of the standard Ant 1.8 <property> task and supports all of it's properties. For more information on the standard Ant 1.8 <property> task, see the official Ant 1.8 documentation.
Bundle recipes may be further parameterized by using either the standard Ant 1.8 <property> tasks or by using the <rhq:property> tasks.
Properties loaded using <rhq:property file=""> assume the path to the file is relative to the working directory where the bundle is unzipped prior to deployment. This path is undefined so users should not rely on this value. It is recommended to use known absolute paths on the target machines or relative paths that do not try to access parent directories (using '..').
Files referenced by <property> or <rhq:property> are not deployed by default but are required bundle files. For files to be both used to load properties and deployed to the destination, they must also be referenced using the <rhq:file> task in the deployment unit.
In addition to the existing Ant attributes for <property>, the <rhq:property> task also supports the <command>relativeToDeployDir</command> attribute.
| Attribute | Description | Optional or Required |
|---|---|---|
|
relativeToDeployDir
|
Only applicable if the file attribute is also used and is a relative path.
Defaults to false.
If true, the file is resolved against the deploy directory of the bundle instead of the working directory from which the bundle deployment is executed.
|
Optional
|
The relativeToDeployDir attribute allows relative file references in the file attribute to resolve relative to the target deploy directory of the bundle instead of the working directory.
27.5.8.9. rhq:audit
Sets custom audit trail messages to use during the provisioning process. This is useful with complex recipes that perform some additional custom tasks. As the tasks are processed, the
rhq:audit configuration sends information to the server about the additional processing steps and their results.
| Attribute | Description | Optional or Required |
|---|---|---|
| status | The status of the processing. The possible values are SUCCESS, WARN, and FAILURE. The default is SUCCESS. | Optional |
| action | The name of the processing step. | Required |
| info | A short summary of what the action is doing, such as the name of the target of the action or an affected filename. | Optional |
| message | A brief text string which provides additional information about the action. | Optional |
Example 27.9. rhq:audit
<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>27.5.8.10. rhq:replace
Lists templatized files, in children <rhq:fileset> elements, contained in the archive which need to have token values realized when the archive is deployed.
Any file which uses a token that must be replaced with a real value is a templatized file. When the provisioning process runs, the token value is substituted with the defined value. This element lists all of the files which are templatized; the only files which are processed by the provisioning system for token substitution are the ones listed in the <rhq:replace> element.
Example 27.10. Example
<rhq:archive name="file.zip">
<rhq:replace>
<rhq:fileset>
<include name="**/*.properties"/>
</rhq:fileset>
</rhq:replace>
</rhq:archive>27.5.8.11. rhq:ignore
Lists files in the deployment directory which should not be deleted when a new bundle is deployed. This only applies to upgrade operations, not to the initial deployment of a bundle.
Once an application is deployed, instance-specific files — like data files or logs — can be created and should be retained if the application is ever upgraded. This element, much like <rhq:replace>, contains a list of files or directories in the instance to save.
Note
If a file is ignored in the recipe, then the file is not deleted when the bundle is deployed. However, if a file of the same name exists in the bundle, then the local file is overwritten.
Do not attempt to ignore files that are packaged in the bundle. Only files generated by the applications, such as log and data files, should be ignored by the provisioning process since they should be preserved for the upgraded instance.
Important
It is possible to deploy one bundle to a subdirectory of another bundle (such as Bundle A is deployed to
/opt/myapp and Bundle B to /opt/myapp/webapp1).
In that case, set the recipe in Bundle A to ignore the directory to which Bundle B will be deployed. This prevents updates or reversions for Bundle A from overwriting the configuration from Bundle B.
Example 27.11. rhq:ignore
<rhq:ignore>
<rhq:fileset>
<include name="logs/*.log"/>
</rhq:fileset>
</rhq:ignore>27.5.8.12. rhq:fileset
Provides a list of files.
Two JBoss ON elements — <rhq:replace> and <rhq:ignore> — define file lists in either the archive file or the deployment directory. This element contains the list of files.
| Child Element | Description |
|---|---|
| <include name=filename /> | The filename of the file. For <rhq:replace>, this is a file within the archive (JAR or ZIP) file which is templatized and must have its token values realized. For <rhq:ignore>, this is a file in the application's deployment directory which should be ignored and preserved when the bundle is upgraded. |
Example 27.12. rhq:fileset
<rhq:replace>
<rhq:fileset>
<include name="**/*.properties"/>
</rhq:fileset>
</rhq:replace>27.5.8.13. rhq:system-service
Points to a script file to launch as part of the provisioning process. This is usually an init file or similar file that can be used by the deployed application to set the application up as a system service.
| Attribute | Description | Optional or Required |
|---|---|---|
| name | The name of the script. | Required |
| scriptFile | The filename of the script. If the script file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the scriptFile must contain the relative path to the location of the file in the ZIP file. | Required |
| configFile | The name of any configuration or properties file used by the script. If the configuration file is packaged with the Ant recipe file inside the bundle distribution ZIP file, then the configFile must contain the relative path to the location of the file in the ZIP file. | Optional |
| overwriteScript | Sets whether to overwrite any existing init file to configure the application as a system service. | Optional |
| startLevels | Sets the run level for the application service. | Optional |
| startPriority | Sets the start order or priority for the application service. | Optional |
| stopPriority | Sets the stop order or priority for the application service. | Optional |
Example 27.13. rhq:system-service
<rhq:system-service name="example-bundle-init" scriptFile="example-init-script"
configFile="example-init-config" overwriteScript="true"
startLevels="3,4,5" startPriority="80" stopPriority="20"/>27.5.8.14. rhq:handover
Bundle content handover's purpose is to delegate to the bundle target's resource component, some or all of the deployment content included in the bundle archive. The name "handover" stems from the idea that the bundle content is actually "handed over" to a resource component.
The intention of handover is to enable the bundle's target component to participate in the bundle deployment. This is specifically useful in instances where resources do not rely on filesystem changes to deploy content. Handover allows bundle content to be sent to a target resource component along with a defined action and action parameters.
For example, consider deploying an application to a JBoss Enterprise Application Platform 6 domain. The agent plug-in already knows how to communicate with all its resources, upload content to those resources, as well as deploy it. The handover bundle recipe enables JBoss ON to send the JBoss Enterprise Application Platform 6 JBoss ON plug-in an application and handover an action to be performed with that application (e.g. deploy this web application to a specific server group within a domain).
Since the JBoss ON JBoss Enterprise Application Platform 6 plug-in could do many things when content is handed over (e.g. deploy the bundle as an application, run it as a CLI script, etc), an action and action parameters are required when using handover.
Note
Review the plug-in documentation to see a list of actions and associated parameters it supports. For more information on the JBoss Enterprise Application Platform 6 plug-in, users can navigate to Administration > Configuration > Agent Plugins > JBoss Application Server 7.x. Additionally, please note that not all bundle target resources may support bundle content handover.
Important
Bundle permissions should be carefully considered during setup. Content handed over using the the bundle content handover could compromise your system. For example, if the JBoss ON JBoss Enterprise Application Platform 6 plug-in has been configured with credentials of a super user, the bundle developer can execute a JBoss Enterprise Application Platform 6 CLI script with extended permissions. It is recommended that the bundle content and recipes get reviewed before they are uploaded to the JBoss ON server.
The JBoss ON bundle subsystem is filesystem-oriented so there is no actual "uninstall" mechanism. When a revert is done, JBoss ON will actually store backed up files and re-invoke the previous bundle recipe.
With respect to purging, JBoss ON will only clean out the bundle destination directory in accordance with deployment unit's compliance attribute value.
As a result, content which is handed over cannot be reverted or purged in a traditional sense. JBoss ON can only "move forward", it cannot undeploy content to go backwards.
| Attribute | Description | Optional or Required |
|---|---|---|
| action | The name of the action the target resource component should execute. | Required |
| failonerror | Whether the ANT recipe build should fail if the target resource component reports a failure. true or false. Defaults to true. | Optional |
The following tags may have a (unique) <rhq:handover> child tag:
- <rhq:file>
- <rhq:url-file>
- <rhq:archive>
- <rhq:url-archive>
If two pieces of content in the bundle need to be handed over to the target resource component, they will be sent in the same order as declared in the bundle recipe.
Example 27.14. rhq:handover
<rhq:file name="prepareDatasource.cli" replace="true">
<rhq:handover action="execute-script" failonerror="false"/>
</rhq:file>
<rhq:archive name="website.war">
<rhq:handover action="deployment">
<rhq:handover-param name="runtimeName" value="${myapp.runtime.name}"/>
<rhq:handover-param name="serverGroup" value="${server.group}"/>
</rhq:handover>
</rhq:archive>
The
prepareDatasource.cli file content will always be handed over to the target resource component before the website.war archive content.
See Also
27.5.8.15. rhq:handover-param
| Attribute | Description | Optional or Required |
|---|---|---|
| name | The name of the parameter | Required |
| value | The name of the value. | Required |
The <rhq:handover> element may have zero, one or more
rhq:handover-param child tags.
Example 27.15. rhq:handover-param
<rhq:file name="prepareDatasource.cli" replace="true">
<rhq:handover action="execute-script" failonerror="false"/>
</rhq:file>
<rhq:archive name="website.war">
<rhq:handover action="deployment">
<rhq:handover-param name="runtimeName" value="${myapp.runtime.name}"/>
<rhq:handover-param name="serverGroup" value="${server.group}"/>
</rhq:handover>
</rhq:archive>
