Install the IBM z/OS Connect Server zosConnect-3.0 feature image to a Red Hat OpenShift Container Platform

1. Start your container tool.
   For example, Docker.
2. Log in to IBM Cloud Container Registry.

   docker login icr.io

   Provide your username and password login credentials. Instructions for obtaining these credentials can be found in your license documents.
3. Pull the z/OS Connect Server image.

   docker pull icr.io/zosconnectunlimited/ibm-zcon-server:3.0.100

docker image ls

REPOSITORY                                  TAG        IMAGE ID    CREATED     SIZE
icr.io/zosconnectunlimited/ibm-zcon-server 3.0.100    6d2af17d10bd  1 days ago   979MB

Digital signatures provide a way to ensure that an image is both authentic (it originated from the expected source) and has integrity (it is what is expected). z/OS Connect images are signed and this topic describes how to verify the signatures on those images.

1. Import the z/OS Connect public key on the machine that you prepared according to the Prerequisites section:

   sudo gpg --import PRD0012028key.pub.asc

   This step needs to be done only once on each machine you use for signature verification.
2. Calculate the fingerprints:

   fingerprint=$(sudo gpg --fingerprint --with-colons | grep -B1 'IBM z/OS Connect Enterprise Edition Unlimited' | grep fpr | tr -d ‘fpr:’)

   This command stores the keys' fingerprint in an environment variable that is called fingerprint, which is needed to verify the signature. When you exit your shell session, the variable is deleted. The next time that you log in to your machine, you can set it again by rerunning the command.

3. Log in to Skopeo.

   sudo skopeo login icr.io

4. Create a directory for the image and use skopeo to pull it into local storage:

   mkdir images

   sudo skopeo copy docker://icr.io/zosconnectunlimited/ibm-zcon-server:3.0.100 dir:./images -a

   This command downloads the image as a set of files and places them in the images directory (or another directory that you choose). If the source image is a list of images for different architectures, the -a attribute copies all of the images.

   Tip: One of these files is a manifest file that is named images/manifest.json, and a signature file named images/signature-1. You reference both these files in the next step (in the command to verify the signature).
5. Verify the signature:

   sudo skopeo standalone-verify ./images/manifest.json icr.io/zosconnectunlimited/ibm-zcon-server:3.0.100 ${fingerprint} ./images/signature-1

   The confirmation output should be similar to the following where the sha256 value is a 64-byte hexadecimal string.

   Signature verified, digest sha256:0000000000000000000000000000000000000000000000000000000000000000

1. Make sure that your container build environment is running.
2. Go to the root of your z/OS Connect API project.
3. Ensure that the Dockerfile within the z/OS Connect API project references your downloaded z/OS Connect Server image in the FROM instruction.
   For example,

   
   FROM icr.io/zosconnectunlimited/ibm-zcon-server:3.0.100
   

   Note: The tag references the specific version of the z/OS Connect Server image that is being used. Using the tag `latest` adds the risk of updating the image automatically, and a newer version is used on later builds.
4. Log in to the private Container Registry.
   Note: This is not the IBM Cloud Container Registry, but the registry where you host your z/OS Connect API image.
   For example,

   docker login example.io

5. From the same location as the Dockerfile, build the z/OS Connect API image locally.
   By using Docker, the following command is an example where,

   • example.io is the Container Registry.
   • zcon-employees-api is the chosen image name.
   • v1.0.0 is the image tag.

   The command is run from the same location as the Dockerfile.

   docker build -t example.io/zcon-employees-api:v1.0.0 .

   Note: The trailing period '.' in the command states to use the current directory as the build context.
   This z/OS Connect API image is now stored locally in the private container. In this example, the z/OS Connect API image is stored locally in the Docker private container.
   Important: The z/OS Connect API image is a multi-architecture image and defaults to an architecture that matches the system on which it is built. To build a z/OS Connect API image with a different architecture to your build system, use docker build --platform <os/arch> to specify the target platform for the build output. For example,

   docker build --platform linux/amd64 -t example.io/zcon-employees-api:v1.0.0 .

   For more information, see Building multi-platform images.

6. Push the z/OS Connect API image to the remote private Container Registry.

   For example,

   docker push example.io/zcon-employees-api:v1.0.0

   Note: Using the tag latest adds the risk of updating the image automatically when deployed with Red Hat OpenShift.

1. Log in as cluster-admin to the Red Hat OpenShift Container Platform web console, and ensure that you are using the Administrator perspective by using the left navigation.
2. Click to open the import YAML page.
3. Click Project. From the drop-down menu, make sure that Show default projects is on and select openshift-marketplace.
4. Copy the following CatalogSource YAML file into the editor.

   apiVersion: operators.coreos.com/v1alpha1
   kind: CatalogSource
   metadata:
    name: ibm-operator-catalog
    namespace: openshift-marketplace
   spec:
    displayName: IBM Operator Catalog
    publisher: IBM
    sourceType: grpc
    image: icr.io/cpopen/ibm-operator-catalog
    updateStrategy:
      registryPoll:
          interval: 45m
   

5. Click Create.
6. Verify that the CatalogSource is successfully applied:
   1. Wait for the status field in the Details section to become READY.
   2. Ensure that the IBM z/OS Connect Operator appears in the Operators section.

Install the IBM z/OS Connect Operator to deploy z/OS Connect APIs in a Container Platform.

1. Log in as cluster-admin to the Red Hat OpenShift Container Platform web console. Ensure that you are using the Administrator perspective by using the left navigation.
2. Click Operators > OperatorHub in the left navigation.
3. Search for z/OS Connect and click the IBM z/OS Connect tile.
4. Click Install.
5. From the Install Operator page, complete the fields as follows:
   1. Installation Mode

      All namespaces on the cluster (default)

      For the AllNamespaces install mode, the IBM z/OS Connect Operator is installed to the openshift-operators namespace and watches all namespaces on the cluster for instances of the ZosConnect CR. This means that a IBM z/OS Connect Operator can be installed only once in this mode.

      For the OwnNamespace install mode, the IBM z/OS Connect Operator is installed to a namespace of your choice and watches all instances of a ZosConnect CR in isolation to this namespace. This means that an IBM z/OS Connect Operator can be installed multiple times in this mode.

   2. Installed Namespace Select a namespace from this list or create a new namespace.
      Note: Installed Namespace is only an option if you selected OwnNamespace for the installation mode.
   3. Update Approval To automatically update the running instance of your IBM z/OS Connect Operator whenever new updates are made available to the channel, select Automatic (the default). If you want to review and approve an update manually, select Manual.
      Note:

      1. You can change the approval strategy later.
      2. Automatic Update Approval updates the IBM z/OS Connect Operator in a connected environment. Automatic updates aren't applicable for offline (airgapped) environments.
6. Click Install.
7. If you selected Manual for the Approval Strategy field, manually review and approve the install plan.
8. Verify the IBM z/OS Connect Operator installation.
   A message is displayed on the Operators > OperatorHub page, similar to Figure 1, confirming the successful installation of the IBM z/OS Connect Operator to the Red Hat OpenShift Container Platform.

   

   Tip: To view the installation status of the IBM z/OS Connect Operator after the installation procedure is complete, navigate to Operators > Installed Operators, and select your project from the Projects drop-down. IBM z/OS Connect is listed with a status of Succeeded.
9. View the deployed IBM z/OS Connect Operator Pods.
   To view the deployed IBM z/OS Connect Operator Pods, click View Operator to see the Operator details page. Scroll to the ClusterServiceVersion details section and click the ibm-zcon-zosconnect-controller-manager deployment that is listed under Operator Deployments.

   From the Deployment details page, click the Pods tab where the IBM z/OS Connect Operator Pod is shown as Status > Running and Ready > 2/2.

1. Log in as zcon-user to the Red Hat OpenShift Container Platform web console. Ensure you are in the Developer perspective by using the left navigation.
2. Click Secrets in the left navigation.
3. Select a Project to view the list of Secrets or create a Project.
   Note: This Project is the environment where your z/OS Connect APIs are deployed. Your Administrator might have created it depending on the IBM z/OS Connect Operator installModes configuration. If a Project does not exist, you must create a Project.
4. Click Create in the upper right of the Secrets page and select Image pull secret.
5. Enter a Secret name.
   For example, zosconnect-pull-secret.
   Note: The Secret name is used as a reference in Create a ZosConnect Custom Resource (CR) - Operand Deployment.
6. Enter the Registry server address for the location of the z/OS Connect API.
   For example, privateregistry.example.com.
7. Enter the Username for the Container Registry defined in Step 6.
8. Enter the Password for the Container Registry defined in Step 6.
9. Click Create.
10. The Secret is added to the Secrets page and is ready for use.

Use ConfigMap and Secret Objects in a Container Platform to store the connection and credential configuration values for your z/OS Connect API image to use.

1. ConfigMap
   1. Log in as zcon-user to the Red Hat OpenShift Container Platform web console. Ensure you are in the Developer perspective by using the left navigation.
   2. Click ConfigMaps in the left navigation.
   3. Select the Project to view the list of ConfigMaps or Create a Project.
      Note: This Project is the environment where your z/OS Connect APIs are deployed. Your Administrator might have created it depending on the IBM z/OS Connect Operator installModes configuration. If a Project does not exist, you must Create a Project.
   4. Click Create ConfigMap in the upper right of the ConfigMaps page.
   5. Switch Config via value to YAML view using the radio-buttons.
   6. Add the ConfigMap name and your connection information to the Create ConfigMap page.
      In this example, DB2_HOST and DB2_PORT are specified as Key-Value pairs. Customize the values as appropriate.

      apiVersion: v1
      kind: ConfigMap
      metadata:
        name: <unique ConfigMap name>
        namespace: <project name>
      data:
        DB2_HOST: <db2 host address> 
        DB2_PORT: '<db2 port>'

      Note:

      • Integer values must be represented as 'string'.
      • The ConfigMap name is used as a reference in Creating a z/OS Connect Custom Resource (CR) instance - Operand Deployment.
      • Selecting the Project in step 1.c before creating the ConfigMap will automatically complete the namespace value in the ConfigMap.
   7. Click Create.
   8. The ConfigMap is added to the ConfigMaps page and is ready for use.
2. Secret
   1. Log in as zcon-user to the Red Hat OpenShift Container Platform web console, and ensure you are in the Developer perspective by using the left navigation.
   2. Click Secrets in the left navigation.
   3. Select a Project to view the list of Secrets or Create a Project.
      Note: This Project is the environment where your z/OS Connect APIs are deployed. Your Administrator might have created it depending on the IBM z/OS Connect Operator installModes configuration. If a Project does not exist, you must Create a Project.
   4. Click Create in the upper right of the Secrets page and select Key/value secret.
   5. Enter a Secret name.
      For example, sample-db2-cred.
      Note: The Secret name is used as a reference in Create a ZosConnect Custom Resource (CR) instance - Operand Deployment.
   6. Enter the username key in the Key field.
      For example, DB2_USERNAME.
   7. Enter the username credential in the Value field.
      For example, JoeSmith.
      This is the DB2_USERNAME for the DB2_HOST defined in Step 1.
   8. Click Add key/value.
   9. Enter the password key in the Key field.
      For example, DB2_PASSWORD.
   10. Enter the password credential in the Value field.
       In this example, the DB2_PASSWORD is the Value for DB2_USERNAME JoeSmith.

       Note: The Secret values should be encrypted at rest. For more information, see Encrypting Confidential Data at Rest.
   11. Click Create.
   12. The Secret is added to the Secrets page and is ready for use.

Configuring TLS (secure networking configuration options) for a z/OS Connect API deployed to a Container Platform with the IBM z/OS Connect Operator.

1. Red Hat OpenShift Routes
   Note: Use the following procedure to create the certificateSecret depending on the TLS Termination type and configuration, if required.
   1. Log in as zcon-user to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Developer perspective by using the left navigation.
   2. Click Secrets in the left navigation.
   3. Select a Project to view the list of Secrets or create a Project.
      Note: This Project is the environment where your z/OS Connect APIs are deployed. Your Administrator might have created it depending on the IBM z/OS Connect Operator installModes configuration. If a Project does not exist, you must create a Project.
   4. Click Create in the upper right of the Secrets page and select Key/value secret.
   5. Enter a Secret name.
      Note: The Secret name is used as a reference in Operand Routes for the certificateSecretRef field.
   6. Enter the Key from the table into the Key field and enter the Value from the table into the Value field. Repeat for all applicable Key/Value pairs in the table for your chosen TLS Termination Type.
   7. Click Create.
2. Native Kubernetes Ingress
   1. Install Kubernetes CLI (kubectl). For more information, see Installing the CLI.
   2. Log in to your Kubernetes cluster.
   3. Add tls.key and tls.crt to separate files.
   4. Run the following command to create the secret in the namespace where the z/OS Connect API is to be deployed.
      Note: This namespace is the environment where your z/OS Connect APIs are deployed. Your Administrator might have created it depending on the IBM z/OS Connect Operator installModes configuration. If a namespace does not exist, you must create one.

      kubectl create secret <secret-name> --namespace <your_namespace> --key /path/to/tls.key --cert /path/to/tls.crt

Use volumes in a container platform to mount keystores for your z/OS Connect API image to use. Volumes are mounted file systems available to pods and their containers.

<ssl id="sslCertificates" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore"/>

<keyStore id="clientKeyStore" password="${CERTIFICATE_PASSWORD}" location="${server.config.dir}/resources/security/clientKey.p12" type="PKCS12"/>  
<keyStore id="clientTrustStore" password="${CERTIFICATE_PASSWORD}" location="${server.config.dir}/resources/security/clientTrust.p12" type="PKCS12"/>

1. Log in as zcon-user to the Red Hat OpenShift Container Platform web console. Make sure that you are in the Developer perspective by using the navigation.
2. Click Secrets in the navigation.
3. Select a Project to view the list of Secrets or Create a Project.
   If a Project does not exist, you must Create a Project.
4. Click Create on the Secrets panel and select Key/value secret.
5. Enter a Secret name.
   For example, keystore-secret.
6. Enter the keystore key in the Key field.
   For example, clientKey.p12.
7. Enter the keystore contents in the Value field.
   For example, the clientKey.p12 certificate in plain text.
8. Click Create.
9. Click Secrets in the navigation.
10. Click Create on the Secrets panel and select Key/value secret.
11. Enter a Secret name for the truststore certificate.
    For example, truststore-secret
12. Enter the truststore key in the Key field.
    For example, clientTrust.p12
13. Enter the truststore contents in the Value field.
    For example, clientTrust.p12 certificate in plain text.
14. Click Create.

To create the CERTIFICATE_PASSWORD, complete the following steps:

15. Click Secrets in the navigation.
16. Click Create on the Secrets panel and select Key/value secret.
17. Enter a Secret name for the certificate password.
    For example, certificate-password.
18. Enter the certificate key in the Key field.
    For example, CERTIFICATE_PASSWORD.
19. Enter the certificate credential in the Value field.
    For example, the CERTIFICATE_PASSWORD in plain text.

Creating a ZosConnect Custom Resource (CR) instance to enable deployment of your z/OS Connect API project.

1. Log in as zcon-user to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Developer perspective by using the left navigation.
2. From the navigation, click +Add.
   Select the project that you are creating a ZosConnect CR instance for. Create a project if one doesn't exist.
3. In the Add page, select Operator Backed from the Developer Catalog section.
4. Search for ZosConnect, and then click the ZosConnect tile.
5. From the ZosConnect panel, click Create.
6. Complete the following fields on the Create ZosConnect page to define the ZosConnect Custom Resource:
   1. Specify a Name for your ZosConnect CR instance to associate it with your API.
   2. Optional: Specify additional Labels for your ZosConnect CR instance.
   3. Operand License Structure

      Expand the Operand License Structure section by using to the right of the page.

      Accept Operand License - Click the check-box, or in later versions of Red Hat OpenShift toggle the radio button to reflect true to accept the license.

      Note: Accept the license for the IBM z/OS Connect Operator to create the resources.
   4. Operand Deployment
      Expand the Operand Deployment section by using to the right of the page and complete the fields as detailed in Table 5.

      Table 5. Operand Deployment

      Field	Value	Note
      Container Port	For HTTP, 9080. For HTTPS, 9443.	This value maps to the available ports defined in a z/OS Connect API. Note: This value must be consistent with the Port and Target Port values in the Operand Service step.
      Image	Enter the image for the z/OS Connect API to deploy.	You can find the steps to build a z/OS Connect API image here Build a z/OS Connect API image.
      Pull Policy	Defaults to IfNotPresent.	The image is updated when it is not already present on the cluster. Note: For more information about this native Kubernetes feature, see Image Pull Policy.
      Pull Secret	Name of the Secret to use to pull images from the specified repository.	For more information, see Configure an image pull secret in the Container Platform.
      Replicas	Number of Pod replicas to be deployed to the cluster for the z/OS Connect API.	Note: This value can be scaled up or down manually after the deployment if needed. More details on Pod replication can be found here.
      Volume	All volumes are available to the z/OS Connect API pod.	The volumes are not accessible by the z/OS Connect API pod unless mounted.
      VolumeMounts	Volumes that are mounted on the z/OS Connect API pods container	The name value must match the wanted volume name.

      Optional - Environment variables

      If you completed Configure environment variables (Optional), you must complete the following steps for the data within the ConfigMap and Secret objects to be mapped to the connection and credential tags in the z/OS Connect API image.

      1. Go to the start of the page, switch the view using the Configure via: YAML view to manually edit the ZosConnect CR.
      2. Add the values to the spec.deployment.env field in the ZosConnect CR.
         Note: Do not save the yaml file. It is done automatically.

         For example,

         spec:
           deployment:
             env:
               - name: DB2_HOST
                 valueFrom:
                   configMapKeyRef:
                     key: DB2_HOST
                     name: sample-db2-conn
               - name: DB2_PORT
                 valueFrom:
                   configMapKeyRef:
                     key: DB2_PORT
                     name: sample-db2-conn
               - name: DB2_USERNAME
                 valueFrom:
                   secretKeyRef:
                     key: DB2_USERNAME
                     name: sample-db2-cred
               - name: DB2_PASSWORD
                 valueFrom:
                   secretKeyRef:
                     key: DB2_PASSWORD
                     name: sample-db2-cred

         This adds DB2_HOST and DB2_PORT values from the sample-db2-conn ConfigMap and adds DB2_USERNAME and DB2_PASSWORD values from the sample-db2-cred Secret. These environment variables are exported inside the z/OS Connect API image at run time.

         Note: Substitute the values for sample-db2-conn and sample-db2-cred to match the ConfigMap and or Secret created in Configure environment variables (Optional). If you do not require the optional Secret, remove the respective fields from the example.
      3. Switch the view back to using the Form view using Configure via:

      Optional - Volumes

      If you completed Configure volumes (Optional), you must complete the following steps for the data within the Secret objects to be mapped to the keystore tags in the z/OS Connect API image.

      1. Go to the start of the page, switch the view using the Configure via: YAML view to manually edit the ZosConnect CR.
      2. Add an environment variable for the certificate password by using the spec.deployment.env field.
      3. Add a volume for the keystore and truststore in the spec.deployment.volumes field.
      4. Mount the volume for the keystore and truststore to the container at defined location by using the spec.deployment.volumeMount field.
      5. The following example is a sample configuration for the SSL example that is shown in Configure volumes (Optional). Customize these values for your own configuration.

         spec:
           deployment:
             env:
               - name: CERTIFICATE_PASSWORD
                 valueFrom:
                   secretKeyRef:
                     name: certificate-password
                     key: CERTIFICATE_PASSWORD
         
             volumes:
               - name: truststore
                 secret:
                   secretName: truststore-secret
               - name: keystore
                 secret:
                   secretName: keystore-secret
         
             volumeMounts:
               - mountPath: /opt/ibm/wlp/usr/servers/defaultServer/resources/security/clientTrust.p12
                 name: truststore
                 subPath: clientTrust.p12
               - mountPath: /opt/ibm/wlp/usr/servers/defaultServer/resources/security/clientKey.p12
                 name: keystore
                 subPath: clientKey.p12

      6. Switch back to the Form view by selecting Configure via: and verify that the volume mounts and environment variables are correctly configured.

      Each certificate (clientTrust.p12 and clientKey.p12) is referenced from its respective secrets (truststore-secret and keystore-secret) and is stored in a volume (truststore and keystore). The volume is mounted by defining its mountPath that refers to the path inside the z/OS Connect API where the volume is mounted. The subPath property ensures that only the specific certificate file is mounted rather than the entire volume and the name under volumeMount matches the corresponding volume name.

   5. Operand Service
      Expand the Operand Service section by using the to the right of the page.

      Table 6. Operand Service Config

      Field	Value	Note
      Port	The port is exposed by the container. For HTTP, 9080 For HTTPS, 9443	This allows a Service resource to communicate with the z/OS Connect API for Routes / Ingress. Note: This must be consistent with the Container Port value in the Operand Deployment step.
      Target Port	The port that the operator assigns to containers inside pods. Defaults to the value of Operand Service Port.	There are no notes for the Target Port field.
      Type	ClusterIP	There are no notes for the Type field.

      Note: The values for Port and Target Port must match.

   6. Operand Route
      Important:

      1. Use the Expose toggle to set the field to true. This displays the Operand Route section and enables the IBM z/OS Connect Operator to create the Route / Ingress resources, which are required for invoking the z/OS Connect.
      2. If you completed Configure Transport Layer Security (TLS) in a Container Platform (Optional), you must complete values for Termination and Certificate Secret Ref for the operand config to create a secured Route or Ingress.
      3. The following table defines fields that support both Red Hat OpenShift Routes and native Kubernetes Ingress. Select the fields that apply for your chosen configuration. If you do not require transport security, all of the Operand Route fields can be left blank.
      Expand the Operand Route section by using to the right of the page.

      Table 7. Operand Routes Config

      Field	Value	Note
      Termination (Route)	TLS termination policy for Route. Can be one of the edge, reencrypt, and, passthrough.	Define the Red Hat OpenShift Route Transport Layer Security (TLS) termination policy. Required secured Route field. For an insecure Route, do not enter a value.
      Insecure Edge Termination Policy (Route)	HTTP traffic policy with TLS enabled for Route. Can be one of Allow, Redirect and None.	Defaults to Allow.
      Path (Route) (Ingress)	Path to be used for Route or Ingress.	This defaults to /.
      Certificate Secret Ref (Route) (Ingress)	The name of a secret that already contains TLS key, certificate, and CA to be used for the Route or Ingress. It can also contain a destination CA certificate for Route. The following keys are valid in the secret: ca.crt, destCA.crt, tls.crt, tls.key.	Optional for a secured Route field. Required for a secured Ingress field. For an insecure Route or Ingress, do not enter a value.
      Hostname (Ingress)	Hostname to be used for the Ingress.	Required Ingress field.
      Path Type (Ingress)	Path Type to be used for the Ingress. Can be one of Prefix, Exact or ImplementationSpecific.	Required Ingress field. For more information about Ingress Path Types, see Ingress Path Types.

7. Click Create to create your ZosConnect CR instance.
   Important: To install another z/OS Connect API to the Red Hat OpenShift cluster, repeat the procedure for step 6.

   The IBM z/OS Connect Operator is designed to manage many ZosConnect Custom Resource instances, therefore many z/OS Connect API deployments. The following image shows a IBM z/OS Connect Operator managing 3 ZosConnect instances. Each ZosConnect instance is configured with a different z/OS Connect API image. These represent 3 separate z/OS Connect API deployments in Red Hat OpenShift.

   

Results

When the ZosConnect Custom Resource is created, the IBM z/OS Connect Operator creates the resources that are required for your chosen configuration based on the fields that are completed in this procedure. To view these resources, open the Topology page where the ZosConnect instance is created.

In the example shown in Figure 3, the name of the ZosConnect Custom Resource is zosconnect-sample. Click inside the dotted area of the zosconnect-sample Custom Resource to view the resources that are associated with the created ZosConnect Custom Resource.

The Pod containing the z/OS Connect API is created by the zosconnect-sample-deployment deployment. To view the Pod, click zosconnect-sample-deployment in the Resources tab to open the Deployment > Deployment details page. Navigate to the Pods tab to view the Pod.

In this example, the Pod Status is Running and 1/1 replicas are Ready. Only 1 Deployment>Replicas was specified for the ZosConnect Custom Resource.

Note:

1. The Pods might take a few seconds to become ready.
2. The Pods that are created by the IBM z/OS Connect Operator are annotated with productName, productID, and productMetric to allow the IBM License Service to recognize the z/OS Connect Pods should IBM License Service be required by other IBM products that are installed into the same cluster.