Appendix C. Fabric8 Maven Plug-In

C.1. Overview

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.xml file.

C.1.1. Building Images

The fabric8:build goal is 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.

Important

Fuse on OpenShift supports only the OpenShift s2i build strategy, not the docker build strategy.

C.1.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.

C.1.3. 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.xml file 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.2. 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.

<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.3. Understanding the 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.3.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:

Table C.1. Build Goals

GoalDescription

fabric8:build

Build images. Note that Fuse on OpenShift supports only the OpenShift s2i build strategy, not the docker build strategy.

fabric8:resource

Create Kubernetes or OpenShift resource descriptors

fabric8:apply

Apply resources to a running cluster

fabric8:resource-apply

Run fabric8:resourcefabric8:apply

Table C.2. Development Goals

GoalDescription

fabric8:run

Run a complete development workflow cycle fabric8:resourcefabric8:buildfabric8:apply in the foreground.

fabric8:deploy

Deploy resources descriptors to a cluster after creating them and building the app. Same as fabric8:run except that it runs in the background.

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.3.2. Setting Environmental Variable

You can set one or more environment variables by adding the env parameter in the XML configuration. For example,

<configuration>
  <resources>
    <env>
        <JAVA_OPTIONS>-Dmy.custom=option</JAVA_OPTIONS>
        <MY_VAR>value</MY_VAR>
    </env>
  </resources>
</configuration>

C.3.3. Resource Validation Configuration

The fabric8:resource goal validates the generated resource descriptors using API specification of Kubernetes and OpenShift.

Table C.3. Resource Validation Configuration

ConfigurationDescriptionDefault

fabric8.skipResourceValidation

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

fabric8.failOnValidationError

If value is set to true then any validation error will block the plugin execution. A warning will be displayed otherwise.

false

fabric8.build.switchToDeployment

If value is set to true then fabric8-maven-plugin would switch to Deployments rather than DeploymentConfig when not using ImageStreams on OpenShift.

false

fabric8.openshift.trimImageInContainerSpec

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 ImagePullErr.

false

For more information about the Fabric8 Maven plugin goals, see https://maven.fabric8.io/#goals.

C.4. Generators

The Fabric8 Maven plug-in provides generator components, which have the capability to build images automatically for specific kinds of application. In the case of Fuse on OpenShift, the following generator types are supported:

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.

Note

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.4.1. Zero-Configuration

Generators do not require any configuration. They are enabled by default and run automatically with default settings when the Fabric8 Maven plug-in is invoked. But you can easily customize the configuration of the generators, if you need to.

C.4.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).

docker

The 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>.

Note

The default behaviour 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.4.2.1. Default Values for istag Mode

When istag mode is selected (which is the default), the Fabric8 Maven plug-in uses the following default image specifiers to select the Fuse images (formatted as <namespace>/<image-stream-name>:<tag>):

fuse7/fuse-eap-openshift:1.2
fuse7/fuse-java-openshift:1.2
fuse7/fuse-karaf-openshift:1.2
Note

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.4.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 plug-in uses the following default image specifiers to select the Fuse images (formatted as <image-namespace>/<image-name>:<tag>):

fuse7/fuse-eap-openshift:1.2
fuse7/fuse-java-openshift:1.2
fuse7/fuse-karaf-openshift:1.2

C.4.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:

<configuration>
  <generator>
    <config>
      <spring-boot>
        <fromMode>{istag|docker}</fromMode>
        <from>{image locations}</from>
      </spring-boot>
    </config>
  </generator>
</configuration>

C.4.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:

<configuration>
  <generator>
    <config>
      <karaf>
        <fromMode>{istag|docker}</fromMode>
        <from>{image locations}</from>
      </karaf>
    </config>
  </generator>
</configuration>

C.4.2.5. Specifying the Mode on 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:

//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.4.3. Spring Boot

The Spring Boot generator gets activated when it finds a spring-boot-maven-plugin plug-in in the pom.xml file. The generated container port is read from the server.port property application.properties, defaulting to 8080 if it is not found.

In addition to the common generator options, this generator can be configured with the following options:

Table C.4. Spring-Boot configuration options

ElementDescriptionDefault

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 artefacts are put. Change this only if the base image is changed too.

/deployments

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 target/classes directory is scanned to look for a single class with a main method. If none is found or more than one is found, the generator does nothing.

 

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.4.4. Karaf

The Karaf generator gets activated when it finds a karaf-maven-plugin plug-in in the pom.xml file.

In addition to the common generator options, this generator can be configured with the following options:

Table C.5. Karaf configuration options

ElementDescriptionDefault

baseDir

Directory within the generated image where the detected artifacts are put. Change this only if the base image is changed too.

/deployments

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 target/classes directory is scanned to look for a single class with a main method. If none is found or more than one is found, the generator does nothing.

 

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 <user>[:<group>[:<run-user>]]`. The user and group can be given either as numeric user- and group-id or as names. The group id is optional.

jboss:jboss:jboss

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