This article provides step by step instruction on how to create a custom image for App Connect on OpenShift without the overhead of creating and maintaining a separate image registry.
When deploying an App Connect integration on OpenShift, you have a choice between uploading the bar file to the App Connect dashboard or "baking it in" to a custom image.
There are pros and cons of each of these. Uploading via the dashboard works out of the box and you do not need any additional infrastructure.
If you create a baked image, you can automate the whole process and there is no need to use any UI.
Further to this, creating a baked image provides more control over customisation of the container.
You could add multiple bar files, bar file overrides, user defined extension or third party libraries etc.
On starting the build, OpenShift will create a `build` pod which pulls the ACE image from either IBM Entitled Registry or from Dockerhub.
The result of the build is a new image, which extends the ACE image by adding the bar file.
This new image is published to the image registry on the OpenShift cluster.
Finally an IntegrationServer is created and each of its pods pulls the custom image from the ImageRegistry to run in its containers.
To configure the system, we shall create the following:
- Source Image We define an ImageStream with an ImageStreamTag with a reference to the App Connect base image.
- Build Configuration An OpenShift BuildConfig stores the configuration (e.g Dockerfile) necessary to build the custom image.
- Target Image We define another ImageStream containing an ImageStreamTag with a reference to the resulting custom image.
Out of the box, OpenShift provides some resources that can be configured to build images and store them in the cluster's own image registry. There are a few build strategies available and different options for triggering and for loading or pulling your code into those builds.
We are going to use the dockerStrategy and will trigger the build manually from command line.
Select the project that you want to use
oc project ar-cp4i-ace-demo
or create a new project with
oc new-app ar-cp4i-ace-demo
Open a bash terminal and set the environment variable OPEN_SHIFT_PROJECT
to the name of the OpenShift project that you created for Prerequisite #2 and set IBM_ENTITLEMENT_KEY
to the value of your IBM entitlement key. NOTE: it is not necessary to set IBM_ENTITLEMENT_KEY
if you intend to use the developer edition from docker hub.
For example, in your terminal, run the following, replacing ar-cp4i-ace-demo
with the name of your project and replacing <your ibm entitlement key>
with your key for the IBM Entitled Registry:
export OPEN_SHIFT_PROJECT=ar-cp4i-ace-demo
export IBM_ENTITLEMENT_KEY=<your ibm entitlement key>
Set Windows PATH variable for the current session:
set OPEN_SHIFT_PROJECT=ar-cp4i-ace-demo
set IBM_ENTITLEMENT_KEY=<your ibm entitlement key>
If you are intending to use the developer edition image, then you may skip this step.
Run the following in the same bash terminal
oc create secret docker-registry ibm-entitlement-key --docker-username=cp --docker-password=${IBM_ENTITLEMENT_KEY} --docker-server=cp.icr.io
Run the following in your bash terminal to create an ImageStream:
oc apply -f - <<EOF
apiVersion: image.openshift.io/v1
kind: ImageStream
metadata:
name: ace-server-prod
namespace: ${OPEN_SHIFT_PROJECT}
EOF
The name we give here can be anything that you chose but we will use ace-server-prod
so that it is descriptive of its purpose.
If you are using the developer edition, then it would make sense to change the name
of the ImageStream
to ace-server
Run the following in your terminal to create an ImageStreamTag
oc tag -n ${OPEN_SHIFT_PROJECT} cp.icr.io/cp/appc/ace-server-prod@sha256:04bc376391a00ff1923d9122f93911b0f8e9700c7dda132f24676e383c0283cc ace-server-prod:latest-amd64
This will use release 11.0.0.9-r2 production images. Refer to the App Connect Knowledge Center for the tags for other releases of the production image and refer to https://hub.docker.com/r/ibmcom/ace-server/tags for the tags relating to the developer edition.
If this is successful, then it validates that you have performed step 2 correctly.
oc get ImageStreamTags -n ${OPEN_SHIFT_PROJECT}
Should return something like
NAME IMAGE REFERENCE UPDATED
ace-server-prod:latest-amd64 cp.icr.io/cp/appc/ace-server-prod@sha256:04bc376391a00ff1923d9122f93911b0f8e9700c7dda132f24676e383c0283cc 16 seconds ago
Run the following in your terminal to create an ImageStream
oc apply -f - <<EOF
apiVersion: image.openshift.io/v1
kind: ImageStream
metadata:
name: my-custom-ace-image
namespace: name: ar-ace-app-demo
EOF
The name can be anything you chose. You will likely create a new ImageStream for every bar file that you intend to deploy so it would make sense to give a name that makes it easy to associate with the bar file and the purpose of that integration.
Run the following in your terminal to create the BuildConfig object
oc apply -f - <<EOF
apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
name: ar-ace-app-demo
namespace: ace
labels:
app: ar-ace-app-demo
spec:
source:
type: Git
git:
uri: https://github.com/Mduduzi/ar-cp4i-ace-demo.git
contextDir: .
strategy:
type: Docker
dockerStrategy:
dockerfilePath: Dockerfile # Look for Dockerfile in: gitUri/contextDir/dockerfilePath
output:
to:
kind: ImageStreamTag
name: my-custom-ace-image:latest
namespace: ar-cp4i-ace-demo
EOF
NOTE: If you are using developer edition and you changed the name of the ImageStream in step 3, then you need to update the yaml here accordingly.