New WildFly S2I image

In  cloud openshift user-experience

Overview

Today, we are relying on the WildFly s2i builder image to build a WildFly application image. There is a strong coupling inside this image that implies releasing a new image for each new WildFly release. This approach is not flexible. We should be able to build an application image for any WildFly release (even for a locally built SNAPSHOT) without having to wait for the WildFly s2i builder image to be deployed.

In addition, the WildFly server located inside the builder image, enforces a set of configuration API (a set of environment variables) and bash launch scripts. At startup time, a complex CLI script generation that impacts the server startup time is mandatorily executed. Having this level of configurability should be a user choice and not be enforced by the WildFly s2i image.

To solve these pain points, we are removing the server and its configuration aspects from the image. In order for the launch scripts and server configuration adjustments to be offered, we are introducing a new cloud Galleon feature-pack to be provisioned in combination with WildFly Galleon feature-pack.

The WildFly s2i image becomes a generic image allowing to properly install and execute any provisioned WildFly server. As a developer one should be able in max 2 steps to deploy to the cloud an app. Same for WildFly developers that should deploy a locally built WildFly SNAPSHOT in one step (as done with WildFly Bootable JAR today).

Responsabilities of the WildFly s2i builder image

  • Provide JDK and maven tooling

  • Provides automatic and configurable JVM configuration at server startup (same as the openjdk builder image)

  • Understand the execution constraints for the server and adapt the server launch processing (e.g.: start the server in a way that would allow a server killed by POD to terminate properly).

  • Provides nice defaults for the minimal set of server configuration items (e.g.: jboss.node.name derived from hostname, public interface address, management address)

  • Install the server in the image.

  • Support s2i build from source and binary.

  • Handle incremental build.

  • Built application Image must be runnable but also usable inside a docker chained build to construct a final application image (that doesn’t contain any build tooling).

Responsabilities of the WildFly runtime image

  • Provides Java JDK. We are including the JDK in order for the image to contain JDK debug tooling.

  • Provides automatic and configurable JVM configuration at server startup (same as the openjdk builder image)

  • Understand the execution constraints for the server and adapt the server launch processing (e.g.: start the server in a way that would allow a server killed by POD to terminate properly).

  • Provides nice defaults for the minimal set of server configuration items (e.g.: jboss.node.name derived from hostname, public interface address, management address)

A Maven plugin to provision and configure WildFly

The steps that have been removed from the WildFly s2i build processing are now aggregated inside a single point of configuration inside the WildFly Maven plugin that is evolved with WFMP-138. The plugin handles Galleon provisioning, user CLI scripts execution, ability to enrich server content and application(s) deployment.

This plugin used in conjunction with this new WildFly s2i image is all what is needed to offer a flexible experience. We gain the flexibility to provision/configure a WildFly instance to answer specific requirements instead of relying on a fixed set of features packaged inside a WildFly s2i builder image.

N.B.: The image is not strongly coupled with this Maven plugin. For source build, any plugin that outputs a server installation can be used during S2I source build. For binary build, any server installation can be the source of binary build.

Legacy s2i workflow

The image still supports s2i build that don’t require the usage of the WildFly Maven plugin. This support is deprecated and could be removed in a future version of the images.

Some GALLEON_XXX env variables have to be set to enable the legacy s2i workflow. When the legacy workflow is enabled, the server is first provisioned then the application deployment built during s2i is copied to the provisioned server deployments directory.

Galleon provisioning based on env variables

  • GALLEON_PROVISION_FEATURE_PACKS=<comma separated list of Galleon feature-packs GAV>. For example: org.wildfly:wildfly-galleon-pack:25.0.0.Final,org.wildfly.cloud:wildfly-cloud-galleon-pack:1.0.0.Final. This option is mandatory if GALLEON_USE_LOCAL_FILE is not set.

  • GALLEON_PROVISION_LAYERS=<comma separated list of layers>. List of Galleon layers to provision. This option is mandatory if GALLEON_USE_LOCAL_FILE is not set.

  • GALLEON_USE_LOCAL_FILE=true. Advertise to the s2i build that a Galleon provisioning file has to be looked-up in the application project (by default <app basedir>/galleon/provisioning.xml). Is false by default.

  • GALLEON_DIR=<path to galleon directory> . Used to locate the directory relative to the application project directory that contains galleon custom content (provisioning.xml and settings.xml files). By default the directory galleon is used.

WildFly cloud Galleon feature-pack

All the existing launch scripts and configuration changes that were present in the WildFly s2i image are moved inside a cloud Galleon feature-pack. This feature-pack is to be provisioned with WildFly Galleon feature-pack.

NB: The usage of this feature-pack is not mandatory and WildFly feature-pack can be used alone to provision a server runnable inside the builder or runtime images.

Feature-pack source repository is : github.com/wildfly-extras/wildfly-cloud-galleon-pack.

The Maven coordinates of this feature-pack are org.wildfly.cloud:wildfly-cloud-galleon-pack:<version>.

OIDC support

The keycloak Galleon layer is not present in the cloud feature-pack. The WildFly elytron-oidc-client has to be used to provision the OIDC subsystem. OIDC support in a cloud context is specified in the WFLY-15421 proposal.

Issue Metadata

Issue

  • Evolve WildFly Maven plugin with Galleon provisioning - WFLY-14934

  • OIDC Support for the cloud: WFLY-15421

Dev Contacts

QE Contacts

  • TBD

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

Implementation notes

In WildFly s2i repo, a new git branch v2 will be used to implement the feature and release the first versions of the images. The master will be used to build and release the current WildFly S2I and runtime images that will become deprecated. Once the deprecated images are no more released, a legacy branch will be created, the v2 branch will be merged into master. At this point, no more "legacy" content will be released.

Hard Requirements

WildFly s2i builder image

Building

  • The builder image is built from ubi8-minimal image.

  • It adds on top JDK11 and maven s2i tooling.

  • It contains the user jboss.

  • It is deployed on quay.io: quay.io/wildfly/wildfly-s2i-jdk11

  • Has a versioning independent from WildFly versioning

  • Has support for binary and source build.

  • Expects a server to be provisioned in <target dir>/server by default. Directory name relative to the target directory can be configured with S2I_SERVER_DIR=<relative path in target directory> env variable.

Running

  • Image produced with this builder image is runnable.

  • Image execution can be configured with Java related environment variables. JVM API

  • The image entry-point offers the following features:

    • Discover the WildFly launcher script to be called: standalone.sh, standalone-cloud.sh or openshift-launch.sh. N.B.: In case of openshift-launch.sh (legacy cloud entry point), no configuration is applied. Configuration of the server is delegated to the openshift-launch.sh script that handles it all. The env variable SERVER_LAUNCH_SCRIPT_OVERRIDE can be used to override the server launch script file name. The file must be located in $JBOSS_HOME/bin directory.

    • WARNING. This needs to be reviewed at the light of future evolutions in the transaction subsystem. Computes the value of the jboss.node.name system property (required by transactions). By default a truncated to 23 characters name based on the hostname is computed. This can be overridden by using the JBOSS_NODE_NAME env variable.

    • Computes the JVM options to be conveyed to the server

    • Appends the content of JAVA_OPTS_APPEND env variable to JAVA_OPTS.

    • If the env variable CLI_LAUNCH_SCRIPT=<cli script path> has been set, the referenced CLI script is executed during boot. The file can be an absolute path or a path relative to JBOSS_HOME directory.

    • Handles POD termination with CLI shutdown. Can be disabled with CLI_GRACEFUL_SHUTDOWN=true env variable. N.B.: the PORT_OFFSET env variable is to be used to convey a port offset, This allows the CLI shutdown logic to retrieve the port offset when interacting with the server.

    • Set default value for management (0.0.0.0) and public (value of hostname -i command) interfaces. The default values can be specified with SERVER_PUBLIC_BIND_ADDRESS and SERVER_MANAGEMENT_BIND_ADDRESS.

    • Enables the server statistics. Can be overridden with SERVER_ENABLE_STATISTICS=false.

    • Calls the server launch script passing it the SERVER_ARGS env variable that can contain extra arguments to provide to the server.

The API to configure the server launch (for both the builder and runtime images entry-point) is defined in this cekit module

WildFly runtime image

  • The runtime image is built from ubi8-minimal image.

  • It adds on top JDK11.

  • Has the same versioning that the S2I Builder image.

  • It is deployed on quay.io: quay.io/wildfly/wildfly-runtime-jdk11

  • It contains the user jboss

  • Image produced from this runtime image is runnable.

  • It contains the same entry-point present in the builder image.

  • Examples of Docker file to install a server inside the runtime image:

Local WildFly installation copied to the image

FROM quay.io/wildfly/wildfly-runtime-jdk11:latest
COPY --chown=jboss:root vanilla-wildfly $JBOSS_HOME
RUN chmod -R ug+rwX $JBOSS_HOME

Chained build from builder image

FROM quay.io/wildfly/wildfly-runtime-jdk11:latest
COPY --from=builder --chown=jboss:root /opt/wildfly $JBOSS_HOME
RUN chmod -R ug+rwX $JBOSS_HOME

Nice-to-Have Requirements

  • None.

Non-Requirements

  • None.

Test Plan

  • Add new Behave tests that would use WildFly Maven plugin and WildFly. This would cover the entrypoint configurability.

  • Port existing behave tests to the new design by using the wildfly-cloud-galleon-pack.

  • Add new Openshift QE tests.

Community Documentation

  • A complete rework of the community documentation is required.

Release Note Content

Yes.