App Connect

This blog is part of a series. For the whole series list see here


Scenario 1. Basic example using Docker

Many enterprises have IBM Integration Bus environments running 100s of integration flows in production. You have likely read about the benefits of moving to containers, perhaps even more generally of agile integration (http://ibm.biz/agile-integration), and you’d like to explore that. You’d also like to move to a more recent version of the product (now named App Connect Enterprise). However, it is likely you have no, or at least very limited background in container technology. How do you take the first steps to exploring these new platforms and product versions? 

In this series we are going describe how you move to containers running App Connect Enterprise. We’ll build up to more complex examples, but for this first one we’ll take the simplest possible flow, and we’ll use a Docker container environment that can easily be run on a laptop.

It is worth noting that you are not forced to move to containers to move to IBM App Connect Enterprise, but hopefully through these articles we will give you some practical insight into the benefits you might gain if you do.

Introducing our (very) simple integration flow

We take a simple example of an HTTP based flow as shown in the figure below, that presents an echo service (we’ll call it HttpEcho) over an HTTP endpoint on port 7800. This returns the current date-stamp in response. Clearly this example flow doesn’t do much, but this article isn’t about writing integration flows, it is about moving them to containers, and we’ll come to more complex ones in future articles. 

You can call this by going to http://localhost:7800/Echo or running curl command as

curl -k http://localhost:7800/Echo">http://localhost:7800/Echo

The BAR file generated using IIB v10 Toolkit containing the above message flow is attached here. 

In this scenario we will see how to deploy this BAR file into a Docker container running IBM App Connect Enterprise using simple steps.

Building or downloading  a sample IBM App Connect Enterprise image using Docker

To run IBM App Connect Enterprise in a Docker container, you must first build a base image containing an installation of IBM App Connect Enterprise. Instructions are available in the IBM App Connect Enterprise GitHub repository, at https://github.com/ot4i/ace-docker. Alternatively, you can download a pre-built image of IBM App Connect Enterprise from the IBM Entitled Registry. In this example, for simplicity, we will use the pre-built image, but it would work largely the same if you build your own.

Obtain an IBM entitlement key

To obtain your required version of an IBM App Connect Enterprise server image, you require an IBM entitlement key for pulling the image from the IBM Cloud Container Registry.

Obtain an IBM entitlement key by visiting the following site: 

https://myibm.ibm.com/products-services/containerlibrary

You will need to log in with an IBM ID. It is free to register for an ID if you do not have one.

Obtaining an IBM App Connect Enterprise server image

• Log in to the IBM Cloud Container Registry by running this command, using cp as the user name, icr.io as the Docker server, and your entitlement key as the password: 

                 docker login cp.icr.io -u cp -p myEntitlementKey

• Use Docker to pull the required version of the ACE server image, 

                 docker pull imageLocation

where imageLocation represents one of the listed image locations in the table shown in the following link: 

https://www.ibm.com/docs/en/app-connect/12.0?topic=cacerid-building-sample-app-connect-enterprise-image-using-docker

These are basic images based on the ace-docker github samples, and they can be used in any container environment (Docker, Podman, Kubernetes etc.). Note however, that these are different to the  “operator-based” images  that we will be using in later articles . Those have a dependency on the IBM App Connect Operator which can only be installed in Kubernetes environments.

In this demonstration we will use ACE server image version 12.0.5.0-r1

Here is the command we will use to pull the image from the IBM Container registry

$ docker pull cp.icr.io/cp/appc/ace:12.0.5.0-r1@sha256:f8f1baa76be21adfeefef8dcf56f432bad7840efdbe147217ee6dcc8710f478d
$ docker images

 REPOSITORY                      TAG     IMAGE ID      CREATED
cp.icr.io/cp/appc/ace      12.0.5.0-r1  84ae64b988bd  3 weeks ago

After the image is pulled /downloaded, tag it so that it is easy to recall. 

For example :

$ docker tag 84ae64b988bd ace:12.0.5.0-r1
$ docker images

 REPOSITORY                    TAG       IMAGE ID      CREATED       
   ace                    12.0.5.0-r1  84ae64b988bd   3 weeks ago 

Note: If you are using 'podman' tool instead of 'docker' to manage your images, you may see some differences to the output shown above. For example, when you tag an image without repository name, you may see 'localhost/' being prefixed to the image name as shown below:

$ podman tag 84ae64b988bd ace:12.0.5.0-r1
$ podman images

 REPOSITORY                    TAG       IMAGE ID      CREATED       
 localhost/ace            12.0.5.0-r1  84ae64b988bd   3 weeks ago 

Customizing an ACE Server image

You may have some customization requirement on top of the base ACE server image like  setting up some configuration for odbc.ini or bake in the bar files into the ACE server image or you want to add MQ Client to the ACE image to be able to deploy MQ based flows etc..

The samples provides in following GitHub repository contains  Dockerfile and some additional files that show how you can build and customize an IBM App Connect Enterprise Docker image: https://github.com/ot4i/ace-docker/tree/master/samples

Running ACE Server image

You can run the image by using an example command such as:

docker run --name aceserver -p 7600:7600 -p 7800:7800 -p 7843:7843 --env LICENSE=accept --env ACE_SERVER_NAME=ACESERVER   ace:12.0.5.0-r1

Let us look at the various command line options that we have passed to the docker run command.

--name :  Name assigned to the Docker container

-p : This option maps the container's port(s) to the host. The Integration Server by default enables ports 7600, 7800, 7843 during start-up and they serve following purpose:

7600 – An administrative listener port. Also used by the WebUI.
7800 – To listen to http traffic
7843 – To listen to https traffic

These ports are exposed to the VM host so that external applications can invoke the services hosted by message flows over these ports.

--env : To pass on an ENV variable to the container. You must accept the license to be able to launch the ACE Integration Server. You can optionally provide a name to your Integration Server using  env var ACE_SERVER_NAME

 ace:12.0.5.0-r1  : The ACE image that is being launched. 

Observe the console output. An example is shown as below 

2022-09-22 11:55:42.546692: BIP1990I: Integration server 'ace-server' starting initialization; version '12.0.5.0' (64-bit)
2022-09-22 11:55:42.559880: BIP9905I: Initializing resource managers.
2022-09-22 11:55:46.840644: BIP9906I: Reading deployed resources.
2022-09-22 11:55:46.846004: BIP9907I: Initializing deployed resources.
2022-09-22 11:55:46.849080: BIP2155I: About to 'Initialize' the deployed resource 'AutoScaleApp' of type 'Application'.
2022-09-22 11:55:47.117040: BIP2155I: About to 'Start' the deployed resource 'AutoScaleApp' of type 'Application'.
An http endpoint was registered on port '7800', path '/testService'.
2022-09-22 11:55:47.124048: BIP3132I: The HTTP Listener has started listening on port '7800' for 'http' connections.
2022-09-22 11:55:47.124168: BIP1996I: Listening on HTTP URL '/testService'.
Started native listener for HTTP input node on port 7800 for URL /testService
2022-09-22 11:55:47.124404: BIP2269I: Deployed resource 'test_service' (uuid='test_service',type='MessageFlow') started successfully.
2022-09-22 11:55:47.798932: BIP2866I: IBM App Connect Enterprise administration security is inactive.
2022-09-22 11:55:47.815324: BIP3132I: The HTTP Listener has started listening on port '7600' for 'RestAdmin http' connections.
2022-09-22 11:55:47.816880: BIP1991I: Integration server has finished initialization.

It is worth noting that in a single step, starting from a completely generic container platform, the container started within just a few seconds with a fully installed and configured Integration Server, and the BAR file is already deployed and running. Compare this to the time (and indeed the many steps) it would take in a traditional environment to install, configure and start up an Integration Server, and then deploy a BAR file to it. 

You can begin to see just how different this container-based approach is, and what opportunities this offers in terms of new ways of working. We can imagine how much easier it would be for example, to build a CI/CD pipeline, and how that pipeline could effectively include not just the code, but the full server configuration. It might also lead us to think differently about how we manage high availability and scalability. 

We’ll cover more on this and the broader cloud native approach in future posts.

Execute and Test the message flow

Let’s just check that we really do have a running integration application. As seen in the console output, the HTTP listener is listening on port 7800 and service endpoint is /Echo. You can verify the message flow execution by invoking the service via a web browser or curl command.

curl http://<hostname>:7800/Echo

Output :

    <Echo>
        <DateStamp>2021-10-14T09:25:46.352934Z</DateStamp>
    </Echo>

Connecting to the WebUI of the Integration Server

In our start-up command, we chose to expose the web user interface via 7600.

http://<hostname>:7600/

However, it’s worth noting that in a true cloud native deployment we would avoid viewing and administering containers directly like this. A cloud native approach (http://ibm.biz/cloudnativedefined) encourages administrative changes to be made by creating a new container rather than administering the one that is running (“immutable deployment”), and monitoring is generally done by viewing log files or using a visualization tool on them (“observability”).

We’ll discuss these changes to the way we work as we go through the more advanced examples.

Acknowledgement and thanks to Kim Clark for providing valuable technical input to this article.

#IntegrationBus(IIB)
#AppConnectEnterprise(ACE)
#Docker
#containers