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 or build automation toolchain.
When deploying an App Connect integration on OpenShift, you have a choice between uploading the bar file to the App Connect dashboard and "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. The steps described below can be followed to achieve some of the benefits of creating a custom image by using only what is available out of the box with a App Connect installed on a plain vanilla OpenShift cluster.
The Solution
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.
In the recipe below, we use the dockerStrategy and will trigger the build manually from command line.
You begin with a bar file on your local workstation. You then start the build by uploading a bar file via the `oc` command line utility. 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.
The Recipe
Prerequisites
- An OpenShift cluster
- OpenShift project created on that cluster that you have access to
- App Connect Operator installed on your cluster and available in your project
oc
Command line tool installed on your local workstation
- [Optional] App Connect Toolkit, App Connect Designer or access to and instance of App Connect service on IBM Cloud. Either one of these is needed to develop the integration and create the bar file. However, if you just want to follow the steps here to learn the process, you can use the sample HTTPEcho bar file
- [Optional] An IBM Entitled Registry key or credentials to a private registry containing the base App Connect images. If you decide to use the developer image, then this is optional. The steps below explain what is needed to use the production images and how to configure the use of the credentials to pull that image. If you are using the developer edition images, then these steps can be simplified because no credentials are necessary. Release 11.0.0.9-r1 or later is assumed in these instructions although a similar approach may work on earlier releases.
Steps
1. Setup environment variables
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](#Prerequisites) 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 `my-project` with the name of your project and replacing <your ibm entitlement key> with your key for the IBM Entitled Registry:
export OPEN_SHIFT_PROJECT=my-project
export IBM_ENTITLEMENT_KEY=<your ibm entitlement key>
NOTE: If you are intending to use the developer edition image from docker hub, then you do not need to set
IBM_ENTITLEMENT_KEY
2. Create the pull secret for the base image
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
3. Tag the input image
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
4. Define the output image stream
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: ${OPEN_SHIFT_PROJECT}
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.
5. Specify the build configuration
Run the following in your terminal to create the
BuildConfig
object
oc apply -f - <<EOF
apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
name: my-custom-ace-image
namespace: ${OPEN_SHIFT_PROJECT}
labels:
name: my-custom-ace-image
spec:
triggers: []
source:
type: dockerfile
dockerfile: |
FROM ace-server-prod:latest-amd64
COPY HTTPEcho.bar /home/aceuser/initial-config/bars/HTTPEcho.bar
strategy:
type: Docker
dockerStrategy:
from:
kind: ImageStreamTag
name: 'ace-server-prod:latest-amd64'
namespace: ${OPEN_SHIFT_PROJECT}
output:
to:
kind: ImageStreamTag
name: 'my-custom-ace-image:latest-amd64'
namespace: ${OPEN_SHIFT_PROJECT}
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.
6. Set the pull secret for the build
As with step 2, this is optional if you are using the developer edition images from Dockerhub.
oc set build-secret --pull bc/my-custom-ace-image ibm-entitlement-key
If you now inspect the
BuildConfig
that you created in step 5
oc get BuildConfig my-custom-ace-image -o yaml
You will notice that it has a spec.strategy.pullSecret
field added. We could have included this in the yaml as part of step 5 but I added it as a separate step to make it more obvious to you and also because it is an optional step if you are using the developer edition from Docker Hub.
7. Start the build
oc start-build my-custom-ace-image --from-file ./HTTPEcho.bar
8. Inspect the result
Run the following command to see the status of the build
oc describe builds
You should see a pod created which runs the builds
oc get pod
Run the following to view the buid logs
oc logs <build-pod-name>
Run the following to see the ImageStreamTag
oc get imagestreamtags
You should see something like
NAME IMAGE REFERENCE UPDATED
ace:11.0.0.9-r1-amd64 image-registry.openshift-image-registry.svc:5000/my-project/ace@sha256:318a3874c8283a3a9ea4c6a7cbf7d0764fbd0e609f57e901cc66711b51c3dc86 3 minutes ago
my-custom-ace-image:latest-amd64 image-registry.openshift-image-registry.svc:5000/my-project/my-custom-ace-image@sha256:cc30ef236e8250b6529a3acfafe792c57537fe9426898f74eb3031eb248b52c9 1 minute ago
We see 2 ImageStreamTag
s. The one that we explicitly created in step 3 and the other is a result of running the build.
9. Create an integration server using that image
Edit the following by accepting the license and providing the license value. Then enter it into your terminal to create an integration server
oc apply -f - <<EOF
apiVersion: appconnect.ibm.com/v1beta1
kind: IntegrationServer
metadata:
name: my-integration-server
spec:
version: 11.0.0
pod:
containers:
runtime:
image: image-registry.openshift-image-registry.svc:5000/my-project/my-custom-ace-image:latest-amd64
license:
accept: true
license: L-AMYG-BQ2E4U
use: AppConnectEnterpriseProduction
barURL: ''
designerFlowsOperationMode: disabled
service:
endpointType: http
useCommonServices: false
replicas: 1
EOF
10. Invoke the API
curl http://$(oc get route my-integration-server-http -o jsonpath='{.status.ingress[0].host}')/Echo
11. Cleanup
oc delete IntegrationServer my-integration-server
oc delete build my-custom-ace-image-1
oc delete BuildConfig my-custom-ace-image
oc delete ImageStream my-custom-ace-image
oc delete ImageStream ace-server-prod
oc delete secret ibm-entitlement-key
Conclusion
We created 2 ImageStreams
and in each of those we created an ImageStreamTag
. The BuildConfig
defined how to take the image from one ImageStreamTag and create a new image and tag it as the 2nd ImageStreamTag. This resulting ImageStreamTag was then used to specify a custom image to use on an IntegrationServer
operand.
#AppConnect#Openshift#Integration#custom-image