Deploying IBM z/OS Connect for DevOps

How to deploy IBM® z/OS® Connect for a DevOps pipeline.

A DevOps pipeline defines a series of tasks that are run in a predefined sequence to automate the development and deployment of projects for continuous integration and delivery. The following task provides an overview of common pipeline tasks for deploying IBM z/OS Connect API projects. The pipeline technology used to implement these tasks depends on your organization.

Deploying API requester and API provider artifacts requires making the outputs of the build steps available to the runtimes.

REST APIs

zosConnect-2.0 Applies to zosConnect-2.0.

The z/OS Connect administration interface is a set of REST interfaces for managing .sar, .aar, and .ara artifacts.

For more information about deploying an API by using the REST API administration interface, see Deploying an API.

For more information about updating an API by using the REST API administration interface, see Update an API.

For more information about deploying a service by using the REST API administration interface, see Deploy a service.

For more information about deploying an API requester by using the REST API administration interface, see How to deploy an API requester by using the administration interface.

Deploying on z/OS by copying files

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

API providers and API requesters can be deployed to z/OS in two steps.

Copy the files.
Refresh the server.

The following information provides more details about how-to copy the files and how-to refresh the z/OS Connect Server.

Copy the files

zosConnect-2.0 .aar's, .sar's, and .ara's: zosConnect-2.0 Applies to zosConnect-2.0.; Services, APIs, and API requesters in z/OS Connect are represented as single files (.sar, .aar, and .ara archive files). When these archive files are placed in the designated locations for services, APIs, and API requesters, they can be automatically deployed if the server is configured to monitor changes in these locations. You can run the build toolkit through a script to generate these archive files and then deploy them to the designated locations to automate the deployment process. Deployment of services and APIs can also be achieved through calls to the administration interface.
The build toolkit supports generation of service archives and API archives from projects that are created in the z/OS Connect API toolkit. For each service or API that you create in the API toolkit, the project directory in the Eclipse workspace and the files it contains serve as the input to the build toolkit for archive generation.; The deployment of services and APIs can also be achieved through calls to the administration interface. See the following examples to find out more.

zosConnect-3.0 API providers and API requesters

zosConnect-3.0 Applies to zosConnect-3.0.

The DevOps build tasks have common steps for API provider and API requester API projects. For more information about the DevOps build tasks that are required to automate the building of z/OS Connect API projects, see Building IBM z/OS Connect artifacts for DevOps.

The DevOps deployment steps require different steps depending on whether you're deploying an API provider z/OS Connect API project or an API requester z/OS Connect API project. The following sections define the DevOps deployment tasks for an API provider z/OS Connect API project and an API requester z/OS Connect API project.

Configure the z/OS Connect Server.
Copy the server configuration files from the API project /src/main/liberty/config directory into the ${server.config.dir}/configDropins/overrides directory of the server or another directory by using FTP. For more information, see Overview of IBM z/OS Connect configuration files.

For details on how to configure a z/OS Connect Server to support API providers, see Configuring z/OS Connect for zosConnect-3.0. Details can be found here in the sub-sections on how to configure z/OS Connect for CICS, Db2 and IMS.

For details on how to configure a z/OS Connect Server to support API requesters, see Configuring zosConnect-3.0 to support API requesters.
Deploy the generated API project WAR files to the z/OS Connect Server.
Deploy the generated API WAR project files into a permanent USS directory. An example directory, such as the one provided by the z/OS Connect Server zosconnect:openApi3Requester template, is ${server.config.dir}/apps.

API WAR files and API requesters can also be deployed to other directories, such as in separately mounted zFS file systems. For more information, see Deploying an API requester WAR file.
For each deployed API, define a webApplication element in the configuration file. An example element might be the following, where the location must match the directory and file name of the API WAR file:
```
<webApplication id="EmployeesApi" location="${server.config.dir}/apps/api.war" name="EmployeesApi"/> 
```
Note:
- With API provider, to avoid overwrites when deploying multiple APIs in a single server, change the name of api.war.
- An example element is included in the supplied zosconnect:openApi3 server template. For more information about supplied server templates, see Supplied server templates.

Examples - How to copy the files

Ansible

Ansible task to copy a WAR file.

  - name: Copy API to server
      ansible.builtin.copy:
        src: api.war
        dest: {{ zosconnect_server }}/apps/api.war
        mode: '0755'

For more information, see ansible.builtin.copy module – Copy files to remote locations

Zowe

Zowe command to copy the file.

zowe files upload file-to-uss "api.war" "<path_to_server>/apps/api.war" -b

For more information, see zos-files

Refresh the z/OS Connect Server

When you are ready to deploy your z/OS Connect artifacts, use the MVS system MODIFY command to refresh the z/OS Connect Server API and API requester WAR files and configuration files. For more information, depending on which feature you are using, see

The MODIFY command zosConnect-2.0

The MODIFY command zosConnect-3.0

Deploying in containers

zosConnect-3.0 Applies to zosConnect-3.0.

Containers Applies to z/OS Connect container deployments.

To deploy z/OS Connect API images to OCI-compliant container platforms, the container image is built by using the z/OS Connect Server image and your z/OS Connect API project. For more information, see Building container images.

When the z/OS Connect API image is built, push the image to your company's image registry to update the image. This image can then be used by the IBM z/OS Connect Operator and deployed into a Kubernetes cluster. The environment variables that are required for a specific environment are configured by using ConfigMaps and Secrets that are defined in the Operator.

For more information on configuring the IBM z/OS Connect Operator and the environment variables in a Red Hat® OpenShift® container platform, see Install the IBM z/OS Connect Operator and Configure environment variables (Optional).

For more information on deploying a z/OS Connect API image by using Podman, Run the z/OS Connect API container.

For more information on deploying in an airgapped (disconnected) environment, Install the z/OS Connect Catalog in Red Hat OpenShift with bastion host.

Note:

If you have changed an API image that is referenced by a deployment running in production, the cluster administrator must perform the following command to manually restart each pod in the deployment and distribute the changes.
```
oc rollout restart deployment <deployment-name>
```
If you have published a new version of an API image, for example with a new image tag, and would like to update an existing deployment that references an old version, you can update the zosconnect_v1_zosconnect.yaml Custom Resource Definition with the new API image and apply it to the cluster. The IBM z/OS Connect Operator will automatically restart each pod in the deployment and distribute the changes.