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

This scenario describes how to deploy a simple IBM® App Connect Enterprise Toolkit flow into a containerized environment on Red Hat OpenShift. You will use the command-line interface (CLI) to perform the deployment.

Prerequisites for deployment

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 description

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

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.

Enabling the remote pull (or retrieval) of the BAR file from an external repository

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 cluster, and then reference this configuration object when you deploy the container.

Introducing configuration objects

Configuration objects are a mechanism that you can use to pass to a container any environment-specific information that it needs at run time. Integrations within an IBM Integration Bus or IBM App Connect Enterprise environment typically require a connection to servers or entities such as databases, queues, FTP servers, or TCP/IP sockets. Each connection requires authentication credentials, certificates, or other properties, which will have different values based on the environment that you are deployed to.

If you have an existing IBM Integration Bus or IBM App Connect Enterprise environment, you’ll be familiar with mechanisms such as these:

odbc.ini files for defining database connection properties
The mqsisetdbparms command for setting up authentication credentials for the various systems that you connect to

To make these same credentials and properties available to your container, you can create configuration objects of various types to store the details. The list of configuration types that you can create for integration runtimes (and integration servers) is provided in Learn more about the configuration types.

The simple message flow in this scenario doesn't connect to anything at run time. However, the container itself will need credentials for connecting to the GitHub location to get the BAR file on startup. Therefore, you need to create a configuration object to meet this requirement.

Creating a configuration object from the CLI

You can create a configuration object like any other object in Kubernetes by using a set of values in a YAML-formatted text file. Within this file, you must specify the credentials or properties that you want to store as Base64-encoded data.

Prepare the authentication credentials for the GitHub location. You can specify the credentials in the following JSON format:
```
{"authType":"BASIC_AUTH","credentials":{"username":"myUsername","password":"myPassword"}}
```
In this string, myUsername and myPassword are the username and password that can be used to connect to the URL where the BAR file is located. Because the BAR file is in a public GitHub location, a username and password are not required. So you can simply specify the credentials by passing empty values:
```
{"authType":"BASIC_AUTH","credentials":{"username":"","password":""}}
```
Base64 encode the authentication credentials because they need to be in this format within the YAML file that you will define later to create the configuration object.
One way to Base64 encode data is to do so directly from the command line:
```
echo '{"authType":"BASIC_AUTH","credentials":{"username":"","password":""}}' | base64
```
The Base64-encoded output is as follows:
```
eyJhdXRoVHlwZSI6IkJBU0lDX0FVVEgiLCJjcmVkZW50aWFscyI6eyJ1c2VybmFtZSI6IiIsInBhc3N3b3JkIjoiIn19Cgo=
```
Make a note of this value to use in the next step.
On your local computer, create the YAML definition file for the configuration object. Add the following YAML content to a text file named github-barauth.yaml:
```
apiVersion: appconnect.ibm.com/v1beta1
kind: Configuration
metadata:
  name: github-barauth
  namespace: ace-demo
spec:
  data: eyJhdXRoVHlwZSI6IkJBU0lDX0FVVEgiLCJjcmVkZW50aWFscyI6eyJ1c2VybmFtZSI6IiIsInBhc3N3b3JkIjoiIn19Cgo=
  description: Authentication for GitHub
  type: barauth
```
The parameter settings to note are as follows:
- The kind parameter indicates that you want to create a Configuration object.
- The name parameter specifies a unique name for this configuration object. You will use this value to reference this configuration object later when you create the integration runtime.
- The namespace parameter identifies the namespace where the IBM App Connect Operator is installed and where you want to deploy the integration runtime. (On Red Hat OpenShift, a namespace is also referred to as a project.)
  Note: In these instructions, we are using a namespace called ace-demo, which will be reflected in the sample output of some commands that are run later. You can replace ace-demo with the namespace where you installed your IBM App Connect Operator.
- The data parameter specifies the Base64-encoded credentials from the previous step.
- The type parameter of barauth indicates that you are specifying authentication credentials to use for retrieving a BAR file from a remote URL endpoint.
  For more information about the barauth configuration object, see BarAuth type.
Log in to the Red Hat OpenShift cluster.
The following example shows the format of a login command that is based on an API token:
```
oc login --token=xxxxxxxxx  --server=https://yyyyyy.abc.com:6443
```
Tip: One way to obtain a login command from the Red Hat OpenShift Container Platform web console 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.

After you log in, switch to the namespace (or project) where the Operator is installed if necessary:
```
oc project namespaceName
```
Create the configuration object in the cluster by running the following command to apply the YAML file that you created earlier.
```
oc apply -f github-barauth.yaml
```
The command should produce the following output:
```
configuration.appconnect.ibm.com/github-barauth created
```
You can check the status of your configuration object or list all the configuration objects that you have created by using following command:
```
oc get configuration
```
You should see output that is similar to this:
```
NAME                                          AGE
github-barauth                                7m48s
```

Deploying the BAR file to an integration runtime by using 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.

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.
  Note: The value of spec.license.use is set to CloudPakForIntegrationNonProductionFREE because these instructions were completed within an IBM Cloud Pak for Integration environment. If you are using an independent deployment of the IBM App Connect Operator, set spec.license.use to AppConnectEnterpriseProduction or AppConnectEnterpriseNonProductionFREE instead.
- 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 in the 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.
Log in to your 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.
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
```

Testing the message flow

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

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.

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.

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>
```

Next steps

In this scenario, you deployed a simple flow from an IBM Integration Bus or IBM App Connect Enterprise environment into a container by using the Red Hat OpenShift CLI. You can now proceed to Scenario 2 to learn how to deploy the same BAR file by using the App Connect Dashboard.