IBM z/OS Connect Server DevOps overview

z/OS Connect Server DevOps activities for building, deploying, and administering API projects in a Container Platform.

Before you begin

A DevOps pipeline defines a series of tasks that are run in a predefined sequence to automate the building and deployment of API projects for continuous integration and delivery. You can choose to automate the start of the DevOps pipeline by using technologies such as webhooks with GitHub, or you can manually commence the DevOps pipelines.

This topic provides an overview of the DevOps pipeline tasks for building and deploying z/OS Connect API projects. The pipeline technology used to implement these tasks depends on your organization.

Prerequisites

Choose one of the following options for the directory where the API project WAR files are deployed:

The drop-ins directory

The drop-ins directory, /config/dropins is a special directory that is supported by WebSphere® Application Server for Liberty. It allows WAR files to be deployed and dynamically loaded into the running z/OS Connect Server with no additional definitions that are required in the configuration file.

By default, z/OS Connect Designer deploys the API project WAR file to this directory. Using the same directory in your API container image simplifies the creation of that image because the configuration remains the same. This option simplifies the DevOps pipeline by using this deployment method when developing the API project. A production system would not use this option.

A directory other than drop-ins

This is required in any of the following situations:

The APIs OpenAPI definition servers: section contains an entry for the context root value of the API, which is not just /.
Note: The API project WAR file is generated with a context root of /.
Multiple APIs are to be deployed to the same z/OS Connect container. Because the API project WAR file is generated with a context root of /, and multiple API WAR files in the same server must have unique context root values, you need to include a unique context root value (not /) in the APIs OpenAPI definition servers: section. For example, to use a context root of /EmployeesApi:
```
openapi: 3.0.0
   ...
   servers:
      url: https://localhost:9443/EmployeesApi
   ...
```
Requests to start an API require authentication only, without authorization, so the authorization roles need to be mapped to the WebSphere Application Server for Liberty special subject ALL_AUTHENTICATED_USERS. For more information, see How to define authorization roles.

If you choose not to use the drop-ins directory, you must alter the configuration that is used in z/OS Connect Designer during the creation of the API container image.

These API project WAR files are typically deployed into the /config/apps directory. You must create this directory but you can choose a different name.

You also need to configure a webApplication element in the server.xml configuration file. For example,

<webApplication location="/config/apps/EmployeesApi.war" name="EmployeesApi" contextRoot="/EmployeesApi"/>

Where:

location is the fully qualified path to the deployed API WAR file.
name is an optional attribute that is used in log messages to identify the API.
contextRoot value must match the context root value that is specified in the servers: entry of the OpenAPI definition servers: section.

Note: The webApplication configuration needs to be in the {server_config_dir}/server.xml. The API Project src/main/liberty/config/server.xml file is generated with specific content and any customized changes are overwritten.

Ensure that the following requirements are also met.

Each API project must be checked into a Source Code Management (SCM) repository.
Gradle V7.6.1 or later must be installed on the machine running the builds.
Access to Gradle. For more information, Building IBM z/OS Connect APIs with Gradle.

Procedure

Extract the project from Source Code Management.
Extract the API project from your chosen Source Code Management (SCM) solution.
Initiating the Gradle build process
Use Gradle to build and package that API project. When you define this task in your DevOps pipeline you can use the build.gradle, and settings.gradle file found in the API project. For more information about the Gradle plug-in and it's requirements, see Building IBM z/OS Connect APIs with Gradle.
Note: You can include more than one API project WAR file in a container, but only include those that require common configuration.
Copy the server configuration.
Copy the server configuration files from the API project /src/main/liberty/config directory into the configDropins/overrides directory of the server. If using Docker Desktop you can use the Dockerfile found in the API project. For more information, see Building IBM z/OS Connect APIs with Gradle.
Identify the appropriate configuration for the environment for which the image is built.
For example, your API project might require different property substitutions that relate to the z/OS Connect Designer environment variables, such as CICS_USER, DB2_USER, CICS_PASSWORD, CICS_HOST and CICS_PORT or extra security configuration is needed.
Building an API container image.
Use a container image building tool such as Docker, Podman, Buildah to define a task that builds an Open Container Initiative (OCI) compliant image from the z/OS Connect Server image and the API project WAR file that is built in the previous step. If using Docker Desktop, you can choose to use the Dockerfile found in the API project. For more information about building an API container, see Building IBM z/OS Connect APIs with Gradle.
Update the image registry.
Once a container image has been built, push the image to your company's chosen image registry. 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, see Install the IBM z/OS Connect Operator.
Note:
- If you have made changes to 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.