Part 3 - Migrate z/OS applications to adopt DBB 2.0

This blog post is Part 3 of a 3-part series of blog entries dicussing the migration process from DBB 1.1 to DBB 2.0 and its implications. The first post, Part 1 - Migrate existing datastore managed in Derby to Db2z, covered the database migration process, which is optional if you are already using a supported database for DBB 2.0 (that is, either Db2 LUW or Db2 z/OS). The second post, Part 2 - Prepare CI/CD pipelines for DBB 2.0, discussed all the preparation steps that should be taken to ensure a smooth migration for existing CI/CD pipeline definitions. In Part 2, we outlined how the IBM Z DevOps Acceleration Team (DAT) has prepared their GitLab environment for a smooth and frictionless migration of the applications that are hosted on the platform.

Note: This blog series was originally published in early 2023, and only applies to migrations from DBB 1.x to DBB 2.0, and not migrations from DBB 1.x directly to DBB 2.0.1 or above. In June 2023, DBB 2.0.1 was released and introduced database schema changes that do not allow a DBB 1.x and DBB 2.0.1 toolkit to access the same database instance. As a reminder, DBB 1.x will be going out of support at the end of April 2024. If you need additional advice on migrating from DBB 1.x, please open a support ticket with IBM Support.

In this final blog entry, we will now actually migrate one of our applications from using DBB 1.1.3 to using our prepared DevOps implementation with DBB 2.0, and we will discuss the activities necessary to ensure a successful move. With the pre-work that has been done, the migration of an actual application turns into a straightforward activity. This blog entry documents the steps we took for our retirementCalculator sample application, which is a COBOL/batch application that includes a zUnit test setup. The GitLab pipeline definition of the retirementCalculator application uses pipeline templates, which we have already prepared for the use of DBB 2.0.

We need to consider several aspects performed by the following roles:

• Application teams have to update their search path definitions for the SearchPathDependencyResolver and SearchPathImpactFinder APIs. At the end of the migration process, this will enable them to use DBB 2.0 by simply updating their pipeline definition to point to the new configuration that uses DBB 2.0.
• The Build engineer in charge of DBB has to update the "owner" of the high-level DBB objects (that is, collections and build results) in the metadatastore.

Update application build configurations for the SearchPathDependencyResolver and SearchPathImpactFinder APIs

DBB version 1.1.2 introduced the SearchPathDependencyResolver and SearchPathImpactFinder APIs for dependency analysis and impact analysis, respectively, which resulted in the deprecation of their corresponding API predecessors (DependencyResolver and ImpactResolver). DBB 2.0 drops support for the older, deprecated APIs, meaning that if your DBB build configurations have not yet been updated to use the newer SearchPathDependencyResolver and SearchPathImpactFinder APIs, you will want to make this update before switching your applications to build with DBB 2.0. Not only will updating to the newer APIs keep your pipelines running, but it will also allow you take advantage of the improved API experience, including the ability to use wildcards and file extensions in the search path, and the ability to specify the search path to the APIs in a more granular way.

When using the SearchPathDependencyResolver and SearchPathImpactFinder APIs, application properties for dependency and impact resolution should be defined using the searchPath string format, as opposed to the older APIs' pseudo-JSON rules format. An example of this property mapping from the old to new API is shown in the following snippet. You can read more details about the searchPath format and how to use it in the context of both dependency resolution and impact resolution in How to manage build dependencies.

Although we had previously been running our GitLab environment with Dependency Based Build 1.1.3 by default, our retirementCalculator application was not yet using the new searchPath definitions. It was still using the older pseudo-JSON rules format. As part of a normal development iteration for the retirementCalculator, we added the new (and required for DBB 2.0) definitions for the SearchPathDependencyResolver and SearchPathImpactFinder APIs to the property files in application-conf. For example, we mapped our old, pseudo-JSON copybookRule to the new copybookSearch property using the searchPath string format in the application-conf/application.properties snippet below. (Note that in our application, we also decided to keep the definitions with the old format, since our team does a lot of testing and demos between DBB versions.):

In our case, most of the properties we needed to update for the new APIs were located in application-conf/application.properties. For a sampling of properties that you might need to update for the new APIs, you can take a look at the properties listed in the value of the impactSearch property in zAppBuild's sample application.properties file. In this file of zAppBuild version 3.0.0, you can still see examples of the old APIs' pseudo-JSON rules (mostly preceded by ** deprecated ** warnings in the comments and ending with the world "Rule" in their property names), alongside their corresponding new searchPath property definitions (similarly-named, but ending with the word "Search" in their property names). These side-by-side comparisons can be helpful when mapping the older APIs' format to the newer APIs' format. (The older rule samples are removed in later versions of zAppBuild, starting with zAppBuild version 3.0.1.)

When making these updates, remember that your build dependency resolution and impact resolution properties are referenced in other places in your build configuration (for example, in property files for the language scripts), so you will also need to ensure those property name references are integrated accordingly. For example, the application-conf/Cobol.properties file contains a reference to the copybookRule property as part of the cobol_resolutionRules property for the old APIs; therefore, in this property file, we added a new cobol_dependencySearch property to reference the newly-required copybookSearch property that will be used by the SearchPathDependencyResolver API:

We validated the new definitions and updated references on a feature branch first, before merging them into the main branch and including them in the next release cycle. With this update, the application continued to use the existing DBB environment version 1.1.3, but was now switched to the use new searchPath APIs required for DBB 2.0.

Update pipeline definitions for applications moving to DBB 2.0

Moving an application from DBB 1.1.x to DBB 2.0 is a significant change. It is recommended to introduce the following changes through a HotFix/Emergency Fix process, as part of the lifecycle process of the application. The reason for this is that this task should be completed in a short time window, as it requires the coordination of the update of the ownership of the high-level DBB objects stored in the database and the updates to the application pipeline configuration. The updates to the pipeline definition should be merged into all of the application repository's active branches at the same time, in order to avoid causing build exceptions such as the one below:

** Storing 1 logical files in MetadataStore collection 'retirementCalculator-Dennis-37-implement-changes-to-easily-switch-to-dbb-2-0-setup-patch-88576'
Caught: com.ibm.dbb.build.BuildException: BGZTK0144E The user is not authorized to delete collection logical file.
com.ibm.dbb.build.BuildException: BGZTK0144E The user is not authorized to delete collection logical file.
	at com.ibm.dbb.metadata.jdbc.JDBCMetadataStore.deleteLogicalFile(JDBCMetadataStore.java:385)
	at com.ibm.dbb.metadata.jdbc.CollectionImpl.addLogicalFile(CollectionImpl.java:140)
	at com.ibm.dbb.metadata.jdbc.CollectionImpl.addLogicalFiles(CollectionImpl.java:152)
	at ImpactUtilities.updateCollection(ImpactUtilities.groovy:896)
	at ImpactUtilities.createImpactBuildList(ImpactUtilities.groovy:50)
	at build.createBuildList(build.groovy:503)
	at build.run(build.groovy:36)
	at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
	at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)

Update permissions in the DBB metadatastore

With DBB 1.1.x, the owner of the high-level objects created in the DBB database was usually the ADMIN user, as these objects were typically created by the CI/CD pipelines which were by default configured this way. With DBB 2.0 and its new DBB role model based on RACF groups, the user owning these objects is the user that is running the groovyz commands.

As a result, we needed to update the metadatastore objects to change the OWNER field for the objects we wanted to migrate in the permissions table. It should be noted that this action can be only performed by users with high database authority.

The IBM DBB documentation provides a SQL query to update the owner of all artifacts at once. However, we could not apply this in our incremental migration approach, as we wanted to migrate applications at a different pace. In our setup, we had only assigned the DBBUSER role to our pipeline user GITLAB, by adding it to the DBBUSER RACF group.

The high-level DBB metatadata store objects COLLECTION and BUILD_RESULT contain a foreign key reference to the PERMISSIONS table.

To support an incremental approach, the PERMISSION table entries need to be updated for the application that is being migrated. Rather than the "all or nothing" approach, we aimed to update only the necessary records for the application we were currently migrating (retirementCalculator), and set the OWNER to be the GITLAB user, which is the technical user executing the pipelines:

 -- UPDATE OWNER of COLLECTION
SET SCHEMA DBBGITLAB;
Update PERMISSIONS set P_OWNER = 'GITLAB' WHERE C_ID IN ( SELECT PERMISSIONS_C_ID FROM COLLECTION WHERE C_NAME LIKE 'retirementCalculator%');
-- UPDATE OWNER of BUILD RESULTS
Update PERMISSIONS set P_OWNER = 'GITLAB' WHERE C_ID IN ( SELECT PERMISSIONS_C_ID FROM BUILD_RESULT WHERE BR_GROUP LIKE 'retirementCalculator%');

To coordinate the updates of the permissions and the update of the application pipelines, an alternative approach would be to add the GITLAB user to the DBBADMIN group to grant control over all objects.

Update the application pipeline configuration

In our setup for the retirementCalculator application, we created an emergency fix branch from our production branch to introduce the changes to switch to DBB 2.0. As we have blogged about in Part 2, the changes were rather small. In the following screenshot from our retirementCalculator migration merge request, you can see that we needed to ensure that the pipeline definition would:

• check out the correct version of zAppBuild for DBB 2.0 (in our case, this is the main branch), and
• include the new DBB_ENV environment variable, set to DBB20.

As changes to the .gitlab-ci.yml file (GitLab CI/CD pipeline definition file) trigger a pipeline build, we were able to immediately verify that the pipeline now uses the DBB 2.0 toolkit.

Conclusion

In this final blog entry, we have detailed the required steps to finalize the migration of application pipelines to DBB 2.0. These steps were mainly about integrating the new searchPath rules, updating the metadatastore security to assign the correct owner for DBB high-level objects, and updating the pipeline definition to point to DBB 2.0 setup through the DBB_ENV environment variables.

Our retirementCalculator sample application is now fully migrated to DBB 2.0! And throughout this series of blog entries, we prepared the ground for the smooth migration of all the other applications we're using in our demonstration infrastructure. Reapplying the steps described in this last blog entry will ensure a perfect transition for our remaining applications and a successful migration to DBB 2.0, with minimal disruption to users' activities.

Authors of this post

Lauren Li, DevOps Acceleration Team

Mathieu Dalbin, DevOps Acceleration Team

Dennis Behm, DevOps Acceleration Team