Create and edit an IBM z/OS Connect API project in Red Hat OpenShift Container Platform

Set up an IBM z/OS Connect API project with Red Hat OpenShift Dev Spaces or Red Hat OpenShift Wazi Dev Spaces.

Before you begin

zosConnect-3.0 Applies to zosConnect-3.0.

Containers Applies to z/OS Connect container deployments.

Ensure that you have access to:

Red Hat OpenShift Container Platform cluster.
Red Hat OpenShift Dev Spaces Operator 3.15.0 or later. For more information, see Installing Dev Spaces on OpenShift using the web console in the Red Hat OpenShift Dev Spaces documentation, or,
Red Hat OpenShift Wazi Dev Spaces. For more information, see Installing Red Hat OpenShift Wazi Dev Spaces in the IBM Z and Cloud Modernization Stack documentation.

About this task

Note: Where the documentation refers to Red Hat OpenShift Dev Spaces, the instructions can also be applied to Red Hat OpenShift Wazi Dev Spaces.

The task has 2 parts:

Creating the API project template for the API project development team, and check it into Source Code Management (SCM).
Figure 1. Making the API project available in Source Code Management (SCM)
Importing the API project into Red Hat OpenShift Dev Spaces, where the z/OS Connect Designer can be started.
Figure 2. Using the API project template in Red Hat OpenShift Dev Spaces

Procedure

Create the API project template.

At the command line on your workstation, change to the directory where you want to create your z/OS Connect API project.

Enter the following command to create a project workspace directory called apiProjectWorkspace.
```
mkdir apiProjectWorkspace
```
Enter the following command to change to that directory:
```
cd apiProjectWorkspace
```
In the apiProjectWorkspace directory, create the subdirectories for the API project. These subdirectories are used for Liberty server configuration files.
For Windows, enter the following command:
```
mkdir apiProject\src\main\liberty\config
```
For MacOS, enter the following command:
```
mkdir -p apiProject/src/main/liberty/config
```
The following image shows the directory structure:
```
/apiProjectWorkspace
|-- /apiProject/src/main/liberty/config
```

To configure the connection to the z/OS Connect Server, place the server configuration files in the apiProject/src/main/liberty/config directory.

For more information, see Configuring z/OS Connect for zosConnect-3.0.

The following example shows a server configuration file to authenticate the Db2® connection that is called db2.xml.

<?xml version="1.0" encoding="UTF-8" ?>
<server description="Default server">
    <featureManager>
        <feature>zosconnect:db2-1.0</feature>
    </featureManager>
    <zosconnect_credential user="${DB2_USERNAME}" password="${DB2_PASSWORD}" id="commonCredentials"/>
    <zosconnect_db2Connection id="db2Conn" host="${DB2_HOST}" port="${DB2_PORT}" credentialRef="commonCredentials"/> 
</server>

/apiProjectWorkspace
|-- /apiProject/src/main/liberty/config/db2.xml

Create a devfile.yaml and place it into the apiProject/ directory.

This file contains the configuration that is needed to create a workspace in Red Hat OpenShift Dev Spaces for the z/OS Connect API Project, and allows the IBM z/OS Connect Designer to be started.

For example,

schemaVersion: 2.3.0 
metadata: 
  name: <API_PROJECT_NAME> 
attributes: 
  controller.devfile.io/storage-type: ephemeral 
projects: 
  - git: 
      checkoutFrom: 
        revision: main 
      remotes: 
        origin: '<SOURCE_CODE_REPOSITORY>.git' 
    name: <API_PROJECT_NAME> 
components: 
  - name: tools 
    container: 
      image: registry.redhat.io/devspaces/udi-rhel8:latest 
      memoryLimit: 3Gi 
  - name: zosconnect 
    container: 
      endpoints: 
        - exposure: public 
          name: zc-ui-http 
          path: /zosConnect/designer/ 
          protocol: http 
          targetPort: 9080 
        - exposure: public 
          name: zc-ui-https 
          path: /zosConnect/designer/ 
          protocol: https 
          targetPort: 9080 
      env: 
        - name: ZCON_DESIGNER_PROJECT 
          value: /projects/<API_PROJECT_NAME>/start 
        - name: zosconnect_remote_download_allowlist 
          value: BLOCK_ALL 
      image: 'icr.io/zosconnect/ibm-zcon-designer:3.0.100' 
      memoryLimit: 4927M 
      mountSources: true

Where, <API_PROJECT_NAME> is the name of your API Project, and <SOURCE_CODE_REPOSITORY> is the name of the Git repository where your API Project is hosted. Note, the name must contain only lowercase characters and hyphens.

From 3.0.95, the zosconnect_remote_download_allowlist property is available. This devfile.yaml example shows the property configured to BLOCK_ALL. For more information about allowlist property and how to configure it, see Configuring an allowlist for IBM z/OS Connect Designer.

Validate that the API project has the following structure.

apiWorkspaceProject
└── apiProject
    ├── devfile.yaml
    └── src/main/liberty/config/db2.xml

Push the API project to the Git repository <SOURCE_CODE_REPOSITORY> hosted by a Source Code Management (SCM) solution.

Import an API project to create a Red Hat OpenShift Dev Spaces workspace from the API project template.
1. Mount the server configuration environment variables (from step 1.d) into the workspace by using a Secret and a ConfigMap.
  Access your development environment where the Red Hat OpenShift Dev Space Operator is installed. Click in the navigation bar to add the Secrets and ConfigMaps objects.
  
  Continuing with the basic authentication connection to Db2. Create the following ConfigMap and Secret objects on the Red Hat OpenShift cluster with your own data:
  For example,
```
kind: ConfigMap
apiVersion: v1
metadata:
  name: db2-connection
  namespace: <USER_DEVSPACES_NAMESPACE>
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
  annotations:
    controller.devfile.io/mount-as: env
data:
  DB2_HOST: <DB2_HOST>
  DB2_PORT: '<DB2_PORT>'
```
  Note: ConfigMap data values are accepted only as a string. Ensure that all numeric data is input within quotations. For example, DB2_PORT : '1234'
```
kind: Secret
apiVersion: v1
metadata:
  name: db2-credentials
  namespace: <USER_DEVSPACES_NAMESPACE>
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
  annotations:
    controller.devfile.io/mount-as: env
stringData:
  DB2_USERNAME: <DB2_USERNAME>
  DB2_PASSWORD: <DB2_PASSWORD>
```
  Where, <USER_DEVSPACES_NAMESPACE> is the namespace in which the Red Hat OpenShift Dev Spaces is hosted for the active user. You can go to https://<openshift_dev_spaces_fqdn>/api/kubernetes/namespace to get your Red Hat OpenShift Dev Spaces user namespace as name. For more information, see Integrating with OpenShift in the Red Hat OpenShift Dev Spaces documentation.
  
  For more information, see Mounting Secrets and Mounting ConfigMaps.
2. Access Red Hat OpenShift Dev Spaces.
  
  Figure 3. Red Hat OpenShift Dev Spaces home page
3. Import from Git.
  
  Note: The following entries are an example from the z/OS Connect sample API project: https://github.com/zosconnect/sample-db2-api. Substitute these with your own values.
  Enter the repository URL for the z/OS Connect API project in SCM in Git repo URL.
  https://github.com/zosconnect/sample-db2-api
  Open Git Repo Options.
  Figure 4. Options in the Import from Git screen
  Enter the branch of the repository where the devfile is located in Git Branch.
  main
  Enter the relative path to the devfile in the Git repository in Path to Devfile.
  start/devfile.yaml
  The Git repo URL is constructed as the following.
  https://github.com/zosconnect/sample-db2-api/tree/main?devfilePath=start/devfile.yaml
  Click Create & Open.
4. The new workspace opens. Click Open in New Tab to open the z/OS Connect Designer.
  
  Note: It might take a few minutes for the z/OS Connect Designer to start, and Open in New Tab to appear.
  
  Figure 5. Open z/OS Connect Designer in Red Hat OpenShift Dev Spaces

Results

You successfully created a Red Hat OpenShift Dev Spaces workspace for the z/OS Connect API project.