Source-to-Image (S2I) is a framework that makes it easy to write images that take application source code as input, and produce a new image that runs the assembled application as output.

The main reasons one might be interested in using source builds are:

To build a Java EE application from source, simply set up a new application and point it to the git repository where the source code is checked in. The OpenShift S2I process detects the presence of a pom.xml file in the root of the project and recognizes it as a Java EE application. At this point, the S2I process looks for a default image stream with a jee tag to handle the build and deployment. In the absence of such a tagged image stream, or if more than one has a matching tag, the intended image stream would have to be explicitly provided as part of the new-app command.

For example, to build and deploy an application with a maven-based source code checked into github, the following command line instruction can be used.

$ oc new-app jboss-eap70-openshift~https://github.com/PROJECT.git --name=APPLICATION_NAME

This uses the oc client library with the jboss-eap70-openshift image stream to build and deploy an application on JBoss EAP 7. It is also possible to set up applications for source deployment, and build and deploy them with Jenkins, using available plugins and/or scripting. Refer to the section on Chapter 4, Jenkins for further details.

As an example, source deployment is used to build and deploy the sample microservice application in the following section.

In environments where a pre-existing build management tool like maven, ant or other is used, as the target environment transitions from a standalone application server to one based on OpenShift, there may be a requirement or preference to continue using the existing build setup and simply deploy the generated war or ear file.

The obvious advantage of using binary source deployment is the lower effort and impact of migration from existing environments to OpenShift, as there is no need to change the existing build strategy, source code management, release workflow, or other processes. Only the deployment target is switched to OpenShift.

To deploy a Java EE application that has already been built, copy the archive file to a location where the oc client binary is available. The deployment is a two-step process, where the new application is first defined and created without providing a source of any type. To ensure that no source is provided to the oc client, create an empty directory and use it to set up the new application:

$ mkdir /tmp/nocontent
$ oc new-app jboss-eap70-openshift~/tmp/nocontent --name=APPLICATION_NAME

This results in a build by the same name being created, which can now be started by providing the binary source, for example:

$ oc start-build APPLICATION_NAME --from-file=APPLICATION.war

It is in fact rare for an application and all its dependencies to be self-contained in a war file. There are often dependencies and custom configuration that require changes to the server. This often means providing a customized standalone-openshift.xml for each service.

Place the standalone-openshift.xml in a directory called configuration, which itself is created at the same level as the war file. Assuming you create a deploy directory with the war file and the configuration directory as the only two items inside, the following command is used to deploy the content of the deploy directory:

$ oc start-build APPLICATION_NAME --from-dir=deploy

It is also possible to set up applications for binary deployment, and build and deploy them with Jenkins, using a combination of available plugins and scripting. Refer to the section on Chapter 4, Jenkins for further details.

As an example and to provide further context and details, the following section leverages the binary deployment of Java EE applications to build and deploy the sample microservice application.

An alternative deployment scenario is one where a container image is created outside of OpenShift and then deployed to create a service. This may be entirely a custom image, but is often the result of layers on top of a standard and supported base image. It is common to use the Dockerfile syntax to add layers on top of existing images.

For more details on creating Docker images, refer to the Red Hat documentation on Creating Docker images

Assuming the existence of a proper image in a docker registry that is accessible to OpenShift, deploying the image and creating an OpenShift service is very easy and follows a similar syntax to that used for S2I and other methods of creating services:

$ oc new-app --docker-image=172.30.12.190:5000/MYNAMESPACE/MYIMAGE --name=MYSERVICENAME

OpenShift provides an internal registry, called the Integrated OpenShift Container Platform Registry, which is ideal for storing images, and to use for the purpose of creating and deploying services.

To directly access this registry, an OpenShift user must be set up with the required roles, and use the login token to directly authenticate against the docker registry. Follow the steps in the Red Hat documentation to grant this user the required privileges.

Use a system admin account, such as the root user, to grant the OpenShift user the required roles:

# oadm policy add-role-to-user system:registry ocuser
# oadm policy add-role-to-user system:image-builder ocuser

Also use this system admin account to determine the connection address of the internal docker registry:

# oc get services -n default

NAME                      CLUSTER-IP       EXTERNAL-IP   PORT(S)                   AGE
docker-registry           172.30.182.75    <none>        5000/TCP                  81d
...

The ocuser credentials can now be used to push new images to the registry. Make sure this linux user is part of a user group called docker in order to be able to invoke docker commands.

Obtain the user’s authentication token and use it to log in to the docker registry:

$ oc whoami -t
UVicwxVTEWUGJyj84vT0cGHeM-K2Cq9Mhiq5mQXSl1o
$ docker login -u ocuser -p UVicwxVTEWUGJyj84vT0cGHeM-K2Cq9Mhiq5mQXSl1o 172.30.182.75:5000
Login Succeeded

Create a Dockerfile using a simple text editor and use it to create a layer on top of the standard JBoss EAP 7 image, to add the built archive and the server configuration files.

# Product Service Docker image
# Version 1

# Pull base image
FROM registry.access.redhat.com/jboss-eap-7/eap70-openshift

# Maintainer
MAINTAINER Calvin Zhu

# deploy app
ADD product.war $JBOSS_HOME/standalone/deployments/
ADD standalone-openshift.xml $JBOSS_HOME/standalone/configuration

USER root
# In the JBoss EAP container, JBoss EAP runs as the jboss user
# but copied files are brought in as root
RUN chown jboss:jboss $JBOSS_HOME/standalone/deployments/product.war
RUN chown jboss:jboss $JBOSS_HOME/standalone/configuration/standalone-openshift.xml
USER jboss

In order to deploy the product service, place Dockerfile in a directory along with product.war, and standalone-openshift.xml, which includes the database configuration:

$ ls -l
total 52
-rw-rw-r--. 1 czhu czhu   469 Apr 12 22:42 Dockerfile
-rw-rw-r--. 1 czhu czhu 19391 Feb 14 19:07 product.war
-rw-rw-r--. 1 czhu czhu 25757 Apr 12 22:33 standalone-openshift.xml

The next step is to build and tag the new image. This tag is subsequently used to push the image to the internal registry.

$ docker build -t 172.30.182.75:5000/deploy-project/msa-product .

Once the new image is successfully built, push it to the local docker registry:

$ docker push 172.30.182.75:5000/deploy-project/msa-product

The final step is deploying the service on OpenShift by having it pull this new docker image from the registry:

$ oc new-app -e MYSQL_USER=product -e MYSQL_PASSWORD=password --docker-image=172.30.182.75:5000/deploy-project/msa-product --name=product-service

The process for building the remaining three images is almost identical. The content of the Dockerfile for each follows.

Dockerfile for Billing service:

# Billing Service Docker image
# Version 1

# Pull base image
FROM registry.access.redhat.com/jboss-eap-7/eap70-openshift

# Maintainer
MAINTAINER Calvin Zhu

# deploy app
ADD billing.war $JBOSS_HOME/standalone/deployments/

USER root
RUN chown jboss:jboss $JBOSS_HOME/standalone/deployments/billing.war
USER jboss

Dockerfile for Sales service:

# Sales Service Docker image
# Version 1

# Pull base image
FROM registry.access.redhat.com/jboss-eap-7/eap70-openshift

# Maintainer
MAINTAINER Calvin Zhu

# deploy app
ADD sales.war $JBOSS_HOME/standalone/deployments/
ADD standalone-openshift.xml $JBOSS_HOME/standalone/configuration

USER root
RUN chown jboss:jboss $JBOSS_HOME/standalone/deployments/sales.war
RUN chown jboss:jboss $JBOSS_HOME/standalone/configuration/standalone-openshift.xml
USER jboss

Dockerfile for Presentation service

# Presentation Service Docker image
# Version 1

# Pull base image
FROM registry.access.redhat.com/jboss-eap-7/eap70-openshift

# Maintainer
MAINTAINER Calvin Zhu

# deploy app
ADD ROOT.war $JBOSS_HOME/standalone/deployments/

USER root
RUN chown jboss:jboss $JBOSS_HOME/standalone/deployments/ROOT.war
USER jboss

Docker scripts for building the new docker images:

$ docker build -t 172.30.182.75:5000/deploy-project/msa-billing . $ docker build -t 172.30.182.75:5000/deploy-project/msa-sales . $ docker build -t 172.30.182.75:5000/deploy-project/msa-presentation .

Docker scripts for pushing the new docker images to local registry.

$ docker push 172.30.182.75:5000/deploy-project/msa-billing $ docker push 172.30.182.75:5000/deploy-project/msa-presentation $ docker push 172.30.182.75:5000/deploy-project/msa-sales

CLI scripts for deploy the new docker images to OpenShift and expose the service.

$ oc new-app --docker-image=172.30.182.75:5000/deploy-project/msa-billing --name=billing-service $ oc new-app --docker-image=172.30.182.75:5000/deploy-project/msa-presentation --name=presentation $ oc new-app -e MYSQL_USER=sales -e MYSQL_PASSWORD=password --docker-image=172.30.182.75:5000/deploy-project/msa-sales --name=sales-service $ oc expose service presentation --hostname=msa.example.com

The fabric8-maven-plugin is a Maven plugin that accelerates development by allowing easy and quick deployment of Java applications to OpenShift. This plugin reduces the required steps by building the application, creating a docker image and deploying it to OpenShift in a single command, which is especially useful in the development stage, where multiple retries often accompany each step.

The following example demonstrates using fabric8-maven-plugin alongside the Dockerfile assets used in the previous section, to build and deploy the same four services to OpenShift.

Each project’s pom.xml file needs to be updated with the following plugin elements. The newly added configuration for the Product service looks as follows:

<plugin>
        <groupId>io.fabric8</groupId>
        <artifactId>fabric8-maven-plugin</artifactId>
        <version>3.2.28</version>
        <configuration>
            <images>
                <image>
                    <name>172.30.182.75:5000/deploy-project/msa-product</name>
                  <alias>product-svc</alias>
                  <build>
                    <dockerFileDir>/home/czhu/dockerBuild/product/</dockerFileDir>
                  </build>
            </image>
            </images>
            <enricher>
                <config>
                      <fmp-controller>
                        <name>product-service</name>
                      </fmp-controller>
                </config>
            </enricher>
            <env>
              <MYSQL_USER>product</MYSQL_USER>
              <MYSQL_PASSWORD>password</MYSQL_PASSWORD>
            </env>
        </configuration>
        <executions>
            <execution>
                <id>fmp</id>
                <goals>
                    <goal>resource</goal>
                    <goal>build</goal>
                    <goal>push</goal>
                </goals>
          </execution>
        </executions>
</plugin>
<plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <version>3.0.2</version>
    <executions>
      <execution>
        <id>copy-resources</id>
        <phase>package</phase>
        <goals>
          <goal>copy-resources</goal>
        </goals>
        <configuration>
          <outputDirectory>/home/czhu/dockerBuild/product/</outputDirectory>
          <resources>
            <resource>
              <directory>/home/czhu/MSA-EAP7-OSE/Product/target</directory>
                <includes>
                    <include>product.war</include>
                </includes>
            </resource>
            <resource>
              <directory>/home/czhu/MSA-EAP7-OSE/Product/configuration</directory>
                <includes>
                    <include>standalone-openshift.xml</include>
                </includes>
            </resource>
          </resources>
        </configuration>
      </execution>
    </executions>
</plugin>

The image element contains the docker repository name, and the Dockerfile information:

<images>
    <image>
        <name>172.30.182.75:5000/deploy-project/msa-product</name>
      <alias>product-svc</alias>
      <build>
        <dockerFileDir>/home/czhu/dockerBuild/product/</dockerFileDir>
      </build>
</image>
</images>

The fmp-controller enricher is used to name the service. In its absence, the artifactId configured in the pom.xml will be used.

<enricher>
    <config>
          <fmp-controller>
            <name>product-service</name>
          </fmp-controller>
    </config>
</enricher>

The env element is used to configure environment variables and replaces passing environment variables through the -e flag:

<env>
  <MYSQL_USER>product</MYSQL_USER>
  <MYSQL_PASSWORD>password</MYSQL_PASSWORD>
</env>

By using maven-resources-plugin, our build file copies both product.war and standalone-openshift.xml to the Dockerfile folder and prepares the for the image build:

    <artifactId>maven-resources-plugin</artifactId>
    <version>3.0.2</version>
    <executions>
      <execution>
        <id>copy-resources</id>
        <phase>package</phase>
        <goals>
          <goal>copy-resources</goal>
        </goals>
        <configuration>
          <outputDirectory>/home/czhu/dockerBuild/product/</outputDirectory>
          <resources>
            <resource>
              <directory>/home/czhu/MSA-EAP7-OSE/Product/target</directory>
                <includes>
                    <include>product.war</include>
                </includes>
            </resource>
            <resource>
              <directory>/home/czhu/MSA-EAP7-OSE/Product/configuration</directory>
                <includes>
                    <include>standalone-openshift.xml</include>
                </includes>
            </resource>
          </resources>
        </configuration>
      </execution>
    </executions>

Deploying through the plugin also requires the use of Resource Fragments to configure OpenShift services. Create the src/main/fabric8 folder for each project, and add a svc.yml file inside it:

[czhu@mw-ocp-master fabric8{master}]$ pwd
/home/czhu/MSA-EAP7-OSE/Product/src/main/fabric8
[czhu@mw-ocp-master fabric8{master}]$ ls -l
total 4
-rw-rw-r--. 1 czhu czhu 157 Apr 19 18:55 svc.yml

The content of svc.yml for Product service is:

apiVersion: v1
kind: Service
metadata:
  name: product-service
spec:
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080
  type: ClusterIP

With these two changes, you can use the following command to trigger the maven build and deployment:

mvn clean fabric8:deploy -Dfabric8.mode=kubernetes

To clean up all the OpenShift resources that were just created, run:

mvn fabric8:undeploy

Additions to pom.xml for other services should be as follows.

For the Billing service:

<plugin>
        <groupId>io.fabric8</groupId>
        <artifactId>fabric8-maven-plugin</artifactId>
        <version>3.2.28</version>
        <configuration>
          <images>
                <image>
                  <name>172.30.182.75:5000/deploy-project/msa-billing</name>
                  <alias>billing-svc</alias>
                  <build>                        <dockerFileDir>/home/czhu/dockerBuild/billing/</dockerFileDir>
                  </build>
            </image>
          </images>
          <enricher>
                <config>
                      <fmp-controller>
                        <name>billing-service</name>
                      </fmp-controller>
                </config>
          </enricher>
        </configuration>
        <executions>
            <execution>
                <id>fmp</id>
                <goals>
                    <goal>resource</goal>
                    <goal>build</goal>
                    <goal>push</goal>
                </goals>
          </execution>
        </executions>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.0.2</version>
<executions>
  <execution>
    <id>copy-resources</id>
    <phase>package</phase>
    <goals>
      <goal>copy-resources</goal>
    </goals>
    <configuration>
      <outputDirectory>/home/czhu/dockerBuild/billing/</outputDirectory>
      <resources>
        <resource>
          <directory>/home/czhu/MSA-EAP7-OSE/Billing/target</directory>
            <includes>
                <include>billing.war</include>
            </includes>
        </resource>
      </resources>
    </configuration>
  </execution>
</executions>
</plugin>

For the Presentation service:

<plugin>
        <groupId>io.fabric8</groupId>
        <artifactId>fabric8-maven-plugin</artifactId>
        <version>3.2.28</version>
        <configuration>
          <images>
                <image>
                    <name>172.30.182.75:5000/deploy-project/msa-presentation</name>
                  <alias>presentation-svc</alias>
                  <build>
                  <dockerFileDir>/home/czhu/dockerBuild/presentation/</dockerFileDir>
                  </build>
            </image>
          </images>
          <enricher>
                <config>
                      <fmp-controller>
                        <name>presentation</name>
                      </fmp-controller>
                </config>
          </enricher>
        </configuration>
        <executions>
            <execution>
                <id>fmp</id>
                <goals>
                    <goal>resource</goal>
                    <goal>build</goal>
                    <goal>push</goal>
                </goals>
          </execution>
        </executions>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.0.2</version>
<executions>
  <execution>
    <id>copy-resources</id>
    <phase>package</phase>
    <goals>
      <goal>copy-resources</goal>
    </goals>
    <configuration>
      <outputDirectory>/home/czhu/dockerBuild/presentation/</outputDirectory>
      <resources>
        <resource>
          <directory>/home/czhu/MSA-EAP7-OSE/Presentation/target</directory>
            <includes>
                <include>ROOT.war</include>
            </includes>
        </resource>
      </resources>
    </configuration>
  </execution>
</executions>
</plugin>

For the Sales service:

 <plugin>
        <groupId>io.fabric8</groupId>
        <artifactId>fabric8-maven-plugin</artifactId>
        <version>3.2.28</version>
        <configuration>
            <images>
                <image>
                    <name>172.30.182.75:5000/deploy-project/msa-sales</name>
                  <alias>sales-svc</alias>
                  <build>
                    <dockerFileDir>/home/czhu/dockerBuild/sales/</dockerFileDir>
                  </build>
            </image>
            </images>
            <enricher>
                <config>
                      <fmp-controller>
                        <name>sales-service</name>
                      </fmp-controller>
                </config>
            </enricher>
            <env>
              <MYSQL_USER>sales</MYSQL_USER>
              <MYSQL_PASSWORD>password</MYSQL_PASSWORD>
            </env>
        </configuration>
        <executions>
            <execution>
                <id>fmp</id>
                <goals>
                    <goal>resource</goal>
                    <goal>build</goal>
                    <goal>push</goal>
                </goals>
          </execution>
        </executions>
</plugin>
  <plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <version>3.0.2</version>
    <executions>
      <execution>
        <id>copy-resources</id>
        <phase>package</phase>
        <goals>
          <goal>copy-resources</goal>
        </goals>
        <configuration>
          <outputDirectory>/home/czhu/dockerBuild/sales/</outputDirectory>
          <resources>
            <resource>
              <directory>/home/czhu/MSA-EAP7-OSE/Sales/target</directory>
                <includes>
                    <include>sales.war</include>
                </includes>
            </resource>
            <resource>
              <directory>/home/czhu/MSA-EAP7-OSE/Sales/configuration</directory>
                <includes>
                    <include>standalone-openshift.xml</include>
                </includes>
            </resource>
          </resources>
        </configuration>
      </execution>
    </executions>
</plugin>

The svc.yml resource fragment would also be created under src/main/fabric8 folder for each service as described below.

For the Billing service:

apiVersion: v1
kind: Service
metadata:
  name: billing-service
spec:
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080
  type: ClusterIP

For the Presentation service:

apiVersion: v1
kind: Service
metadata:
  name: presentation
spec:
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080
  type: ClusterIP

For the Sales service:

apiVersion: v1
kind: Service
metadata:
  name: sales-service
spec:
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080
  type: ClusterIP

Once all four services are created in OpenShift, create the route using OpenShift CLI:

$ oc expose service presentation --hostname=msa.example.com