Examining simple build and deployment operations on OpenShift 3/4
Note:
I wrote this article originally for OpenShift 3. I'm please to say that, although the architecture of OpenShift 4 is quite different, the command-line interface remains very similar, and the procedures I describe work on OpenShift 4 as well
OpenShift 3 is designed to make simple application deployment more-or-less
automatic -- you can go directly from source code in a repository, to
an application running in a container (pod) with no detailed understanding
of the internal operations involved. However, such an understanding is
necessary to set up more complicated build operations.
This article describes how to deploy a simple Java application, which is
provided as an executable JAR file, by creating a build configuration
and a deployment configuration. All OpenShift steps are carried out on
the command line using the
oc tool, and we will inspect
the OpenShift artefacts created by the infrastructure at each step.
To follow the steps in this example, you will need a Java 1.8 JDK,
and an installation of Maven (and probably some experience of
setting it up and using it).
I don't assume much knowledge of OpenShift 3, but you need to know
what a pod is, and have some understanding of containers.
Create a simple Apache Camel application from an archetype
For this demonstration I will be using an application based on Fuse
Integration Services (FIS) -- this is a framework for building Apache Camel
applications based on Spring Boot. There is no particularly compelling
reason for this choice, other than that I need to deploy FIS applications
on OpenShift for other purposes. This demonstration would work with
any self-contained Java application that can be run from a JAR
file.
Get the source
A sample FIS Camel application can be built from a Maven archetype,
like this:
$ mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate \
-DarchetypeCatalog=https://maven.repository.redhat.com/ga/io/fabric8/archetypes/\
archetypes-catalog/2.2.195.redhat-000004/archetypes-catalog-2.2.195.redhat-000004-archetype-catalog.xml \
-DarchetypeGroupId=org.jboss.fuse.fis.archetypes \
-DarchetypeArtifactId=spring-boot-camel-xml-archetype \
-DarchetypeVersion=2.2.195.redhat-000004
Fill in the prompted values -- the exact input is unimportant, but
I chose
fis-test for the artefact name, which also becomes
the name of the directory that Maven creates for the source.
The application includes a lot of infrastructure, including the whole of
the Apache Camel core, but all it does in its stock form is write messages
to standard out.
Build and test the JAR
cd to the newly-created directory, and then
$ mvn package
This creates a JAR file in the
target directory.
It should be possible to run the application locally, to see the output
it produces. Of course, in a real development exercise you would probably
want to run unit tests, etc., as well.
$ java -jar target/fis-test-1.0-SNAPSHOT.jar
Create an OpenShift project
Log into OpenShift at the command line (
oc login...) and create a
new OpenShift project; the project name and description are unimportant
for our present purposes.
$ oc new-project test-project
Create an OpenShift build configuration
In OpenShift, a build configuration (BC) is a specification (in the form
of a Kubernetes object)
that describes how to build a deployable image (usually a Docker or Podman image)
from some kind of source. For our purposes it is important to note that
"source" is interpreted very broadly. Although we are using the
"source-to-image" process here, the source is an executable Java JAR
file. In fact, so far as OpenShift is concerned, "source" is anything
that isn't an image -- it might even be a configuration file.
If we have an image, we can skip the
build step completely, and go directly to creating a deployment
configuration (see below).
Set up a new OpenShift build configuration, using the stock Java builder
image, and indicating that the build will take a binary as input
(a JAR, in this case).
$ oc new-build --binary=true --name=fis-test --image-stream=redhat-openjdk18-openshift:1.2
The name
fis-test will be used for the created image, and
for a number of other purposes. To see the details of the build configuration:
$ oc describe bc/fis-test
This shows the following information, among other things. Note that the
build will produce an image called fis-test, and that there is no source
for the image yet: we will provide it when invoking the build from
the command line.
Strategy: Source
From Image: ImageStreamTag openshift/redhat-openjdk18-openshift:1.2
Output to: ImageStreamTag fis-test:latest
Binary: provided on build
You can also view, and perhaps edit, the Kubernetes object definition in
YAML format by running
$ oc edit bc/fis-test
Build the application image
Start the build defined by the
fis-test build configuration,
uploading the JAR built earlier by Maven:
$ oc start-build fis-test --from-file=target/fis-test-1.0-SNAPSHOT.jar --follow
The
--follow switch here indicates that the command should not
complete until the build does.
OpenShift creates a new pod to do the build, whose name is based on the
build configuration name -- in this case,
fis-test-1-build.
The pod
takes as its image the builder image specified in the
new-build
command.
To start the build, the file (or directory) specified on the command line
is packed into
a tar file, and then becomes the builder image's standard input. OpenShift
runs the
tar command in the builder's container, unpacking the
tar file
from stdin into a directory --
/tmp/src by default.
It then runs the
script
/usr/local/bin/s2i/assemble which, in this
particular example,
simply copies the JAR files from
/tmp/src
to
/deployments. The
Java builder image can manage other kinds of Java souce or binary,
and actions will be different in those cases: in some cases, actual
Java compilation may be performed, although this is not necessary in
the present example.
After running
assemble (and some other scripts that
aren't relevant
in this case) the whole contents of the filesytem of the builder
pod's filesystem
are pushed to the docker registry as a new image. Consequently, we
end up with the a new image called
fis-test which is
almost exactly the same as
redhat-openjdk18-openshift, but with our JAR file in
/deployments. It is the presence of this JAR that will
trigger a JVM execution when the new image is deployed and executed.
The fact that the new image contains everything that was in the builder
image is a point of contention for some OpenShift users. A case can
certainly be made that a production container ought not to
contain build-related
tooling, both for reasons of resource management and for security. If
this is a problem, then a different build mechanism will need to be used,
or a second "chained" build step will be needed to sanitize the generated
image.
We can list the builds in the current project like this, and we should
see one completed build:
$ oc get builds
NAME TYPE FROM STATUS STARTED DURATION
fis-test-1 Source Binary Complete 7 minutes ago 1m5s
We should also see one completed pod, that was used to do the build:
$ oc get pods
NAME READY STATUS RESTARTS AGE
fis-test-1-build 0/1 Completed 0 8m
This pod could now be deleted -- it won't be used for anything else;
presumably it is retained so its logs can
be inspected if the build fails.
Deploy the image into an OpenShift pod
We now have one new image stream in the project's namespace:
$ oc get is
NAME DOCKER REPO TAGS UPDATED
fis-test 172.30.1.1:5000/test-project/fis-test latest 8 minutes ago
The image stream consists of one image -- the one with the default
tag "latest".
We need to tell OpenShift how to deploy and run this image in one or
more pods; this requires the creation of a
deployment configuration.
$ oc new-app fis-test
Note that the name
'fis-test' is the name of the image stream -- there are many other possible
inputs
to
new-app, including source code repositories.
new-app can create build configurations as well but, so far as I know, we need
to use
oc new-build explicitly to provide an executable
to OpenShift.
Looking at the list of deployment configurations:
$ oc get dc
NAME REVISION DESIRED CURRENT TRIGGERED BY
fis-test 1 1 1 config,image(fis-test:latest)
we see that the deployment is (by default) triggered by a configuration
change, or a change to the image ``fis-test:latest``. In this case,
providing the configuration counts as a trigger, and the deployment and
provisioning steps will be triggered without further intervention.
So you should already see one pod running:
$ oc describe dc fis-test|grep Replicas
Replicas: 1 current / 1 desired
Since the build configuration was created using default values, the
desired replica count (number of pods) will be 1.
The single, new pod is created by a transient deployer pod. The name
of this pod, in this example, will be
fis-test-1-deploy.
Unlike the builder pod, however, this pod is not retained after
completion. You may see it briefly flash into life if you watch the
pod list whilst doing a deployment.
Since the image for the new pod was created by the source-to-image process
using the script /usr/local/s2i/assemble, the entry
point for execution will be
/usr/local/s2i/run. The
run script delegates (in this simple case) to
/opt/run-java/run-java.sh, which detects the JAR file
in
/deployments, and executes it using
java -jar.... The command line specifies the use of the
Jolokia Java agent, so that the user can have a graphical view
of the JVM operation.
Further builds
After modifying the application, subsequent OpenShift builds are carried
out by repeating the
oc start-build
command, which will trigger a rebuild and redeployment in
OpenShift. The infrastructure will create new build pods and deployer
pod as necessary, numbering them sequentially.
Note that the default redeployment strategy is 'Rolling',
which will cause the a new pod to be started with the new code,
before the old one is shut down. Depending on the application, this
may be inappropriate, and it might be advisable to change the deployment
strategy to 'Recreate' (e.g., using
oc edit dc/fis-test).
Closing remarks
In practice, I would expect that substantial OpenShift projects would
be built using some form of pipeline process, perhaps coordinated
by a build manager like Jenkins. The build manager would create new
OpenShift pods to carry out specific build and deployment operations.
Although OpenShift makes it possible to go directly from a source code
repository to a running container, the large number of default settings
involved in this operation make it less suitable for large-scale development
work.
I've used the command-line for everything in this example, not just because
I think it makes the detailed steps clearer, but because I think that
the terminology it uses is more apposite. The OpenShift web console,
although powerful in its own right, uses terms like 'build' and 'deployment'
in non-specific ways. The web console uses the term 'deployment' to
mean both a deployment configuration, and the process of executing a
deployment. If you already understand the OpenShift build and deployment
philosophy that shouldn't be a problem, but the
oc command
doesn't mix up the different concepts.
