This document contains all the information about the new Wildfly provisioning system. It is very much a work in progress at the moment.

Overview

Previously Wildfly was build using a collection of ant scripts that assembled a server for a set of resources. The server was assembled in a monolithic manner, and projects that build on Wildfly copied these scripts and adapted them to their purposes.

Now that the Wildfly code base has been split up this process is no longer workable, and as a result we have created some tooling to deal with this. Central to this tooling is the idea of a feature pack. A feature pack is basically a collection of metadata that contains enough information to build a server. In particular it contains:

• module.xml files
• static content such as scripts
• versioning information for all artefacts
• configuration file templates

It does not contain the maven artefacts themselves (although in future we may optionally allow this). This means feature packs are very small, especially when compared to a complete Wildfly instance.

At the moment the primary use of these feature packs is for the Wildfly build process, however it has become apparent that this approach gives us lots of flexibility and there are lots of possibilities we can explore. Some of the more interesting ones include provisioning 'thin' servers that run using the jars in a local maven repository, provisioning cut down servers that only include specific functionality and overriding the versions of specific artefacts as part of the provisioning servers, to allow community users easy access to the latest versions of particular components.

It is also apparent that there is a lot of overlay between feature packs and the existing patching system. Ideally these two concepts will be unified.

Use cases

This section contains all the possible use cases we have thought of for the provisioning tool. Just because something is listed here does not mean it will get implemented. This is just listing all the possibilities.

• Assemble a Wildfly server as part of the Wildfly build process

This is the most basic requirement. Now that the Wildfly code base has been split up we need a way to assemble the pieces into a complete server. At the moment this takes the form of a maven plugin.

• Assemble a Wildfly server from the command line

This will allow an administrator to assemble a server using a command line tool.

• Deploy a maven artefact to an assembled server

This will allow a server configuration file to contain a list of artefacts to deploy, and these will be deployed as part of the provisioning process

• Customise the configuration of an assembled server

This will allow server configuration to be changed (e.g. adding datasources and security domains). Combined with the ability to deploy artefacts at assemble time this will allow a production ready server to be assembled and put into use immediately.

• Install an additional feature pack on an existing server

This will allow additional features to be installed on top of an existing instance, for example installing Capedwarf on top of an existing Wildfly instance. This will also be the supported mechanism for users to install custom modules into a Wildfly instance. The use can package these modules into a feature pack using our tooling, and then install these feature packs directly into the server.

• Provision a server with a custom version of a particular artefact

For example a community user may wish to provision a server with the most recent version of Weld or Undertow.

• Provision a cut down version of a server

E.g. a user or 3rd party integrator may want a server with only Undertow and JAX-RS. The provisioning tool should allow the installation of only specific subsystems from a feature pack, while making sure that all required dependencies are also installed.

• Upgrade an existing installation

For example when a new point release of WF come out a user may wish to update the server in place. This is quite a complex topic, and will be covered in depth later on.

• Remotely provision a server

A user may wish to remotely provision a server. The two main use cases that I can see here are:

1. Provisioning to a clean server, in this case the provisioning tool could connect via SSH, and provision remotely over SSH.
2. Provision to a server with a running host controller. In this case we may want to allow the host controller to provision a new server (possibly a different version), and control the lifecycle of the provisioned server, although if we go down this route there are a lot of issues that would need to be resolved.

• Install or customise modules

A user may wish to install new static modules, or in some cases customise an existing module. To accomplish this we will provide tooling to make it easy to create a feature pack and install it into an existing server. Feature packs will become our standard supported way of installing 3rd party modules.

• Customise the server configuration from a feature pack

A feature mack may need to make changes to subsystems provided by other feature packs in order to enable its functionality. For example a monitoring feature pack may need to install a data source. (I'm not 100% sure if this is required).

• Enable functionality by capability name

For example a feature pack may require JTS, and should be able to specify that is requires JTS, and the provisioning tool will enable the capability in the config.

• Ability to provision both 'thin' and 'fat' servers

Thin servers use an <artifact> reference in modules.xml that references the jar in the maven repository. Fat servers are a traditional server with artefacts copied into the modules directory.

• Allow a feature pack to depend on part of another feature pack

For example the keycloak feature pack might depend on a module from the WF full distro, but should still be installable on web. It should be possible for keycloak just declare a dependency on part of the full feature pack.

Proposed Implementation In Wildfly 9

This section contains details about the scope and implementation to be included in Wildfly 9.

Feature packs

The Wildfly build process consists of first generating a Wildfly 'feature pack', which is a lightweight artefact that contains a complete description of a set of server features. These feature packs can be provisioned into full servers, or used as dependencies for other feature packs. Feature packs are created by the build tooling. Feature packs contain the following:

• Unresolved module definitions: the server modules directory, however without specific versions present in the module.xml file. This allows for a specific artifact version to be overridden at build time.
• Artefact versioning information: The default versions for all artefacts that are present in the modules directory
• Additional content: this includes things such as scripts

Server Provisioning

Provisioning is controller via an XML file that describes the server to be assembled. This includes information such as:

• The feature packs to assemble it from
• Filtering information from these feature packs (see below)
• If the server is to be a 'thin' or 'fat' server (thin servers run from jars in the maven repository, and as such can use less disk space, especially if the maven repository is shared)
• Artifact version overides, which allow a server to override the version of specific artifacts. For example this could allow a community user to use a newer version of Resteasy with some bug fixes
• Deployments to install in the server. This will consist of a GAV of a deployment that will be downloaded and installed in the server
• Configuration changes to make to the server. This will most likely consist of a list of CLI commands to execute on the provisioned server

Config Files

Config files are assembled as follows:

• A feature pack can specify a new config file (e.g. standalone.xml) or domain profile. Domain profiles can be linked to a config file name to ensure they stay in sync. When specifying the feature pack it is also possible to specify suppliments that should be applied to the included subsystems.
• A feature pack then specifies the subsystems that are present in this config file
• A feature pack can specify that it builds on a dependent feature pack's config file. When this happens all subsystem configs included in the feature pack are merged into the base config. This feature pack can also add more suppliments to the config.
• A feature pack can also add new config files based on an existing config. This new file can include additional suppliments and subsystems, as well as excluding subsystems from the base config.
• It is expected that in the normal case all config files will inherit from standalone.xml, which means that adding a file to standalone.xml will include it in all config file. This allows things such as keyclock to add themselves to all config files without needing to know the full contents of such a file.
• TODO: how are subsystems referenced, and how does this fit in with filtering? I would expect to just reference them by config file name, subsystem name does not really work, as we have multiple (example) configs for some subsystems.

Subsystem filtering

When provisioning a server it will be possible to filter the subsystems that are installed. When listing a feature pack it will be possible to list the names of the subsystems that should be installed. These subsystems will have their transitive dependencies analysed and only these subsystems and required dependencies will be installed. For instance this will allow a user to provision cut down Wildfly instances that meet their requirements without any additional features they do not need. Subsystem filtering affects config file generation, as filtered subsystem will not be added to the config.

TODO: figure out how this interacts with capabilities and requirements. This also requires some changes to the existing feature pack layout.

Provisioning tools

The main provisioning tool is implemented as a library to make it easy to create new front ends. The following front ends are planned to be ready for the Wildfly 9 timeframe:

• Maven plugin: This is necessary just to build Wildfly and downstream projects. It is also useful as a developer tool, as it means that a pre configured Wildfly instance can be provisioned for testing.
• JBoss Forge Plugin : This will be the CLI version of the provisioning tool for now. This has a number of advantages:
  • Less development time, as all the plumbing has been done
  • Easy to support config file generation, to allow a server to be build from CLI commands, as forge is designed for content generation. Forge also has a plugin repository that may be useful to allow easy discovery of feature packs.

Eventually we may also want:

• JBoss CLI support (this is less useful than it sounds, as it runs into the chicken and egg problem, i.e. to provision a server, first you need a server with the CLI)
• a standalone provisioning CLI

Proposed Implementation In Wildfly 10

Wildfly 10 will expand upon the above with the following features, all of which need a lot more thought.

Ability to install additional features into an existing installation

This will probably be done via some kind of command line tool, similar to yum etc (e.g. ./wildfly install drools ).

Ability to upgrade an existing installation

When a new version of a feature pack is released it should be possible to upgrade an existing installation. This will probably be done by re-provisioning the modules directory (with rollback provided by re-provisioning the older version).