Scenario 1: Deploy an IBM App Connect Enterprise Toolkit integration on Red Hat OpenShift by using the command-line interface (CLI)

Before you begin, ensure that the prerequisites are met. For more information, see Prerequisites for deploying an IBM App Connect Enterprise Toolkit integration on Red Hat OpenShift.

Scenario 1 introduces the following concepts and shows how they are used in the deployment process:

• Operator installation of the IBM App Connect components

  You will learn how to use an Operator to make the IBM App Connect components available in your OpenShift cluster. The IBM App Connect Operator performs most of the underlying work to set up your containers on Red Hat OpenShift, which significantly simplifies the deployment.

• Remote pull of a BAR file that contains resources for deployment

  You will learn how to pull or retrieve a BAR file from an external (remote) HTTP repository, so that it can be deployed to a container.

• Configuration objects

  You will learn about the purpose of configuration objects, and create a configuration object that stores the credentials for authenticating to the external repository to retrieve the BAR file.

• Deployment of the message flow by using the command line

  You will learn how to use a single standard Kubernetes command (in this case, the Red Hat OpenShift oc command) to deploy the BAR file to an integration runtime, and then test the flow.

An Operator is a Kubernetes-native application that is based on the open source Operator Framework, and offers a way to deploy containers to Kubernetes environments.

The IBM App Connect Operator is used for packaging, deploying, and managing the IBM App Connect Enterprise certified container. This Operator converts your key deployment requirements into the appropriate Kubernetes constructs, and simplifies how you interact with Kubernetes.

The IBM App Connect Operator manages an increasing list of functions, in line with the Understanding operators. Some of these functions are as follows:

• Translates your requirements into Kubernetes constructs such as deployments, pods, routes, services, node ports, and replica sets.
• Links your deployment with any environment-specific configurations that your container needs at run time, and watches these configurations for changes so that they can get rolled out to any reliant containers.
• Tracks the supplied custom resource definitions (CRDs), which contain the structured data that is required to create the App Connect custom resource (CR) objects that you need.

  Each CRD defines an object type such as Dashboard, DesignerAuthoring, IntegrationRuntime, IntegrationServer, or Configuration, which is known as a kind. (In Scenarios 1 and 2, you will create the following object types as you work through the instructions: Configuration, IntegrationRuntime, and Dashboard.)

• Identifies OpenShift cluster events that are related to CR changes (for example, updates or deletions) and responds to these changes by reconciling the current CR state with the desired state.

The BAR file that you are going to deploy is hosted on the public GitHub location at https://github.com/amarIBM/hello-world. This public location is used to keep the instructions simple, but BAR files in other external repositories such as JFrog Artifactory can be used.

You need to provide basic authentication credentials for connecting to the URL endpoint where the BAR file is stored. Credentials often change as you move from one environment to another; therefore, you need a way to supply credentials at deployment time. You can do so by creating a configuration object in the OpenShift cluster, and then reference this configuration object when you deploy the container.

• Introducing configuration objects
• Creating a configuration object from the CLI

Finally, you are ready to deploy an IBM App Connect Enterprise certified container by referencing the remote BAR file. Similar to the configuration object that you created, you will need to create a YAML definition file with the required settings for an integration runtime, and can then run commands to apply this file.

1. On your local computer, create the YAML definition file for the integration runtime. Add the following YAML content to a text file named http-echo-service.yaml:

   apiVersion: appconnect.ibm.com/v1beta1
   kind: IntegrationRuntime
   metadata:
     name: http-echo-service
     namespace: ace-demo
   spec:
     license:
       accept: true
       license: L-APEH-CJUCNR
       use: CloudPakForIntegrationNonProductionFREE
     template:
       spec:
         containers:
           - resources:
               requests:
                 cpu: 300m
                 memory: 368Mi
             name: runtime
     logFormat: basic
     barURL:
       - 'https://github.com/amarIBM/hello-world/raw/master/HttpEchoApp.bar'
     configurations:
       - github-barauth
     version: '12.0'
     replicas: 1

   The main parameters to note are as follows:

   • The kind parameter indicates that you want to create an IntegrationRuntime object or instance.
   • The name parameter provides a unique name for the integration runtime.
   • The namespace parameter points to the same namespace (or project) where the configuration object was created.
   • The license parameter requires you to specify a license identifier and type that you want to accept for the integration runtime. (This license must align with the channel or fully qualified version that you specify in the version parameter.) For more information, see Licensing reference for IBM App Connect Operator.
   • The barURL parameter denotes the URL where the BAR file is hosted on GitHub. Notice that the raw URL of the file needs to be specified.
   • The configurations parameter references the github-barauth configuration object that you created earlier.
   • The version parameter specifies an App Connect product (fix pack) version that the integration runtime is based on. The sample YAML specifies a channel, but a fully qualified version (that is, a fixed version) can alternatively be specified. Choosing a channel generally indicates that you want the integration runtime to be updated to the latest known version whenever new Operator patch versions are installed on the OpenShift cluster. For more information about these values, see spec.version values.
   • The replicas parameter specifies how many replica pods you want to run for this deployment. In this case, use the default value of 1.

     It's worth noting that you can specify higher values if you want to create multiple copies of the container in order to provide high availability. This, in turn, can enable you (with experience) to take advantage of the benefits of the container orchestration platform and scale up when the incoming workload increases, or automatically spread the workload across all those container replicas.

   Tip:

   Although the referenced BAR file on GitHub contains only one message flow, it's possible to deploy a BAR file that contains multiple applications, or even deploy multiple BAR files. If needed, you can specify multiple BAR files as an array by using the barURL parameter; for example:

     barURL:
       - 'https://github.com/amarIBM/hello-world/raw/master/HttpEchoApp.bar'
       - 'https://github.com/amarIBM/hello-world/raw/master/CustomerOrderAPI.bar'

   Some considerations apply if you are deploying multiple BAR files:

   • Ensure that all of the applications can coexist (with no names that clash).
   • Ensure that you provide all of the configurations that are needed for all of the BAR files.
   • All of the BAR files must be accessible by using the single set of credentials that are specified in the configuration object of type BarAuth.
2. Log in to your OpenShift cluster if you are no longer logged in.

   oc login --token=xxxxxxxxx  --server=https://yyyyyy.abc.com:6443

   Also, switch to the namespace (or project) where the Operator and configuration object are installed if necessary.

3. Create the integration runtime in the cluster by running the following command to apply the http-echo-service.yaml file that you created earlier.

   oc apply -f  http-echo-service.yaml

   You should receive this confirmation:

   integrationruntime.appconnect.ibm.com/http-echo-service created

Verify the status of your application by looking at the pod log and then invoke the service by using routes.

1. Verify the status of the integration runtime pod. In Kubernetes, containers are always deployed within a definition called a pod. Let's look for the one that you just created.

   oc get pods

   You should see output that is similar to this:

   NAME                                                              READY   STATUS      RESTARTS          AGE
   http-echo-service-ir-66c689ddc-n7xvw                              1/1     Running     0                 111s

   You’ll notice that the READY column displays 1/1 because you requested only one replica of this container (by using replicas: 1 in the YAML definition file). Also, notice that the requested replica has been started.

   You can also verify the status of your application by looking at the pod log:

   oc logs podName

   For example:

   oc logs http-echo-service-ir-66c689ddc-n7xvw

   You should see output that is similar to this:

   2022-12-11T21:39:22.474Z Image created: 2022-11-25T16:15:45+00:00
   2022-12-11T21:39:22.476Z ACE version: 12.0.7.0
   ...
   2022-12-11T21:39:24.504Z Downloading bar file using supplied credentials
   2022-12-11T21:39:24.504Z BasicAuth Credentials
   2022-12-11T21:39:24.522Z No certs provided, using system certs only
   2022-12-11T21:39:25.013Z Downloaded bar file from: https://github.com/amarIBM/hello-world/raw/master/HttpEchoApp.bar
   2022-12-11T21:39:25.014Z Saved bar file to /home/aceuser/initial-config/bars/barfile.bar
   2022-12-11T21:39:25.014Z Construct a configuration on the filesystem - configuration name: http-echo-service-ir-adminssl type: adminssl
   ...
   2022-12-11 21:39:26.352858: BIP9906I: Reading deployed resources.
   2022-12-11 21:39:26.356152: BIP9907I: Initializing deployed resources.
   2022-12-11 21:39:26.357248: BIP2155I: About to 'Initialize' the deployed resource 'HTTPEcho' of type 'Application'.
   2022-12-11 21:39:26.377822: BIP2155I: About to 'Start' the deployed resource 'HTTPEcho' of type 'Application'.
   An http endpoint was registered on port '7800', path '/Echo'.
   2022-12-11 21:39:26.422058: BIP3132I: The HTTP Listener has started listening on port '7800' for 'http' connections.
   2022-12-11 21:39:26.422156: BIP1996I: Listening on HTTP URL '/Echo'.
   ...

   From the pod logs, you can see that the deployed HTTPEcho service is listening on service endpoint /Echo.

2. Identify the external URL (that is, the public endpoint) for your service by using routes:

   oc get routes

   You should see output that is similar to this:

   NAME                        HOST/PORT                                                            PATH   SERVICES                  PORT       TERMINATION          WILDCARD
   http-echo-service-http      http-echo-service-http-ace-demo.apps.cp4i-2022-demo.cp.abc.com              http-echo-service-ir      http                            None
   http-echo-service-https     http-echo-service-https-ace-demo.apps.cp4i-2022-demo.cp.abc.com             http-echo-service-ir      https      passthrough/None     None
   

   The HOST/PORT values represent the external base URL for invoking the service.

3. Invoke the service by using the curl command to call an endpoint that is constructed from the URL for the http-echo-service-http route from the previous step, and the service endpoint /Echo.

   curl -X POST http://HOST/PORT_value/Echo

   For example:

   curl -X POST http://http-echo-service-http-ace-demo.apps.cp4i-2022-demo.cp.abc.com/Echo

   You should receive a response that is similar to the following example, which confirms that your request was successful.

   <Echo><DateStamp>2022-12-11T22:25:43.494053Z</DateStamp></Echo>