[COMMUNITY]  WildFly provisioning to support WildFly stability

In  wf-galleon

Overview

WildFly 31 introduced the notion of stability level. Galleon, WildFly Galleon plugins and provisioning tooling must be evolved to support this notion. This proposal describes how stability is handled by the WildFly provisioning.

Issue Metadata

Issue

  • WFLY-19021 - WildFly provisioning to support WildFly stability

  • WFCORE-6668 - Ensure read-feature-description results contain stability as reported by associated description for use by WildFly Glow

  • WFGP-265 - Support setting a minimum stability level when provisioning

  • WFGP-264 - Support setting a minimum stability level when building a feature pack

  • GAL-357 - Support for feature/package stability

  • Issue 570 - Support in prospero for stability level

Stability Level

  • Experimental

  • Preview

  • Community

  • default

Dev Contacts

QE Contacts

  • N/A.

Testing By

  • Engineering

  • QE

Affected Projects or Components

Relevant Installation Types

  • Traditional standalone server (unzipped or provisioned by Galleon)

  • Managed domain

  • OpenShift s2i

  • Bootable jar

Requirements

Stability becomes a Galleon notion that applies to feature-pack, feature/feature_param and package. There is a 1 to 1 mapping with WildFly stability. The stability levels are: default >`community` > preview > experimental

Galleon feature-pack descriptor is extended with 2 new attributes:

  • config-stability-level: The stability to be used when provisioning configurations.

  • package-stability-level: The stability to be used when provisioning packages.

These attributes are set when building Galleon feature-packs and used by Galleon runtime at provisioning time.

Requirements at feature-pack build time

feature-pack minimum stability level

A minimum stability level can be set at feature-pack build time. If no stability level is specified, the default level is used.

Stability level is set thanks to a new option of the WildFly Galleon Plugins Maven plugin: <minimum-stability-level>default|community|preview|experimental</minimum-stability-level>

Feature-specs and packages at a lower stability level than is specified will not be included in the feature pack.

feature-pack provisioning stability level

This level is used as the default stability level to be used when provisioning server configurations and packages. If no stability level is specified, the default level is used for both configs and packages stability levels. It is set thanks to a new option of the WildFly Galleon Plugins Maven plugin: <stability-level>default|community|preview|experimental</stability-level>.

If one wants to have different values for configs and packages, then <config-stability-level> and <package-stability-level> are to be used instead of <stability-level>. The use case for using config-stability-level and package-stability-level as an alternative to stability-level is when the user wishes to generates configurations with features at a given stability level while allowing provisioning of packages at a lower level. The presence of the lower stability level packages allows subsequent update of the configuration to enable lower stability features.

feature-pack provisioning config stability level

This level is used as the default stability level to be used when provisioning server configurations. If no stability level is specified at feature-pack build time, the default level is used. Stability level is set thanks to a new option of the WildFly Galleon Plugins Maven plugin: <config-stability-level>default|community|preview|experimental</config-stability-level>

This level can be overridden at provisioning time with the Galleon option <config-stability-level>

feature-pack provisioning package stability level

This level is used as the default stability level to be used when provisioning server packages (e.g.: JBoss Modules modules). If no stability level is specified, the default level is used. Stability level is set thanks to a new option of the WildFly Galleon Plugins Maven plugin: <package-stability-level>default|community|preview|experimental</package-stability-level>

This level can be overridden at provisioning time with the Galleon option <package-stability-level>

  • Configuring <stability-level> and <config|package-stability-level> options in the same plugin execution is not supported and will lead to a failure.

  • If the specified stability level is not enabled by the level specified by the 'minimum-stability-level' setting, the build of the feature pack will fail.

  • This stability level is not the minimal stability level at which a feature-pack can be provisioned. At provisioning time, a lower stability level for both configs and packages can be specified.

JBoss Modules modules stability level

A stability level can be set in module.xml thanks to the property jboss.stability. Possible value being default|community|preview|experimental. If no stability is specified, default is assumed.

Implementation notes

At build time, the minimum stability level is used in 2 cases:

  • To start the embedded server that generates the Galleon features at the correct stability level (allowing the features to be discovered in the server).

  • To filter-out packages at a stability level lower than the minimum-stability level. Such packages are not packaged inside the feature-pack.

Stability levels for WildFly feature-packs

Expected minimum stability levels for WildFly feature-packs:

  • wildfly-ee-galleon-pack: experimental

  • wildfly-galleon-pack: experimental

  • wildfly-preview-feature-pack: experimental

  • wildfly-core: experimental

Expected config stability levels for WildFly feature-packs:

  • wildfly-ee-galleon-pack: community

  • wildfly-galleon-pack: community

  • wildfly-preview-feature-pack: preview

  • wildfly-core: community

Expected package stability levels for WildFly feature-packs:

  • wildfly-ee-galleon-pack: experimental

  • wildfly-galleon-pack: experimental

  • wildfly-preview-feature-pack: experimental

  • wildfly-core: experimental

Requirements at provisioning time

Provisioning time follows some rules to properly handle stability and avoid features/packages of wrong stability being provisioned.

  • The feature-pack contained config stability level is used to constrain the set of provisioned features. Any features at a lower stability level contained in the feature-pack (if any), are not provisioned.

  • The feature-pack contained package stability level is used to constrain the set of provisioned packages. Any packages at a lower stability level contained in the feature-pack (if any), are not provisioned.

  • By default, the config and package stability levels of each feature-pack are used when provisioning its own content.

  • Each feature-pack present in the provisioning configuration can have a different config stability level. The config stability of each feature-pack applies to its own content and doesn’t leak into other feature-packs.

  • Each feature-pack present in the provisioning configuration can have a different package stability level. The package stability of each feature-pack applies to its own content and doesn’t leak into other feature-packs.

  • A user can specify a config stability level, by means of the config-stability-level Galleon option. NB: This option can’t be set when stability-level is set. This stability level is used to enable the stability level of all features present in configurations generated during provisioning.

  • A user can specify a package stability level, by means of the package-stability-level Galleon option. This stability level is used to set the stability level of all provisioned packages. NB: This option can’t be set when stability-level is set.

  • A user can specify a stability level for both configs and packages, by means of the stability-level Galleon option. This option is a convenience allowing to set both the config and package stability level using a single option. It can’t be set when config-stability-level or package-stability-level are in use.

  • At provisioning time, usage of <stability-level> and <config|package-stability-level> options in the same provisioning execution is not supported and would lead to a failure.

For example, a provisioning configuration containing 3 feature-packs:

  • A, config and package stability default, minimum stability default

  • B, config and package stability community, minimum stability community

  • C, config and package stability experimental, minimum stability experimental

If no stability level is specified:

  • default features/packages of A are provisioned

  • community and default features/packages of B are provisioned

  • experimental, preview, community and default features/packages of C are provisioned

If the config stability level default is specified:

  • default features and packages of A are provisioned

  • default features + community and default packages of B are provisioned

  • default features + experimental and preview and community and default packages of C are provisioned

If the package stability level experimental is specified:

  • default features/packages of A are provisioned

  • community and default features/packages of B are provisioned

  • experimental, preview, community and default features/packages of C are provisioned

Example of a feature-pack containing packages and features at a lower stability level than its default stability levels:

  • The feature-pack A contains features at default, community and preview level.

  • The feature-pack A contains packages at default, community and preview level.

  • The default package stability level is community.

  • The default community stability level is community.

  • The minimum stability level is set to preview.

If no stability level is specified:

  • default and community features/packages of A are provisioned

If the package and config stability level preview is specified:

  • default, community and preview features/packages of A are provisioned

Lowest config stability level needed by WildFly Galleon Plugins

At provisioning time, when WildFly Galleon plugin generates the server configurations, a WildFly embedded server is started. This server is started with a stability level computed in the following way:

  • If a config stability level has been specified by the user, this level is used.

  • If no config stability level has been specified, the lowest config stability level of all feature-packs present in the provisioning is used.

Provisioning tooling requirement

The following Galleon based tooling should let users specify the config-stability-level and package-stability-level options:

  • Galleon CLI and Maven plugin

  • WildFly Maven Plugin

  • WildFly Bootable JAR Maven Plugin

  • WildFly Glow

  • In addition, for WildFly Glow, information about the features/packages that would be not provisioned for a given stability level is displayed to the user.

Nice-to-Have Requirements

  • Support for stability in Prospero provisioning tooling.

Non-Requirements

  • Recording and utilizing stability information in Galleon configuration elements at a higher granularity level than a feature-spec or package (i.e. configs, layers, feature-groups).

  • If a provisioning plan (i.e. a provisioning.xml or other provisioning tooling configuration that instructs the tooling about what to provision) involves configs, layers of feature-groups that reference features or packages that are not available at the stability level in effect, the result is not specified. That is:

    • Always rejecting provisioning such a server is not required.

    • Always provisioning a working server is not required.

    • Best practice for feature pack authors is to not include features or packages at a lower stability level in configs, layers or feature-groups that are expected to be used in servers provisioned at a higher stability level. However it is not the responsibility of the Galleon tooling to enforce this best practice or to guarantee a particular result if best practice is not followed.

Future Works

  • An attempt could be made to identify, at feature-pack build time, the Galleon content that references packages below the minimal stability level (so not included) and abort.

Backwards Compatibility

  • Galleon must be backward compatible with older WildFly releases not supporting stability.

Test Plan

  • Add new unit tests to Galleon project.

  • Add new tests to the Galleon Plugins project.

    • Define 4 subsystems to cover the 4 known stability levels.

    • Define a set of packages, modules and features at the 4 known stability levels in a common set.

    • Defines 4 feature-packs for a given minimum stability level. Each feature-pack includes resources from the common set, so filtering is applied when building the feature-pack to exclude content at a lower stability level.

    • Test that the feature-pack content must not contain any content at a lower stability level.

    • Test that the provisioned content must be compliant with the provisioning time stability level (if provided, otherwise must be compliant with the feature-pack defined stability level(s)).

Community Documentation