Scenario 2: Deploy an IBM App Connect Enterprise Toolkit integration on Red Hat OpenShift by using the App Connect Dashboard

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.

Also, ensure that you have completed Scenario 1: Deploy an IBM App Connect Enterprise Toolkit integration on Red Hat OpenShift by using the command-line interface (CLI), which includes information about installing the IBM App Connect Operator.

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

• The App Connect Dashboard

  You will learn about the purpose of the App Connect Dashboard, and create a Dashboard instance with a required display mode that lets you administer integration runtimes.

• Content server

  Scenario 1 describes how to deploy a BAR file from an external repository to a container. In Scenario 2, you will learn how to use the Dashboard's internal content server as an alternative storage repository for BAR files. You will upload your BAR file for storage, and see how it's selected for deployment.

• Configuration objects

  Configuration objects are introduced in Scenario 1, which describes how to create a configuration object from the CLI. In Scenario 2, you will learn how configuration objects can be created from a Dashboard instance.

• Deployment of the message flow to an integration runtime by using the App Connect Dashboard

  You will learn how to use the Dashboard to complete the deployment.

The App Connect Dashboard is a user interface that provides a simplified way to deploy BAR files to IBM App Connect containers, and to administer the deployed integration servers or integration runtimes. Some of the facilities that the App Connect Dashboard provides are as follows:

• Offers a user interface that you can step through to deploy a BAR file to a container.
• Provides an internal content server for hosting your BAR files for deployment.
• Provides a simplified way to create and view the YAML definition for an integration server or integration runtime, including the facility to create and reference any configuration objects that need to be applied.
• Provides a view of the integration servers or integration runtimes that are deployed in containers, and enables you to drill down to the individual message flows within them.
• Enables you to update the settings for your deployed integration servers or integration runtimes (for example, change the number of replicas, or update the BAR files or configuration objects). Also enables you to change or upgrade to a different fix pack version, or delete integration servers or integration runtimes that you no longer need.

  This capability is not unique to the Dashboard, but can also be done from the command line.

The App Connect Dashboard clearly provides some powerful convenience features, but does require installation and also slightly increases the footprint on your installation. As a result, the Dashboard is offered as an optional resource, and some users might prefer to use the Red Hat OpenShift command line or web console to deploy integration servers or integration runtimes.

The App Connect Dashboard is provided as part of an IBM App Connect Operator installation, so it is assumed that you have installed this Operator as described in Scenario 1. For more information, see Introducing the IBM App Connect Operator.

The Operator doesn't automatically create or install an instance of the App Connect Dashboard (or any of the other custom resources), so you’ll need to now create the Dashboard instance that you'll use for the deployment.

Before you create a Dashboard instance, it's worth noting the following considerations:

• Decide what type of storage to use for BAR files that you'll upload or import to the Dashboard. The following storage types can be used to allocate storage for the content server:
  • Ephemeral storage: The files are stored on the Dashboard’s internal file system. Although a simple configuration, any loaded BAR files are deleted if the Dashboard instance is restarted.
  • Long-term storage: The files are stored on a persistent volume that is provisioned for the container, or on an existing Simple Storage Service (S3) storage system to which you have access. This long-term storage option requires more configuration to set up storage classes or buckets, but ensures that the BAR files are retained if the Dashboard restarts.

  After you create a Dashboard instance, you cannot change its storage type.

• Decide what type of display mode (IntegrationServers or IntegrationRuntimes) you want to assign to the Dashboard. This mode determines whether you can use the Dashboard to display and deploy integration servers only, or integration runtimes only.

  After you create a Dashboard instance, you can switch its display mode, but only instances of the selected type will be visible in that mode.

You can create an App Connect Dashboard instance from the IBM Cloud Pak for Integration Platform UI, or the Red Hat OpenShift web console or CLI. For this simple scenario, you can create your Dashboard instance with ephemeral storage because it's the quicker and simpler option. Also set the display mode to IntegrationRuntimes because you are going to deploy the BAR file to an integration runtime. A sample YAML definition that was used to create the Dashboard for these instructions is as follows:

apiVersion: appconnect.ibm.com/v1beta1
kind: Dashboard
metadata:
  name: ace-dashboard
  namespace: ace
spec:
  license:
    accept: true
    license: L-APEH-CJUCNR
    use: CloudPakForIntegrationProduction
  pod:
    containers:
      content-server:
        resources:
          limits:
            memory: 512Mi
          requests:
            cpu: 50m
            memory: 50Mi
      control-ui:
        resources:
          limits:
            memory: 512Mi
          requests:
            cpu: 50m
            memory: 125Mi
  storage:
    size: 5Gi
    type: ephemeral
  replicas: 1
  useCommonServices: true
  version: '12.0'
  displayMode: IntegrationRuntimes

For more information about creating a Dashboard instance, see the App Connect Dashboard reference in the IBM App Connect in containers documentation.

You can access the Dashboard instance from the Platform UI in your IBM Cloud Pak for Integration environment, or from the Red Hat OpenShift web console.

Accessing the Dashboard from the Platform UI

When you log in to the Platform UI, you can directly open the App Connect Dashboard instance from a card on the home page. Locate the Integrations card and then click the name of the Dashboard instance that you want to access.

Accessing the Dashboard from the Red Hat OpenShift web console

From the namespace (or project) where you created the App Connect Dashboard instance (under Operators > Installed Operators > IBM App Connect), click the Dashboard tab and then click the Dashboard name.

On the Details tab of the Dashboard details view, the Admin UI field provides the URL for accessing the Dashboard instance. You can right-click this URL and then use the Open link in new tab option to open the Dashboard on a separate tab.

The Dashboard home page displays the following tiles:

• A Deploy integrations tile that you can use to create an integration runtime
• A Learn more tile that you can use to view the IBM App Connect in containers documentation
• A Runtimes tile that indicates how many integration runtimes are running, and which you can use to view the deployed runtimes
• An Integrations tile that indicates how many integration applications are currently deployed for the integration runtimes, and which you can use to view these integrations

  The Runtimes and Integrations tiles are shown only if integration runtimes have been deployed.

You can use the navigation menu for alternative access to your deployed instances and for access to the administrative functions.

The navigation pane provides the following default access:

Icon	Description
Home	Displays the home page and tiles to deploy integrations, access the documentation, and access any available integrations runtimes and underlying integrations.
Dashboard	Displays the dashboard UI from where you can deploy and view integrations.
Configuration	Displays the Configuration page from where you can create and manage configuration objects.
BAR files	Displays the BAR files page from where you can manage BAR files that are stored in the content server. You can import, replace, delete, back up, or restore BAR files, and can also view the URL of the location where a BAR file is stored in the content server.

In Scenario 1, you deployed a BAR file (HttpEchoApp.bar) that is hosted on the public GitHub location at https://github.com/amarIBM/hello-world. You are now going to deploy this BAR file by using the App Connect Dashboard. You will upload the BAR file to the Dashboard's internal content server for storage instead of referencing the file from an external location.

The file is provided as an attachment for your use: HttpEchoApp.zip. Download this attachment and then extract its contents to a directory on your local computer. This ZIP file contains the HttpEchoApp.bar file, which you will use in the next procedure.

Finally, you are ready to deploy the simple flow. You will use the App Connect Dashboard to upload the BAR file to the internal content server and then configure properties for the integration runtime.

1. From the home page of the App Connect Dashboard, start the integration runtime deployment by clicking the Deploy integrations tile.
   Tip: You can also start the deployment from the navigation pane, by clicking the Dashboard icon to open the Runtimes page, and then clicking Deploy integrations.
2. From the Size view, click the Quick start integration tile because you are deploying a BAR file that contains a simple integration.

   (The tiles in this view present different sizing options, and you can review the sizings on each tile to help you choose a suitable option for the integration that you want to run. These integrations can typically originate from either App Connect Designer or the IBM App Connect Enterprise Toolkit.)

   
3. Click Next to proceed.
4. From the Integrations view, upload the HttpEchoApp.bar file (which you downloaded earlier) to the Dashboard's content server. You can drag this file into the boxed area, or click to select and upload the file from its extracted location.
   
5. Click Next to proceed to the Configuration view, which can be used to define dynamic configurations that you would like to apply to integration runtimes that you are deploying.
   

   In Scenario 1, you required a configuration object because the App Connect container needed credentials for authenticating to the GitHub location of the hosted BAR file. Because the container will now use a BAR file from the Dashboard's content server, and the message flow does not need to connect to any resources at run time, a configuration object is not required. Therefore, you can skip this stage and proceed to the final step of the deployment process.

   Tip:

   • If you have an App Connect Designer instance in the same namespace as your Dashboard, the configurations table will include configurations that were automatically created when the Designer instance was created. These configurations will be prefixed with the name of the Designer instance. Do not delete them.
   • Where required, you can create configuration objects from the Configuration view by clicking Create configuration to open the Create configuration panel. You can then select the type of configuration that you want to create and specify the content to store in the configuration object. For more information about the configuration types that you can create from the Dashboard, see Learn more about the configuration types in the IBM App Connect in containers documentation.

     To apply one or more configuration objects to your integration runtime, you must ensure that the check boxes for those configuration objects are selected in the configurations table before you click Next to proceed to the Properties view.

6. Click Next to proceed to the Properties view, where you can provide metadata for your integration runtime and install the BAR file resources. Specify the following values and retain the default values in any remaining fields. (Notice that you do not need to specify a namespace because the integration runtime is automatically deployed in the same namespace as the Dashboard.)
   • Name: simple-echo-app

     Specifies a unique name for this integration runtime.

   • Channel or version: 12.0

     Specifies an App Connect product (fix pack) version that the integration runtime is based on. In this case, you are selecting a channel, which will ensure that the latest fix pack of 12.0 M (V.R.M) is used for the deployment, but you can alternatively choose a specific (fully qualified) version such as 12.0.7.0-r2 if preferred. For more information about these values, see spec.version values.

     
   • License: Select the appropriate values for the license identifier and type from the License LI and License use drop down lists.

     These values must align with the channel or fully qualified version that you selected from the Channel or version drop-down list. For more information, see Licensing reference for IBM App Connect Operator.

   • Replicas: 2

     Specifies the number of replica pods to run for this deployment. In this case, you are setting the value to 2 for high availability. You'll explore this some more while testing the message flow later.

   Tip:

   Notice that the BAR URL field is automatically populated with the location where the HttpEchoApp.bar file is stored in the content server.

   For cases where you want to deploy multiple BAR files to an integration runtime, you can use the Add link in the BAR URLs section to specify the location of each file. (If the BAR files are stored in an external repository, you'll also need to create a configuration object of type BarAuth to store the required authentication credentials.)

   The property settings for this integration runtime are similar to the settings that you specified in the YAML definition file for the integration runtime that you deployed from the CLI in Scenario 1. You can click the YAML editor tab to view (and even edit) this YAML format, which can also be used for deployment from the CLI, or used in scripts for deployments that use continuous integration and continuous delivery (CI/CD) pipelines to automate and manage DevOps processes.

   
7. Click Create to create the integration runtime.

   When the deployment completes, the integration runtime is displayed as a tile on the Runtimes page. The status, which is initially shown as Pending, will change to Ready when the deployment completes. (Refresh the page to see the change in status.) You'll notice that the integration runtime tile displays 2/2 replicas to indicate that two replicas are currently configured and running.

   
8. Drill down into the integration runtime to view the deployed applications and the message flows under each application. To do so, click the integration runtime tile on the Runtimes page to view the tile and tabs for the defined application. Then, click the application tile to view the tile and tabs for the message flow.

   (From the Runtimes page, you can also view all deployed integrations by clicking the Integrations tab to open the Integrations page.)

   

Verify the status of your application by looking at the pod log for the deployed container and then invoke the service by using routes. To look at the pod log, you'll need to log in to the cluster from the Red Hat OpenShift CLI.

1. Log in to your cluster.

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

   Tip: One way to obtain the login command on Red Hat OpenShift Container Platform is to use the Copy login command option in your profile menu to display or request an API token. Login credentials for the cluster are required to view this token.

   
2. If necessary, switch to the namespace (or project) where the integration runtime is deployed.

   oc project namespaceName

3. Identify the name of the integration runtime pod.

   oc get pods

   You should see output that is similar to this:

   NAME                                        READY   STATUS    RESTARTS   AGE
   ace-dashboard-dash-66959bf5c4-mjd85         2/2     Running   0          12h
   custom-db-service-ir-67c7854f86-dxfbh       1/1     Running   0          12h
   designer-test-service-ir-7d8dfbf8fd-4lt56   2/2     Running   0          12h
   simple-echo-app-ir-65df8d9bb-574nw          1/1     Running   0          12h
   simple-echo-app-ir-65df8d9bb-ppjfh          1/1     Running   0          12h
   test-echo-app-ir-dff559ccb-hp8nq            1/1     Running   0          69m
   test-echo-app-ir-dff559ccb-w9rdx            1/1     Running   0          69m

   You’ll notice that there are two pod entries named simple-echo-app-ir-* because you set the number of replica pods to 2 (for high availability) while defining the integration runtime settings in the Properties view. The STATUS column also has a value of Running.

   You can also verify the status of your application by looking at the log for either of the simple-echo-app-ir-* pods:

   oc logs podName

   For example:

   oc logs simple-echo-app-ir-65df8d9bb-574nw

   You should see output that is similar to this:

   2022-12-12T10:18:56.171Z Image created: 2022-11-30T09:16:41+00:00
   2022-12-12T10:18:56.174Z ACE version: 12.0.7.0
   ...
   
   2022-12-12T10:18:57.211Z Will save bar as: /home/aceuser/initial-config/bars/barfile.bar
   2022-12-12T10:18:57.211Z Getting configuration from content server
   2022-12-12T10:18:57.211Z Using the following url: https://ace-dashboard-dash.ace:3443/v1/directories/HttpEchoApp?archive=true
   ...
   2022-12-12 10:18:58.797240: BIP9906I: Reading deployed resources.
   2022-12-12 10:18:58.802280: BIP9907I: Initializing deployed resources.
   2022-12-12 10:18:58.803604: BIP2155I: About to 'Initialize' the deployed resource 'HTTPEcho' of type 'Application'.
   2022-12-12 10:18:58.883200: BIP2155I: About to 'Start' the deployed resource 'HTTPEcho' of type 'Application'.
   An http endpoint was registered on port '7800', path '/Echo'.
   2022-12-12 10:18:58.927056: BIP3132I: The HTTP Listener has started listening on port '7800' for 'http' connections.
   2022-12-12 10:18:58.927200: BIP1996I: Listening on HTTP URL '/Echo'.
   ...

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

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

   oc get routes

   You should see output that is similar to this:

   NAME                          HOST/PORT                                                        PATH   SERVICES                   PORT         TERMINATION          WILDCARD
   ace-dashboard-ui              ace-dashboard-ui-ace.apps.cp4i-2022-demo.cp.abc.com                     ace-dashboard-dash         control-ui   reencrypt/Redirect   None
   custom-db-service-http        custom-db-service-http-ace.apps.cp4i-2022-demo.cp.abc.com               custom-db-service-ir       http                              None
   custom-db-service-https       custom-db-service-https-ace.apps.cp4i-2022-demo.cp.abc.com              custom-db-service-ir       https        passthrough/None     None
   designer-test-service-http    designer-test-service-http-ace.apps.cp4i-2022-demo.cp.abc.com           designer-test-service-ir   http                              None
   designer-test-service-https   designer-test-service-https-ace.apps.cp4i-2022-demo.cp.abc.com          designer-test-service-ir   https        passthrough/None     None
   simple-echo-app-http          simple-echo-app-http-ace.apps.cp4i-2022-demo.cp.abc.com                 simple-echo-app-ir         http                              None
   simple-echo-app-https         simple-echo-app-https-ace.apps.cp4i-2022-demo.cp.abc.com                simple-echo-app-ir         https        passthrough/None     None
   test-echo-app-http            test-echo-app-http-ace.apps.cp4i-2022-demo.cp.abc.com                   test-echo-app-ir           http                              None
   test-echo-app-https           test-echo-app-https-ace.apps.cp4i-2022-demo.cp.abc.com                  test-echo-app-ir           https        passthrough/None     None

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

5. Invoke the service URL from a browser address bar. You can construct the endpoint URL from the URL for the simple-echo-app-http route from the previous step, and the service endpoint /Echo.

   http://HOST/PORT_value/Echo

   For example:

   http://simple-echo-app-http-ace.apps.cp4i-2022-demo.cp.abc.com/Echo

   The response should look like this, which indicates that you successfully invoked your deployed flow.

   <Echo>
   <DateStamp>2022-12-12T22:42:39.714521Z</DateStamp>
   </Echo>

   

By completing this deployment from the App Connect Dashboard, you can see that the Dashboard enables you to perform the same actions on the underlying Kubernetes platform as you completed by using the command line. You can switch between the CLI and the Dashboard user interface as preferred, and should observe that the results of any actions in one interface are reflected in the other.