Appendix C. Fabric8 Maven plugin
With the help of fabric8-maven-plugin, you can deploy your Java applications to OpenShift. It provides tight integration with Maven and benefits from the build configuration already provided. This plug-in focuses on the following tasks:
- Building Docker-formatted images and,
- Creating OpenShift resource descriptors
It can be configured very flexibly and supports multiple configuration models for creating:
- A Zero-Config setup, which allows for a quick ramp-up with some opinionated defaults. Or for more advanced requirements,
-
An XML configuration, which provides additional configuration options that can be added to the
pom.xmlfile.
C.1. Building images
The fabric8:build goal is used for creating Docker-formatted images containing an application. It is easy to include build artifacts and their dependencies in these images. This plugin uses the assembly descriptor format from the maven-assembly-plugin to specify the content which will be added to the image.
Fuse on OpenShift supports only the OpenShift s2i build strategy, not the docker build strategy.
C.2. Kubernetes and OpenShift resources
Kubernetes and OpenShift resource descriptors can be created with fabric8:resource. These files are packaged within the Maven artifacts and can be deployed to a running orchestration platform with fabric8:apply.
Configuration
There are four levels of configuration:
-
Zero-Config mode helps to make some very useful decisions based on what is present in the
pom.xmlfile like, what base image to use or which ports to expose. It is used for starting up things and for keeping quickstart applications small and tidy. - XML plugin configuration mode is similar to what docker-maven-plugin provides. It allows for type safe configuration with IDE support, but only a subset of possible resource descriptor features is provided.
-
Kubernetes and OpenShift resource fragments are user provided YAML files that can be enriched by the plugin. This allows expert users to use plain configuration file with all their capabilities, but also to add project specific build information and avoid boilerplate code. *Docker Compose is used to bring up docker compose deployments on a OpenShift cluster. This requires minimum to no knowledge of OpenShift deployment process. For more information about the Configuration, see
https://maven.fabric8.io/#configuration.
C.3. Installing the plugin
The Fabric8 Maven plugin is available under the Maven central repository and can be connected to pre- and post-integration phases as shown below.
Procedure
-
To connect the Fabric8 Maven plugin to pre- and post-integration phases, add the following to
settings.xmlfile.
<plugin>
<groupId>org.jboss.redhat-fuse</groupId>
<artifactId>fabric8-maven-plugin</artifactId>
<version>${fuse.version}</version>
<configuration>
....
<images>
<!-- A single's image configuration -->
<image>
...
<build>
....
</build>
</image>
....
</images>
</configuration>
<!-- Connect fabric8:resource and fabric8:build to lifecycle phases -->
<executions>
<execution>
<id>fabric8</id>
<goals>
<goal>resource</goal>
<goal>build</goal>
</goals>
</execution>
</executions>
</plugin>C.4. Understanding Fabric8 Maven plugin goals
The Fabric8 Maven Plugin supports a rich set of goals for providing a smooth Java developer experience. You can categorize these goals as follows:
- Build goals are used to create and manage the Kubernetes and OpenShift build artifacts like Docker-formatted images or S2I builds.
- Development goals are used in deploying resource descriptors to the development cluster. Also, helps you to manage the lifecycle of the development cluster.
C.4.1. Understanding build and development goals
The following are the goals supported by the Fabric8 Maven plugin in the Red Hat Fabric Integration Services product:
| Goal | Description |
|---|---|
| fabric8:build |
Build images. Note that Fuse on OpenShift supports only the OpenShift |
| fabric8:resource | Create Kubernetes or OpenShift resource descriptors |
| fabric8:apply | Apply resources to a running cluster |
| fabric8:resource-apply |
Run |
| Goal | Description |
|---|---|
| fabric8:run |
Run a complete development workflow cycle |
| fabric8:deploy |
Deploy resources descriptors to a cluster after creating them and building the app. Same as |
| fabric8:undeploy | Undeploy and remove resources descriptors from a cluster. |
| fabric8:start | Start the application which has been deployed previously |
| fabric8:stop | Stop the application which has been deployed previously |
| fabric8:log | Show the logs of the running application |
| fabric8:debug | Enable remote debugging |
| fabric8:watch | Monitor the project workspace for changes and automatically trigger redeployment of application. |
C.4.2. Setting environmental variable
You can set one or more environment variables by adding the env parameter in the XML configuration. For example,
Example
<configuration>
<resources>
<env>
<JAVA_OPTIONS>-Dmy.custom=option</JAVA_OPTIONS>
<MY_VAR>value</MY_VAR>
</env>
</resources>
</configuration>
C.4.3. Resource validation configuration
The fabric8:resource goal validates the generated resource descriptors using API specification of Kubernetes and OpenShift.
| Configuration | Description | Default |
|---|---|---|
|
| If value is set to true then resource validation is skipped. This is useful when the resource validation is failing for some reason but you still want to continue the deployment. | false |
|
| If value is set to true then any validation error will block the plugin execution. A warning will be displayed otherwise. | false |
|
| If value is set to true then fabric8-maven-plugin would switch to Deployments rather than DeploymentConfig when not using ImageStreams on OpenShift. | false |
|
|
If value is set to true then it would set the container image reference to "", this is done to handle weird behavior of OpenShift 3.7 in which subsequent rollouts lead to | false |
For more information about the Fabric8 Maven plugin goals, see https://maven.fabric8.io/#goals.
C.5. Generators
The Fabric8 Maven plugin provides generator components, which have the capability to build images automatically for specific kinds of application. Following generator types are supported in Fuse on OpenShift:
Depending on certain characteristics of the application project, the generator framework auto-detects what type of build is required and invokes the appropriate generator component.
The open source community version of the Fabric8 Maven plug-in provides additional generator types, but these are not supported in the Fuse on OpenShift product.
C.5.1. Zero configuration
Generators do not require any configuration. They are enabled by default and run automatically with default settings when the Fabric8 Maven plugin is invoked. But you can easily customize the configuration of the generators, if you need to.
C.5.2. Modes for specifying the base image
In Fuse on OpenShift, the base image for an application build can either be a Java image (for Spring Boot applications) or a Karaf image (for Karaf applications). The Fabric8 Maven plug-in supports the following modes for specifying the base image:
istag(Default) The image stream mode works by selecting a tagged image from an OpenShift image stream. In this case, the base image is specified in the following format:
<namespace>/<image-stream-name>:<tag>
Where
<namespace>is the name of the OpenShift project where the image streams are defined (normally,openshift),<image-stream-name>is the name of the image stream, and<tag>identifies a particular image in the stream (or tracks the latest image in the stream).dockerThe docker mode works by selecting a particular Docker-formatted image directly from an image registry. Because the base image is obtained directly from a remote registry, an image stream is not required. In this case, the base image is specified in the following format:
[<registry-location-url>/]<image-namespace>/<image-name>:<tag>
Where the image specifier optionally begins with the URL location of the remote image registry
<registry-location-url>, followed by the image namespace<image-namespace>, the image name<image-name>, and the tag,<tag>.
The default behavior of the open source community version of fabric8-maven-plugin is different from the Red Hat productized version (for example, in the community version, the default mode is docker).
C.5.2.1. Default values for istag mode
When istag mode is selected (which is the default), the Fabric8 Maven plugin uses the following default image specifiers to select the Fuse images (formatted as <namespace>/<image-stream-name>:<tag>):
fuse7/fuse-eap-openshift:1.6 fuse7/fuse-java-openshift:1.6 fuse7/fuse-karaf-openshift:1.6
In the Fuse image streams, the individual images are tagged with build numbers — for example, 1.0-1, 1.0-2, and so on. The 1.0 tag is configured to always track the latest image.
C.5.2.2. Default values for docker mode
When docker mode is selected, and assuming that the OpenShift environment is configured to access registry.redhat.io, the Fabric8 Maven plugin uses the following default image specifiers to select the Fuse images (formatted as <image-namespace>/<image-name>:<tag>):
fuse7/fuse-eap-openshift:1.6 fuse7/fuse-java-openshift:1.6 fuse7/fuse-karaf-openshift:1.6
C.5.2.3. Mode configuration for Spring Boot applications
To customize the mode configuration and base image location used for building Spring Boot applications, add a configuration element to the fabric8-maven-plugin configuration in your application’s pom.xml file, in the following format:
Example
<configuration>
<generator>
<config>
<spring-boot>
<fromMode>{istag|docker}</fromMode>
<from>{image locations}</from>
</spring-boot>
</config>
</generator>
</configuration>
C.5.2.4. Mode configuration for Karaf applications
To customize the mode configuration and base image location used for building Karaf applications, add a configuration element to the fabric8-maven-plugin configuration in your application’s pom.xml file, in the following format:
Example
<configuration>
<generator>
<config>
<karaf>
<fromMode>{istag|docker}</fromMode>
<from>{image locations}</from>
</karaf>
</config>
</generator>
</configuration>
C.5.2.5. Specifying the Generator mode using the command line
As an alternative to customizing the mode configuration directly in the pom.xml file, you can pass the mode settings directly to the mvn command, by adding the following property settings to the command line invocation.
Example
//build from Docker-formatted image directly, registry location, image name or tag are subject to change if desirable -Dfabric8.generator.fromMode=docker -Dfabric8.generator.from=<custom-registry-location-url>/<image-namespace>/<image-name>:<tag> //to use ImageStream from different namespace -Dfabric8.generator.fromMode=istag //istag is default -Dfabric8.generator.from=<namespace>/<image-stream-name>:<tag>
C.5.3. Spring Boot
The Spring Boot generator gets activated when it finds a spring-boot-maven-plugin plugin in the pom.xml file. The generated container port is read from the server.port property in the application.properties file, defaulting to 8080 if it is not found.
In addition to the common generator options, this generator can be configured with the following options:
| Element | Description | Default |
|---|---|---|
| assemblyRef | If a reference to an assembly is given, then this is used without trying to detect the artifacts to include. | |
| targetDir | Directory within the generated image where the detected artifacts are put. Change this only if the base image is changed too. |
|
| jolokiaPort | Port of the Jolokia agent exposed by the base image. Set this to 0 if you don’t want to expose the Jolokia port. | 8778 |
| mainClass |
Main class to call. If not specified, the generator searches for the main class as follows. First, a check is performed to detect a fat-jar. Next, the | |
| webPort | Port to expose as service, which is supposed to be the port of a web application. Set this to 0 if you don’t want to expose a port. | 8080 |
| color | If set, force the use of color in the Spring Boot console output. |
The generator adds Kubernetes liveness and readiness probes pointing to either the management or server port as read from the application.properties. If the server.ssl.key-store property is set in application.properties then the probes are automatically set to use https.
C.5.4. Karaf
The Karaf generator gets activated when it finds a karaf-maven-plugin plugin in the pom.xml file. In addition to the common generator options, this generator can be configured with the following options.
| Element | Description | Default |
|---|---|---|
| baseDir | Directory within the generated image where the detected artifacts are put. Change this only if the base image is changed too. |
|
| jolokiaPort | Port of the Jolokia agent exposed by the base image. Set this to 0 if you don’t want to expose the Jolokia port. | 8778 |
| mainClass |
Main class to call. If not specified, the generator searches for the main class as follows. First, a check is performed to detect a fat-jar. Next, the | |
| user |
User and/or group under which the files should be added. The user must already exist in the base image. It has the general format |
|
| webPort | Port to expose as service, which is supposed to be the port of a web application. Set this to 0 if you don’t want to expose a port. | 8080 |
