Building IBM z/OS Connect artifacts for DevOps

How to build IBM® z/OS® Connect artifacts 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 building z/OS Connect API projects by using build automation tooling. The pipeline technology used to implement these tasks depends on your organization.

Using z/OS Connect build toolkit to build z/OS Connect API projects

zosConnect-2.0 Applies to zosConnect-2.0.

The zosConnect-2.0 feature uses the z/OS Connect build toolkit to build the z/OS Connect API and service project archive files.

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.

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. For more information, see Build a service archive with the build toolkit and Build an API archive with the build toolkit.

The build toolkit also generates the API requester from a properties file and the OpenAPI specification from the command line by using zconbt or by using the build toolkit SDK. For more information, see Using the build toolkit to generate artifacts for an API requester.

Using Gradle to build z/OS Connect API projects

zosConnect-3.0 Applies to zosConnect-3.0.

The zosConnect-3.0 feature uses Gradle to build a z/OS Connect API project into a WAR file. This WAR file can be deployed to a z/OS Connect Server. The build.gradle file, which is located in the root of the API project, defines the list of plug-ins that are required to package the API project into a WAR file.

For more information about Gradle and how Gradle is used in the zosConnect-3.0 feature, see Building IBM z/OS Connect APIs with Gradle.

There are prerequisites to building a z/OS Connect API project with Gradle which are as follows.
  • A z/OS Connect project is available. Ideally, the API project source is checked into a Source Code Management (SCM) repository.
  • Gradle 7.6.1 or higher is installed on the machine running the builds. For more information about supported Gradle versions, see IBM z/OS Connect system requirements.
  • For API provider projects, the z/OS Connect API provider Gradle plug-in, com.ibm.zosconnect.gradle that is automatically downloaded in an online environment, must be available to build the API provider project WAR files. For more information, see A launch icon to indicate a link opens a new tab or window. maven central repository - com.ibm.zosconnect.provider
  • For API requester projects, the z/OS Connect API requester Gradle plug-in, com.ibm.zosconnect.requester that is automatically downloaded in an online environment, is available to build the API requester project WAR files. For more information, see A launch icon to indicate a link opens a new tab or window. maven central repository - com.ibm.zosconnect.requester.
  • 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 WebSphere® Application Server Liberty supports. 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 instance. 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
   ...

    These API project WAR files are typically deployed into the /config/apps directory.

    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.

    For more information about building your API project WAR file, see Using Gradle to build the API project.

Building container images

zosConnect-3.0 Applies to zosConnect-3.0.

Containers Applies to z/OS Connect container deployments.

The z/OS Connect Server API image is built with the generated WAR file, API configuration files, and the downloaded z/OS Connect Server image. For more information about how to build your API WAR file, see Using Gradle to build the API project.

Build and deploy new API images when updates to the APIs or their configuration are required. For more information about API configuration files, see Overview of IBM z/OS Connect configuration files. For more information about downloading the z/OS Connect Server image, see Download a z/OS Connect Server zosConnect-3.0 feature image.

To build an API server 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 or Podman, 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.
Note: The API WAR file can be built on any supported environment.

If the deployment target for this API image is the IBM z/OS Container Platform, the z/OS Connect API image must be built and run on a z/OS LPAR with Podman installed.