Appendix C. OpenShift Maven plugin

The OpenShift Maven plugin is used for building and deploying Java applications for OpenShift. It brings your Java applications on to OpenShift. It provides a tight integration into maven and benefits from the build configuration already provided. It focuses on three tasks:

  • Building S2I images
  • Creating OpenShift resources
  • Deploy application on OpenShift

C.1. About OpenShift Maven plugin

OpenShift Maven plugin has following features:

  • Dealing with S2I images and hence inherits its flexible and powerful configuration.
  • Supports both OpenShift descriptors
  • OpenShift Docker builds with a binary source (as an alternative to a direct image build against a Docker daemon)

  • Mulitple configuration styles:

    • Zero Configuration for a quick ramp-up where opinionated defaults will be pre-selected.
    • Inline Configuration within the plugin configuration in an XML syntax.
    • External Configuration templates of the real deployment descriptors which are enriched by the plugin.

  • Flexible customization:

    • Generators analyze the Maven build and generated automatic Docker image configurations for certain systems (spring-boot, plain java, karaf)
    • Enrichers extend the OpenShift resource descriptors by extra information like SCM labels and can add default objects like Services.
    • Generators and Enrichers can be individually configured and combined into profiles.

C.2. Building images

The oc:build goal is used for creating Docker-formatted images containing an application. These then can be deployed later on Kubernetes or OpenShift. This plugin uses the assembly descriptor format from the maven-assembly-plugin to specify the content which will be added to the image. These images can then be pushed to public or private Docker registries with oc:push. The oc:watch goal allows for you to react to the code changes to automatically recreate images or copy new artifacts into running containers.

C.3. Kubernetes and OpenShift resources

Kubernetes and OpenShift resource descriptors can be created with oc:resource. These files are packaged within the Maven artifacts and can be deployed to a running orchestration platform with oc: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.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.

C.4. Installing OpenShift Maven plugin

This plugin is available under the Maven central repository and can be connected to pre- and post-integration phases as shown below. By default, Maven will only search for plugins in the org.apache.maven.plugins and org.codehaus.mojo packages. In order to resolve the provider for the JKube plugin goals, edit the ~/.m2/settings.xml file and add the org.eclipse.jkube namespace so the <pluginGroups> configuration.

Procedure

  • To connect the OpenShift Maven plugin to pre- and post-integration phases, add the following to ~/.m2/settings.xml file. 
<settings>
      ...

      <pluginGroups>
        <pluginGroup>org.jboss.redhat-fuse</pluginGroup>
      </pluginGroups>

      ...
</settings>

<plugin>
  <groupId>org.jboss.redhat-fuse</groupId>
  <artifactId>openshift-maven-plugin</artifactId>
  <version>${fuse.version}</version>

  <configuration>
     ....
     <images>
        <!-- A single's image configuration -->
        <image>
          ...
          <build>
           ....
          </build>
        </image>
        ....
     </images>
  </configuration>

  <!-- Connect oc:resource, oc:build and oc:helm to lifecycle phases -->
  <executions>
    <execution>
       <id>jkube</id>
       <goals>
         <goal>resource</goal>
         <goal>build</goal>
         <goal>helm</goal>
       </goals>
    </execution>
  </executions>
</plugin>

C.5. Understanding OpenShift Maven plugin build goals

Build goals are used to create and manage the Kubernetes and OpenShift build artifacts like Docker-formatted images or S2I builds.

Table C.1. OpenShift Maven plugin build goals

GoalDescription

oc:resource

Create Kubernetes or OpenShift resource descriptors. Generated resources are in target/classes/META-INF/jkube/openshift directory.

oc:build

Build images.

oc:push

Push images to a registry. The registry to push is by default docker.io but can be specified as part of the images’s name.

oc:apply

Apply resources to a running cluster. This goal is similar to oc:deploy but does not perform the full deployment cycle.

C.6. Understanding OpenShift Maven plugin development goals

Development goals are used in deploying resource descriptors to the development cluster. Also, helps you to manage the lifecycle of the development cluster.

Table C.2. OpenShift Maven plugin development goals

GoalDescription

oc:deploy

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

oc:undeploy

Undeploy and remove resources descriptors from a cluster.

oc:log

Show the logs of the running application.

oc:debug

Enable remote debugging.

oc:watch

Watch for file changes and perform rebuilds and redeployments.