As an user, I want to build and push an application image from the wildfly-maven-plugin

In  maven cloud user-experience

Overview

The wildfly-maven-plugin allows to provision and package WildFly server with the maven’s deployment. An important use case for this feature is to deploy the application on the cloud.

With the use of the wildfly-maven-plugin, we have generalized the packaging of WildFly to run it on the Cloud. Once the application (WildFly + user deployments) has been created in the target/server directory, the steps to create an application image are always the same for the users:

  • Determine which WildFly runtime images to use (at the moment, we provide images for OpenJDK 11 and 17)

  • Generate a Dockerfile that is always the same

  • Run the docker build …​ command

  • (optional) log in to a container registry and run docker push …​

These steps could be performed automatically by the wildfly-maven-plugin so that the outcome of the mvn package would directly be an applicaiton image ready to be deployed on the Cloud.

Issue Metadata

Issue

Dev Contacts

QE Contacts

Testing By

  • Engineering

Affected Projects or Components

Other Interested Projects

Relevant Installation Types

  • Maven-controlled standalone server

Requirements

  • Add a new image goal to the plugin that extends the package goal with additional capabilities:

  • Build a container image (known as the application image) containing the WildFly server provisioned by the wildfly-maven-plugin (with the deployment in it) based on the WildFly runtime images

  • (optional) login to a container registry

  • (optional) push the application image to the container registry

All commands related to the application are delegated to the docker binary that must be present on the host executing the mvn command.

The new image goal extends the package goal. We can assume that before the image goal is executed, the application (WildFly + user deployments) has been properly created in the target/server directory (or the specified directory if customized).

The behaviour of the image goal is controlled by additional configuration element (in addition to the ones required by the package goal). They are all included in the <configuration><image>` XML element of the plugin.

  • build - Whether the application image should be built (default is true)

  • push - Whether the application image should be pushed (default is false)

  • jdk - Determine which WildFly Runtime image to use so that the application runs with the specified JDK. The default is 11`. Accepted values are 11, 17.

  • group - The group part of the name of the application image.

  • name - The name part of the application image. If not set, the value of the artifactId (in lower case) is used.

  • tag - The tag part of the application image (default is latest).

  • registry - If set, the registry is added to the application name. If the image is pushed and the registry is not set, it defaults to "docker.io" to login to the registry

  • user - The user name to login to the container registry.

  • password - The user password to login to the container registry.

Hard Requirements

Nice-to-Have Requirements

  • It should be possible to configure the binary used to manipulate the application image so that docker (by default) or podman could be used. Until them aliasing podman to docker prior to the Maven execution is a workaroun.

Backwards Compatibility

There is no backwards compatibility issue. The existing provision and package goals are not affected by the new image goal.

Security Considerations

It is possible to specify the user credentials to log in to the container registry before being able to push the application image.

The password field MUST never be printed out during the execution of the plugin. The pom.xml SHOULD not contain an explicit value of the password. Instead the user is advised to use a property to specify it on the command line or through other means. If possible, the login to the container registry should be done prior to the execution of the Maven commands (so that no credentials would ne neeeded at all).

Test Plan

Example

As an/example, if I am developing a JAX-RS application in the Maven module my-app, the configuration to create an application image to run this application on WildFly 26.1.2.Final with OpenJDK 17 would be

<plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <configuration>
        <feature-packs>
            <feature-pack>
                <location>org.wildfly:wildfly-galleon-pack:26.1.2.Final</location>
            </feature-pack>
            <feature-pack>
                 <location>org.wildfly.cloud:wildfly-cloud-galleon-pack:1.0.1.Final</location>
             </feature-pack>
        </feature-packs>
        <layers>
            <layer>cloud-server</layer>
        </layers>
        <runtime-name>ROOT.war</runtime-name>

        <!-- ==== image configuration ==== -->
        <image>
            <jdk>17</jdk>
            <registry>quay.io</registry>
            <group>${user.name}</group>
            <push>true</push>
        </image>
        <!-- ==== end of image configuration ==== -->

    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>image</goal>
            </goals>
        </execution>
    </executions>
</plugin>

With that configuration, the outcome of the execution of mvn package is the creation of an application image named quay.io/jmesnil/my-app:latest that is pushed to Quay.io. The application will run on OpenJDK 17.

I can then run this application image with docker run -p8080:8080 quay.io/jmesnil/my-app:latest or use it to deploy my applicaiton on any container-based cloud providers.

Community Documentation

This new image goal will be documented in the WildFly Maven Plugin Documentation.

An example to use this goal will be added in the similar fashion to the existing 'package' example.

The WildFly Quickstarts could be enhanced to leverage this new image goal.

Release Note Content

The wildfly-maven-plugin now provides an image goal to build (and push) an application image containing the WildFly server and the user deployment created by Maven. With that goal, the outcome of the mvn package application is container image ready to be deployed on any cloud providers to run the user application on WildFly.