The "File Template" bundle type provides very basic support for ad-hoc provisioning. File template bundles can support simple provisioning use-cases for pushing out content and/or running scripts on remote machines.
File Template recipes are simple in nature, thus the recipe syntax is easy to understand and quick to learn. But its simplicity is also the reason why you lose the ability to do some advanced provisioning tasks that most production use-cases require (such as upgrading and rolling back content). Because of these limitations and restrictions imposed by File Template recipe, File Template bundles are rarely used in production - they are more for testing and development; though some simple tasks can be performed using File Template bundles and thus they may be useful in some limited capacity within a production environment.
You can package together all your bundle's files and its recipe in a bundle distribution file. The bundle distribution file must be either a .zip or .jar file. The recipe must be called "deploy.txt" and it must be found in the top root directory of the distribution file.
The file template recipe is more of a script than a recipe - in other words, the recipe is executed line-by-line, with each line's command executed before the next line is processed (note that blank lines and lines that start with "#" (i.e. comments) are ignored).
Here is an example File Template Recipe:
# Recipe for my test application bundle --name "My Little App" --version=2.0.1 --description "Just a small app with some content" configdef --name=listener.port --default=8080 file --source configuration.txt --destination "@@rhq.deploy.dir@@/config/settings.properties" realize --file "@@rhq.deploy.dir@@/config/settings.properties"
Each line in a file template recipe is called a "recipe command". All commands use the "getopt" syntax which means each argument can be specified in short form (e.g. "-n") or long form ("--name"). When using the long form, you can optionally specify an equals sign between the argument and its value (e.g. --name=JBossAS and --name JBossAS are equivalent). If an argument's value contains spaces, you must wrap the value in quotes (e.g. --name "My Custom JBoss AS").
Each line in the recipe that specifies a command may be "templatized". This means each line can specify tokens of the form @@replacement.variable.name@@. Each replacement variable will have a value assigned to it by the user when the bundle is scheduled to be provisioned.
In addition to the standard built-in replacement variables, all file template recipes can use the following replacement variables:
rhq.deploy.dir : the location where the deployment is to be installed
rhq.deploy.id : the unique identifier for the deployment
rhq.deploy.name : the name given to the deployment
Each line in the recipe can be one of the following commands.
This command is required and is usually the first command in the recipe. It describes the bundle version that this recipe is associated with.
|
Argument |
Short Form |
Required? |
Description |
|
--name |
-n |
yes |
name of the bundle |
|
--version |
-v |
yes |
bundle's version string. Should follow an OSGi-like version format such as "1.0.0" or "2.1.GA" |
|
--description |
-d |
no |
Describes the bundle version. This can be anything useful to a user. |
Example:
bundle --name "ABC Banking App" --version=2.0.1 --description "Introduces 128-bit encryption support"
Each command in a file template recipe may be "templatized", meaning they can specify tokens (e.g. @@name@@) that need replacement values defined by the user. In the same manner, any bundle file associated with a file template bundle can also be templatized, meaning the content of a bundle file will contain tokens such as @@name@@. In this case, you must inform the file template parser what tokens it can expect to find in these templatized files so it knows what values it needs to ask the user for. The "configdef" command is the way you do this (the name "configdef" refers to the "configuration definition", where the "configuration" is another name for the set of replacement values used by the template engine to replace the tokens).
|
Argument |
Short Form |
Required? |
Description |
|
--name |
-n |
yes |
name of a replacement variable found in one or more templatized files |
|
--default |
-d |
no |
the default value for the replacement variable |
Example:
configdef --name=listener.port --default=8080
Each file template bundle (like all bundles) can have one or more bundle files associated with it. If a bundle file is an archive file (that is, something like a zip or tar file), you use the "deploy" command to unpack the archive file into a specific location on the remote file system. The deploy command's arguments tell it both the name of the archive file and the directory where the archive should be unpacked on the remote platform. Note that the built-in token @@rhq.deploy.dir@@ is typically used as the value for the directory argument since you usually want to unpack an archive into the location where the user told RHQ to provision the bundle.
A bundle file's extension will tell RHQ how the archive is to be unpacked. The supported extensions are: .zip, .tar, .tgz, .tar.gz, .tar.bz2, .tbz2, .tbz and .rpm. Depending on the type of archive, RHQ will issue a specific unpack command on the remote platform machine. These unpack commands for each supported archive type are:
.zip : unzip -o file -d directory
.tar : tar xf file -C directory
.tar.bz2, .tbz2, .tbz : tar xfj file -C directory
.tar.gz, .tgz : tar xfz file -C directory
.rpm : rpm -i file --prefix directory
|
Argument |
Short Form |
Required? |
Description |
|
--file |
-f |
yes |
name of the archive file |
|
--directory |
-d |
yes |
location where the archive file is to be unpacked |
Example:
deploy --file=product.zip --directory "@@rhq.deploy.dir@@"
A bundle file may not be an archive - it could be just a raw file that simply needs to be copied to a remote platform. In this case, you use the "file" command to tell RHQ the name of the source file as well as the destination name of the file as it should appear on the remote file system. Using this allows you to copy the file to a specific remote location and allows you to rename the file as it appears in the remote file system.
|
Argument |
Short Form |
Required? |
Description |
|
--source |
-s |
yes |
name of the original bundle file |
|
--destination |
-d |
yes |
path of the bundle file as it should appear on the remote file system - this must be a filename, in other words, not only does it include the directory where the file should be located, but this value also defines the name of the file, which may or may not be the same as the source filename |
Example:
file --source configuration.txt --destination "@@rhq.deploy.dir@@/config/settings.properties"
This command will pass the named file through the template engine, realizing it such that its replacement variables are replaced with their real values as defined by the user at the time the bundle was scheduled to be provisioned, or as defined by the agent at the time the file is realized (in the case when the token is one of the built-ins such as @@rhq.system.hostname@@).
Recipes will specify this realize command after the file has been copied onto the remote file system, via either the "file" or "deploy" recipe command.
|
Argument |
Short Form |
Required? |
Description |
|
--file |
-f |
yes |
The name of the bundle file that is templatized and needs to be passed through the template engine so its tokens can be replaced with their real values. Note that this argument value must be a absolute path as found on the remote file system. |
Example:
realize --file "@@rhq.deploy.dir@@/config/settings.properties"
A bundle file may itself be a script. If you want your recipe to execute your bundle file script, use this script command.
|
Argument |
Short Form |
Required? |
Description |
|
<filename> |
N/A |
yes |
The first argument is assumed to be the name of the bundle script file |
|
* |
N/A |
no |
All following arguments will be passed as-is as arguments to the bundle script file |
Example (this example assumes there is a bundle file called "my-script" and it assumes that script accepts the "--print" argument followed by more arguments):
script my-script --print "hello world"
This is similar to the "script" command, except the "command" command assumes the given executable already exists on the remote machine (i.e. the executable is not a bundle file associated with the bundle). You can use this to run operating system commands that you know already exist on the remote machine.
|
Argument |
Short Form |
Required? |
Description |
|
<executable> |
N/A |
yes |
The first argument is assumed to be the name of a valid executable file |
|
* |
N/A |
no |
All following arguments will be passed as-is as arguments to executable file |
Example:
command dos2unix /var/logs/my-app.log