Skip to main contentIBM Cloud Pak Playbook

App Connect

Overview

Once you have the Cloud Pak for Integration, you will have many capabilities that are available for deployment. To experience these capabilities, the Cloud Pak provides the Platform Navigator user interface. This interface isn’t likely to be used by a developer to deploy new workload, but it can be helpful for you as a new user to become familiar with some of the provided capabilities within the Cloud Pak or to socialize these capabilities within your teams. The Platform Navigator also has convenient interfaces to inspect your deployed integration instances.

The Platform Navigator

If you are looking to deploy your first App Connect instance, it is assumed that you have already installed the Cloud Pak for Integration. If you have not, you may wish to start with the Overview and Requirements before proceeding to the Installation. Once you have completed the installation come back to deploy your first App Connect instances.

If you have not yet accessed the Platform Navigator for the Cloud Pak for Integration you may need to first find the URL. This is not the same as the Cloud Pak Common Services dashboard URL given to you at the end of the Cloud Pak installation process. If you (or your administrator) just installed the Cloud Pak you can easily find the URL by looking up the Route. You will need to first authenticate to the OpenShift cluster from your oc command line or or by using the OpenShift Container Platform User Interface.

From OCP you can run the following command:

oc get routes -n integration

This will list the ibm-icp4i-prod route used to provide access into the platform’s UI for the Cloud Pak. Paste the HOST/PORT value into your browser.

Alternatively, from the OCP UI, navigate to Networking -> Routes and change to the integration project to find this route or URL.

OCP-Routes

You can authenticate to the UI using the admin credential you configured during install, or more preferably using an alternate User ID that you or your cluster administrator have configured.

You can either tour the product from the Welcome screen or Skip to the normal experience. This steps outlined below start from the screen displaying “Lets get you going!”.

CP4I-Navigator

Deploy the App Connect Dashboard

To aid in the deployment of your first flow, start by creating an instance of the App Connect Dashboard. If this step has already been performed, proceed to the next section.

From the Platform Navigator chose the tile for creating an instance of App Connect.

create-instance-app-connect

Continue by selecting the tile for App Connect Dashboard.

create-dashboard

The Dashboard is a tool that you can use to deploy services while you familiarize yourself with the App Connect and the Cloud Pak and prior to setting up your CI toolchain. You may also use this for an easy way to socialize some of the capabilities with your teammates.

After selecting the above action you are presented with a screen that makes some statements about the project space you wish to deploy into, security context constraints, image pull secret and persistent volume storage requirements.

If you are relatively new to OpenShift, it is important to understand that when you deploy something to run within your cluster, it is run within a given namespace / project. This project space must have some prerequisites met to be able to run your application. Users / service accounts must exist with the correct permission to perform certain actions. This example assumes you are using the ace project namespace that was created as part of the Cloud Pak installation. This namespace already has some default security settings configured.

Your project’s namespace must also have access to pull the required container images from a suitable image repository. If your cluster has access to the IBM Entitled Registry, and you wish to deploy the Dashboard using the online image follow the Online instructions. To pull the images from your private registry follow Private.

Log in to MyIBM Container Software Library with the IBM ID and password that are associated with the entitled software. In the Entitlement Keys section, copy the entitlement key.

Create the secret for your project (in this case ace) pulling images with the following command:

oc project ace
create secret docker-registry ibm-entitlement-key --docker-username=cp --docker-password=<entitlement-key-goes-here> --docker-server=cp.icr.io

When deploying the Dashboard component, you will provide the name of this secret(ibm-entitlement-key) as the imagePullSecret.

Next, create the Helm TLS secret that will be used to deploy into your project namespace. This requires a few steps:

  • Log into your Cloud Pak common services API using the cloudctl CLI found here. The URL was given at the end of install otherwise can be found in the same manner we discovered the route above to the Cloud Pak for Integration Platform Navigator. oc get routes | grep management-ingress
  • Choose the correct project / namespace that you wish to deploy into (or run oc project ace assuming the ace project)
  • Create the secret by running the following (again assuming you are using the ace namespace):
kubectl create secret generic ibm-ace-dashboard-icp4i-prod-helm-certs --from-file=cert.pem=$HOME/.helm/cert.pem --from-file=ca.pem=$HOME/.helm/ca.pem --from-file=key.pem=$HOME/.helm/key.pem --namespace=ace

Since this application requires a persistent volume for storing state, the final piece of information you will need prior to deploying the service is the name of the storage class associated with your file storage provider with READ-WRITE-MANY access. When you or your cluster administrator installed the Cloud Pak you would have also used a similar storage provider except it was likely for block storage. You can find a list of storage classes already configured within cluster:

oc get sc

If there isn’t one available work with the cluster administrator to configure an applicable file storage provider that allows for RWX access. Alternatively you can preconfigure a Persistent Volume Claim manually prior to deploying the Dashboard.

Once these prerequisite steps have been completed continue to the chart configuration by choosing next.

Use the following set of parameters to provide a basic deployment of the feature:

  • Provide a name for the Helm release such as: my-ace-dashboard
  • The target namespace (recommend to use the prepared ace namespace while learning the product): ace
  • Target cluster: local-cluster
  • Provide the Helm TLS secret name you created earlier: ibm-ace-dashboard-icp4i-prod-helm-certs
  • Accept the license agreement

Open the All parameters section and scroll to the Docker image information

  • Verify the image-registry / image settings. This will show you which registry the image is being pulled from and the specific name and version of the image. The registry used will relate to the method you chose above when setting / locating your imagePullSecret.
  • Enter the value for your the name of your imagePullSecret (this example is for online see above for private ie. deployer-dockercfg-XXXXX): ibm-entitlement-key

Scroll down to find the section for Persistent storage configuration

  • Only provide the PersistentVolumeClaim name if you are not using dynamic provisioning (it is suggested to use dynamic provisioning / storage class for new users especially)
  • Under Persistent storage class provide your class representing file storage for READ-WRITE-MANY access (this example is for RedHat OpenShift Kubernetes Service on IBM Cloud): ibmc-file-gold

After selecting Install you can find the Helm chart components being deployed by visiting your OCP Administrator interface. You can also log into the Cloud Pak User Interface provided by Common Services. From within that UI use the hamburger menu in the upper left view Helm Releases.

cpcs-ui-helm-releases

This option allows you to view and perform actions against your Helm releases.

When it completes you will be able to access the App Connect Dashboard from the Platform Navigator under the View instances tab.

Deploy the App Connect Designer

With the App Connect Dashboard deployed you know have the capability to run integration flows in the form BARs on App Connect server instances within your cluster. Agile integration developers will typically download and use the Eclipse based IBM App Connect Enterprise Toolkit. Conversely, a low-code alternative for demonstrating product features is the App Connect Designer. This interface provides a very easy way to create and export basic flows that run in App Connect instances.

From the Cloud Pak for Integration Platform Navigator choose the tile for creating an instance of App Connect. Continue by selecting the tile for App Connect Designer.

cp4i-create-app-connect-designer

After selecting the above action you are presented with a screen that provides prerequisite information about the project space you wish to deploy into, security context constraints, image pull secret and persistent volume storage requirements.

In in the previous deployment section for the App Connect Dashboard, you already applied the security context constraint and added the imagePullSecret to the target project / namespace (it is assumed you are using the same namespace). Remember the imagePullSecret used depends on the type of installation you wish to perform, meaning is the image in a local registry (private) or being pulled from the IBM Entitled Registry (online). See the corresponding tab to review how you configured this in the previous section.

Log in to MyIBM Container Software Library with the IBM ID and password that are associated with the entitled software. In the Entitlement Keys section, copy the entitlement key.

Create the secret for your project (in this case ace) pulling images with the following command:

oc project ace
create secret docker-registry ibm-entitlement-key --docker-username=cp --docker-password=<entitlement-key-goes-here> --docker-server=cp.icr.io

When deploying the component, you will provide the name of this secret (ibm-entitlement-key) as the imagePullSecret.

The App Connect Designer requires a persistent volume for storing state. Prior to deploying the service find the name of a storage class associated with a suitable block storage provider with READ-WRITE-ONE access. When you or your cluster administrator installed the Cloud Pak you would have likely used this storage class. You can find a list of storage classes already configured within cluster:

oc get sc

If there isn’t one available work with the cluster administrator to configure an applicable block storage provider that allows for RWO access. Alternatively, you can preconfigure a Persistent Volume Claim manually prior to deploying the Dashboard.

Once these steps have been completed continue to the chart configuration by choosing next.

Use the following set of parameters to provide a basic deployment of the feature:

  • Provide a name for the Helm release such as: my-ace-designer
  • The target namespace (recommend to use the prepared ace namespace): ace
  • Target cluster: local-cluster
  • Accept the license agreement

Open the All parameters section and scroll to the Docker image information

  • Verify the image-registry/image settings. This will show you which registry the image is being pulled from and the specific name and version of the image. The registry used will relate to the method you chose above when setting/finding your imagePullSecret.
  • Enter the value for your the name of your imagePullSecret (this example is for online see above for private ie. deployer-dockercfg-XXXXX): ibm-entitlement-key
  • Repeat the above step for the Values for the server container section to specify where the ACE Server and related images are to be pulled from and the imagePullSecret

Scroll down to find the section for Persistent storage configuration

  • Under Persistent storage class provide the storage class representing bock storage for READ-WRITE-ONE access (this example is for RedHat OpenShift Kubernetes Service on IBM Cloud): ibmc-block-gold

After selecting Install you can find the Helm chart components being deployed by visiting your OCP Administrator interface. You can also log into the Cloud Pak UI provided by Common Services and from the hamburger menu in the upper left view Helm Releases.

When the Helm release deployment completes you will be able to access the App Connect Designer from the Cloud Pak for Integration Platform Navigator under the View instances tab.

Using App Connect Designer

Your next step is to begin using the App Connect Designer. The Knowledge Center for the Designer shows you how to create, export, import and deploy flows.

Deploying Flows via the Dashboard

Once you have an API flow that you created in the App Connect Designer or IBM App Connect Enterprise Toolkit, you are able to create a BAR file that can be run using the App Connect Server. The Knowledge Center shows you how to easily run BARs from the App Connect Dashboard. As mentioned above, to learn a best-practice for deploying APIs via OpenShift Pipelines, see this GitHub repository.