Red Hat Training

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

27.2. Extended Example: Common Provisioning Use Cases (and How They Handle Files)

Section 27.1, “An Introduction to Provisioning Content Bundles” describes the different elements in the bundles and provisioning system — but what is provisioning really for? There are a handful of common use cases that illustrate how provisioning works in a real environment.
  • Deploying a full application server
  • Deploying a web application to an application server
  • Deploying configuration files
Important
One thing to remember for all of this is that bundles take content from point A (JBoss ON) and send it to point B (the destination). This is not a simple copy operation (Section 27.1.3, “File Handling During Provisioning”). The provisioning system, by default, makes the destination, point B, match exactly how the directory in the bundle is laid out. This means adding or editing files, creating or deleting subdirectories, and deleting any existing content from the destination.
That concept of managing the layout and content of the destination influences the ways and effects of deploying content.
Report a bug

27.2.1. Deploying A Full Application Server

Bundle Details

This is the core use for the provisioning system, deploying an entire application server. This bundle contains the complete configuration stack for a server like JBoss EAP (or Tomcat or Apache). The bundle contains all of the files used by the application — the JAR and configuration files and scripts for the EAP server, and all EAR or WAR web applications that are to be deployed on that EPA instance. All of the application server and web app files and directories are zipped into an archive, with the deploy.xml which defines the Ant recipe.

File Handling Details

Because this is a complete application server, it will be deployed into its own, new (or empty) directory, such as /opt/my-application. That directory will be dedicated to the application server, so it will be entirely managed by the bundle.

There is an attribute in the recipe called compliance which tells the bundle system how to deploy content. For deploying a full application server, the bundle system should have complete control over the directory, so compliance is set to full. This means:
  • Only files and subdirectories in the bundle distribution file will be in the root directory.
  • Any existing files or subdirectories will be deleted.
  • If files or subdirectories are added to the root directory, then they will be deleted when the bundle is updated or redeployed, unless those files are explicitly ignored (a setting in the recipe).
Report a bug

27.2.2. Deploying A Web Application

Instead of deploying a full application server, it is possible to deploy a web application to the application server. However, this takes an understanding of the directory layout of both the application server and the web application.
For example, this is the deployment directory path for the application server: 
/opt/my-application/deploy
The goal is to deploy a new web app, myApp1.war to the deploy/ directory. 
/opt/my-application/deploy/myapp1.war/

Bundle Details

In this case, the bundle file contains only the WAR file itself and the deploy.xml recipe.

File Handling Details

Unlike the application server, when deploying the web app, there are or could be other web apps also in the deploy/ directory. The bundle system, then, should not manage the root directory, meaning existing or new files should be allowed within the root directory even if they are not included in the bundle.

The intent here is not to manage all of the content in the directory but to add to that content by deploying the WAR file. So, the recipe should specify compliance=fileAndDirectories, which tells the provisioning system to leave alone any existing files in the directory that are outside the bundle.
Note
Setting compliance=filesAndDirectories only preserves files outside the bundle deployment. If the bundle directory is deploy/myApp/, then any files in deploy/myApp/ or subdirectories like deploy/myApp/WEB-INF/ will be overwritten or removed when the bundle is deployed. The subdirectories defined in the bundle distribution are still entirely managed by the bundle system.
One other consideration is that only one bundle can be deployed to a root directory. If there are multiple web applications to be deployed to the same EAP server and all of them will be managed by the provisioning system, then there are two options:
  • Include all of the web applications in the same bundle distribution. For example, to deploy myApp1.war and myApp2.war to the deploy/ directory, both WAR files can be included in the same bundle and deployed to deploy/myApp1.war/ and deploy/myApp2.war/ simultaneously.
  • It may not be possible to roll all of the web apps into the same bundle. Instead of using deploy/ as the root directory, there could be two different bundle distributions that use a subdirectory as the root directory. For example, the first web app could use deploy/myApp1/ so that the final deployment is deploy/myApp1/myApp1.war/, while the second app uses deploy/myApp2/, resulting in deploy/myApp2/myApp2.war/.
    This allows the two web applications to be deployed, updated, and reverted independently of each other.
Report a bug

27.2.3. Deploying Configuration Files

Another common scenario is deploying configuration files to an application server (or even another resource, like a platform), using bundles.
This is very similar to deploying a web application. If JBoss ON deploys a bundle to a given directory, it expects to manage the content within that directory and all content within any subdirectories defined in the bundle. With configuration files, it is critical that you understand and include all of the configuration files in the bundle or critical files could be removed.
For example, an administrator creates a bundle to deploy two configuration files:
  • New login configuration, in server/default/conf/login-config/xml
  • New JMX console users, in server/default/conf/props/jmx-console.properties
The root directory is the conf/ directory for the application server.

Bundle Details

The bundle must contain all of the files that are expected to be in the conf/login-config/ and conf/props/ subdirectories, not just the two new files that the administrator wants to use. Additionally, the compliance parameter in the recipe must be set to filesAndDirectories so that all of the existing configuration files in the root directory, conf/, are preserved.

File Handling Details

As with deploying a web app, the intent is to add new content, not to replace existing content. Setting compliance=filesAndDirectories only preserves files outside the bundle deployment. However, because there are two subdirectories defined in the bundle, JBoss ON will manage all of the content in those subdirectories. This means:

  • The recipe has to have compliance=filesAndDirectories set for the bundle to preserve the other files in the conf/ root directory.
  • Any files in the subdirectories of the bundle — conf/log-config/ and conf/props/ — will be overwritten when the bundle is deployed. The provisioning process can ignore files in the root directory, but it always manages (meaning, updates, adds, or deletes) files in any subdirectories identified in the bundle so that they match the content of the bundle.
  • Existing files in the conf/log-config/ and conf/props/ subdirectories must be included in the bundle distribution.
Note
There is an alternative to including all of the configuration files in the bundle distribution.
The bundle, containing only the new files, could be deployed to a separate directory, like /opt/bundle/. Then, an Ant post-install task can be defined in the recipe that copies the configuration files from the root directory into the application server's conf/ directory.
Report a bug