はじめに

ここまでz/OSアプリケーション開発プロセスにおいてJenkinsがどのように利用できるか個別の技術要素を見てきましたが、今回はもう少し具体的な開発シナリオを念頭において、どのようにJenkinsを活用できるのかを見ていきます。(基本的にはここまで見てきた手順の組み合わせです)

ここまでの記事を見ると、「今まではJCL実行すればいいだけだったのが、JenkinsやDBBやGitなど新しい技術を習得しなければならず、面倒くさいだけじゃん！」と感じるかもしれません。
しかし、背景としてz/OSの技術者が減っている状況の中で、DXの波に取り残されないように新しい技術を取り入れることで効率化や人材確保に寄与できるのではないか、と考える次第です。
重要なのは、役割の明確化を行い、一元管理できるところは集約し、自動化できるところは自動化する、さらにそれらの仕組みはなるべくオープン系でも活用されている技術を利用する、ということだと思います。その辺りを意識してシナリオを考えてみます。

関連記事

Jenkins - z/OS連携: (1) 概要
 Jenkins - z/OS連携: (2) Pipelineの利用
 Jenkins - z/OS連携: (3) Pipeline+Gitの利用
 Jenkins - z/OS連携: (4) Pipeline+Git+Webhookの利用
 Jenkins - z/OS連携: (5) Pipeline+Git+DBBの利用
 Jenkins - z/OS連携: (6) Jenkins Pipeline利用シナリオ

全体像

CI/CDパイプラインとしては以下のようなフローで表されることが多いと思います。

この記事では、上のフローでいうと上段部分(Code～Test辺り)が該当します。大きく分けると以下の2つの部分に分けて考えます。
(1)各開発者が個別の修正を行うフェーズ(Code～Build部分) ⇒ VSCode + Git + DBB
(2)いくつかの修正をパッケージしてリリースを行うフェーズ(Build～Release部分) ⇒ Git + Jenkins + DBB + α(Provisioning Tool, Deploy Tool, Test Tool, ...)

今回シナリオを動かす環境としては以下のような構成を想定しています。

今回実施するシナリオの流れとしては、以下のイメージです。
(1)個々の開発者がそれぞれVSCodeを使ってUT環境でソースの修正/単体テストなどを実施する。ある程度修正内容が固まったらそのブランチをマスターにマージするためのプルリクエストを発行
(2)リポジトリ管理者が修正内容等をチェックしマスターにマージ処理を行うことで、Pipelineが実行され一連の処理(ビルド、デプロイ、テストなど)が自動実行される。
※ここではこのフローの制御にJenkinsが使えることを確認する目的のため、ビルド部分(DBB)のみに着目しており、テストやデプロイなどの処理は含めていません。

ここでは、以下に提供されているサンプルを流用して一連の流れを追ってみたいと思います。
GitHub - zopeneditor-sample(wazi-masterブランチ)

主な登場人物/役割

仕組みがかなり複雑になってきているので、登場人物と役割を整理した上で、それぞれがどのような作業を行う必要があるのかを見ていきたいと思います。
※呼称は正しくないかもしれません(別の呼び方をするケースもあるかもしれません)が、分類としてはこんな感じだと思うので、ここではそう呼びますというくらいで考えて頂ければと思います。

インフラ担当者: 今回のフローを実現するためのインフラを整えます。製品の導入や基本的なセットアップをする必要があります。
ビルド・エンジニア: ビルドに関する環境を整えるために必要なカスタマイズや運用ルールなどを決定し、ビルドの環境全体の運用を統制します。開発者がコード修正作業に専念できるように裏の仕組みを整えてお膳立てをする役割を担います。
開発者:
- リポジトリ管理者: アプリケーションごとのリポジトリを管理します。
- コード開発者: ソース修正や機能追加など実質的なコーディング作業を行います。

一連のシナリオ実行

事前準備

必要な製品の導入、基本セットアップ (インフラ担当者)

主に上の図の赤線で示した部分のセットアップを行います。
この記事では製品導入や基本セットアップの詳細については触れません。適宜該当するドキュメントに従って実施してください。

各種サーバーの構成

z/OSとは別に、以下のサーバーを準備します。それぞれLinuxのサーバーやコンテナなどを利用して構築します。

Git Server: ソース管理用(今回はGitHub Enterpriseを想定)
Jenkins Server: Pipeline制御用
DBB Server: ビルド関連情報管理用

z/OS上のコンポーネント構成

各環境に製品の導入、基本構成を行ってそれぞれ利用できるようにしておく必要があります。

個別に製品の導入が必要なコンポーネント
- DBB,zAppBuild
- Debugger
- Rocket Git
z/OSの付属機能で構成が必要なコンポーネント
- z/OSMF
- SSH
- Java

ネットワーク構成

上の図の赤点線の矢印は各コンポーネント間でのTCPでの通信が行われる箇所を表しています。矢印の方向はTCPのコネクションを張る向きを示しています。これらの通信が行えるよう必要に応じてネットワークの構成(FirewallやProxyの設定)を行っておく必要があります。

ビルド環境の整備 (ビルド・エンジニア)

上の赤枠部分をセットアップするイメージです。

DBB,zAppBuildの設定

UT環境(UserBuild)、IT環境(FullBuild, ImpactBuild)それぞれでzAppBuildを利用してビルドを行うための設定を行います。
例えば以下のような項目を実施する必要があります。

zAppBuildのbuild-conf以下のプロパティー・ファイルの設計/設定。必要に応じてbuild-scriptのカスタマイズ。
USS上のディレクトリ、DBBで使用するデータセットの設計。
上の情報に基づいた、リポジトリ責任者/コード開発者向け開発ガイド作成、テンプレートの作成。
などなど...

参考:
zAppBuild
build-conf

具体例

zAppBuildは/u/dbb_common/dbb-zappbuild以下に展開している想定。

build-conf/datasets.propertiesを環境に合わせて以下のようにカスタマイズ。

datasets.properties

/u/dbb_common/dbb-zappbuild/build-conf/datasets.properties

# Dataset references
# Build properties for Partition Data Sets (PDS) used by zAppBuild build scripts.
# Please provide a fully qualified DSN for each build property below.
# Ex:
# MACLIB=SYS1.MACLIB

# z/OS macro library. Example: SYS1.MACLIB
MACLIB=SYS1.MACLIB

# Assembler macro library. Example: CEE.SCEEMAC
SCEEMAC=CEE.SCEEMAC

# LE (Language Environment) load library. Example: CEE.SCEELKED
SCEELKED=CEE.SCEELKED

# High Level Assembler (HLASM) load library. Example: ASM.SASMMOD1
SASMMOD1=HLA.SASMMOD1

# Cobol Compiler Data Sets. Example: COBOL.V4R1M0.SIGYCOMP
SIGYCOMP_V4=
SIGYCOMP_V6=IGY630.SIGYCOMP

# PL/I Compiler Data Sets.  Example: PLI.V5R2M0.SIBMZCMP
IBMZPLI_V52=IEL530.SIBMZCMP
IBMZPLI_V51=

# CICS Macro Library. Example: CICSTS.V3R2M0.CICS.SDFHMAC
SDFHMAC=DFH550.CICS.SDFHMAC

# CICS Load Library. Example: CICSTS.V3R2M0.CICS.SDFHLOAD
SDFHLOAD=DFH550.CICS.SDFHLOAD

# CICS COBOL Library. Example: CICSTS.V3R2M0.CICS.SDFHCOB
SDFHCOB=DFH550.CICS.SDFHCOB

# MQ COBOL Library. Example: CSQ.V9R1M0.SCSQCOBC
SCSQCOBC=CSQ911.SCSQCOBC

# MQ Load Library. Example: CSQ.V9R1M0.SCSQLOAD
SCSQLOAD=CSQ911.SCSQLOAD

# DB2 Load Library. Example: DB2.V9R1M0.SDSNLOAD
SDSNLOAD=DSNC10.SDSNLOAD

# IMS Macro Library. Example: DFS.V11R1M0.SDFSMAC
SDFSMAC=DFSF10.SDFSMAC

# IMS RESLIB. Example: DFS.V11R1M0.SDFSRESL
SDFSRESL=DFSF10.USER.SDFSRESL

# User generated library for DB/DC and DC installations. Example: DFS.V11R1M0.REFERAL
REFERAL=DFSF10.REFERAL

# IBM Debug Library containing Exits
SEQAMOD=EQAF00.SEQAMOD

# Optional IDz Load Library. Example: FEL.V14R0M0.SFELLOAD
SFELLOAD=FELE20.SFELLOAD

# Optional IDZ zUnit / WAZI VTP library containing necessary copybooks. Example : FEL.V14R2.SBZUSAMP
SBZUSAMP=T

DBBサーバーへのアクセスを行う際のパスワードを保持するファイルを作成。

TAGUCHI:/u/dbb_common: >/usr/lpp/IBM/dbb/bin/pwf.sh pass.txt
Enter Password
xxxx
/usr/lpp/java/J8.0_64/bin/java -classpath /usr/lpp/IBM/dbb/lib/*: com.ibm.dbb.repository.CreatePasswordFile pass.txt xxxx

上のファイルを含め、DBBサーバーへのアクセス情報を設定するため、build-conf/build.propertiesを環境に合わせて以下のようにカスタマイズ。

build-conf/build.properties

/u/dbb_common/dbb-zappbuild/build-conf/build.properties

# Build properties used by build.groovy

#
# Comma separated list of additional build property files to load
# Supports both relative path (to zAppBuild/build-conf/) and absolute path
buildPropFiles=datasets.properties,Assembler.properties,BMS.properties,MFS.properties,PSBgen.properties,DBDgen.properties,ACBgen.properties,Cobol.properties,LinkEdit.properties,PLI.properties,ZunitConfig.properties

#
# file extension that indicates the build file is really a build list or build list filter
buildListFileExt=txt

#
# Alternate root directory for application-conf locations.  Allows for the deployment of
# the application-conf directories to an alternate location rather in the application repository.
# The expectation is that the root directory will have subfolders for all of the applications built
# by zAppBuild in which the actual application-conf directory is located:
#
# Example: Static location on USS
# applicationConfRootDir=/u/build/config/applications
# |- /u/build/config/applications
# |                       |- App1
# |                       |    |- application-conf
# |                       |    |        |- application.properties
# |                       |- App2
# |                       |    |- application-conf
#
# Example: Application cofig files stored in zAppBuild
# applicationConfRootDir=${zAppBuildDir}/applications
# |- /u/build/zAppBuild/applications
# |                          |- App1
# |                          |    |- application-conf
# |                          |    |        |- application.properties
# |                          |- App2
# |                          |    |- application-conf
#
# Defaults to ${workspace}
applicationConfRootDir=

#
# Comma separated list of required build properties for zAppBuild/build.groovy
requiredBuildProperties=buildOrder,buildListFileExt

# dbb.file.tagging controls compile log and build report file tagging. If true, files
# written as UTF-8 or ASCII are tagged. The default value is false. If the environment
# variable _BPXK_AUTOCVT is set ALL, file tagging may have an adverse effect if viewing
# log files and build report via Jenkins. In this case, set dbb.file.tagging to false or
# comment out the line. Default: true
dbb.file.tagging=true

# Set filter used to exclude certain information from the link edit scanning.
# The value contains a comma separated list of patterns.
# example: A filter of *.SUB1, *.SUB2 will exclude modules SUB1 and SUB2
#          from any dataset. To exclude member HELLO in PDS TEST.ASM will
#          be matched by the pattern TEST.ASM.HELLO. The pattern TEST.ASM.*
#          will match any member in the data set TEST.COBOL.
# The following filter excludes CICS and LE Library references.
dbb.LinkEditScanner.excludeFilter = ${SDFHLOAD}.*, ${SCEELKED}.*

#
# Determine the behavior when facing a scanner failure
# 'true' proceeds with the build and report the a warning (default)
# 'false' will terminate the build process
continueOnScanFailure=true

#
# default DBB Repository Web Application authentication properties
# can be overridden by build.groovy script options

# build.groovy option -url, --url
dbb.RepositoryClient.url=https://127.0.0.1:9998/dbb

# build.groovy option -id, --id
dbb.RepositoryClient.userId=ADMIN

# build.groovy option -pw, --pw
#dbb.RepositoryClient.password=

# build.groovy option -pf, --pf
#dbb.RepositoryClient.passwordFile=${zAppBuildDir}/utilities/ADMIN.pw
dbb.RepositoryClient.passwordFile=/u/dbb_common/pass.txt

# Use dbb.RepositoryClient.sslProtocols to specify one or more SSL protocols used
# to communication between DBB toolkit and server. Use a comma as separator for more
# than one protocol. Requires toolkit PTF UI72423 or version 1.1.0 or higher
# examples
# dbb.RepositoryClient.sslProtocols=TLSv1.2
# dbb.RepositoryClient.sslProtocols=TLS,TLSv1.2

# The dbb.gateway.type property determines which gateway type is used for the entire build process
# Possible values are 'legacy' and 'interactive.  Default if not indicated is 'legacy'
dbb.gateway.type=legacy

# Procedure Name - specified with the procname parameter
dbb.gateway.procedureName=

# Account number - specified with the acctnum parameter
dbb.gateway.accountNumber=

# Group name - specified with a groupid parameter
dbb.gateway.groupId=

# Region size - specified with the regionsz parameter
dbb.gateway.regionSize=

# Gateway logging level.  Add values for multiple types:
# 1 - Log error information
# 2 - Log debug information
# 4 - Log communication information
# 8 - Log time information
# 16 - Log information to the system console
dbb.gateway.logLevel=2

Jenkins:ノード構成

Jenkinsから管理対象ノードの構成を行っておく必要があります。

参考:
Jenkinsノード構成
 Jenkins:ノード定義変更

具体例

起動時の主要パラメータ補足:

パラメーター	値
Javaのパス	/usr/lpp/java/J8.0_64/bin/java
JVMオプション	-Xquickstart -Dfile.encoding=UTF-8 -Xnoargsconversion -Dorg.jenkinsci.plugins.gitclient.CliGitAPIImpl.user.name.file.encoding=IBM-1047 -Dorg.jenkinsci.plugins.gitclient.CliGitAPIImpl.user.password.file.encoding=IBM-1047 -Dorg.jenkinsci.plugins.gitclient.CliGitAPIImpl.user.passphrase.file.encoding=IBM-1047
Prefix Start Agent Command	. /usr/lpp/IBM/dbb/conf/gitenv.sh && export GIT_CONFIG_NOSYSTEM=0 && export JAVA_HOME=/usr/lpp/java/J8.0_64 && export IBM_JAVA_ENABLE_ASCII_FILETAG=ON && env &&
Suffix Start Agent Command	-text(先頭にブランクを入れる)

環境変数補足:

パラメーター	値	補足
DBB_HOME	/usr/lpp/IBM/dbb	DBBがインストールされているディレクトリ
ZAPPBUILD_HOME	/u/dbb_common/dbb-zappbuild	zAppBuildをセットアップしたディレクトリ
DBB_BUILD_EXTRA_OPTS	-DBB_DAEMON_HOST 127.0.0.1 -DBB_DAEMON_PORT 7380	zAppBuild実行時の追加オプション

アプリケーションの準備

ここでは、既存の一連のアプリケーションの単位(ソースの集合体)があって、それをGitでの管理に移行するイメージで考えます。

上の赤枠部分をセットアップするイメージです。

Gitリポジトリ作成(リポジトリ管理者)

アプリケーションごとにGit Server上にリポジトリを作成し、関連するソースコードをリポジトリ上に配置します。

ビルド・エンジニアのガイドに従い、リポジトリ上に以下のファイルを整備していきます。

アプリケーションのソース: 管理対象のソース一式(COPY BOOK等を含む)
application-conf以下のプロパティ: zAppBuildでビルドを行う場合にアプリケーション依存の属性を設定するプロパティを設定(対象のソース、コンパイル・オプション、順序性など)
zappファイル: 開発者がコード修正やUserBuildを行う際にローカルでのファイルの依存関係(COBOL COPY句の探索パス)や、UserBuild時のオプションなどをアプリケーション、UT環境に合わせて設定
.gitattributesファイル: Rocket GitでUSSにリポジトリをクローンする際のファイルごとの文字コード変換情報を指定
Jenkinsファイル: IT環境でのビルドや後続の処理(テスト等)を行うパイプラインの定義を行う

参考:
application-conf
zappファイルの編集
 .gitattributesファイルの作成(GitHub)
Jenkinsfile(Pipeline Script)作成

具体例

以下のzopeneditor-sampleをそのままコピーし、別のリポジトリ"Tag-test01-sample"として作成
コピー元(https://github.com/IBM/zopeneditor-sample/)
※ここの手順の詳細は割愛

wazi-masterブランチをマスターとしてカスタマイズしていきます。

application-conf/application.propertiesのカスタマイズします。(不要なビルドが行われないよう一部のソースはビルド対象外としてexcludeFileListに指定します。)

application-conf/application.properties

...
excludeFileList=.*,**/*.properties,**/*.xml,**/*.groovy,**/*.md,**/application-conf/*.*,COBOL/SAM1LIB.cbl,PLI/PSAM1LIB.pli,ASM/IRR@XACS.asm,ASMCOPY/REGISTRS.asm
...

application-conf/Cobol.propertiesをカスタマイズし、デバッグ用のオプションを追加します。

application-conf/Cobol.properties

...
cobol_compileDebugParms=TEST(SOURCE)
...

zapp-example.jsonをコピーしてzapp.jsonを作成します。(profiles部分を修正)

zapp.json

zapp.json

{
  "_copyright": "(C) COPYRIGHT IBM CORPORATION 2020, 2021. ALL RIGHTS RESERVED",
  "name": "sam",
  "description": "Wazi's code samples with COBOL, PL/I, and HLASM applications",
  "version": "1.1.0",
  "author": {
    "name": "IBM CORPORATION"
  },
  "property-groups": [
    {
      "name": "cobol-local",
      "language": "cobol",
      "type": "local",
      "syslib": [
        "**/COPYBOOK"
      ],
      "libraries": [
        {
          "name": "MYFILE",
          "locations": [
            "**/COPYLIB"
          ]
        }
      ]
    },
    {
      "name": "pl1-local",
      "language": "pl1",
      "compilerOptions": "not(!)",
      "type": "local",
      "syslib": [
        "**/INCLUDES"
      ],
      "libraries": [
        {
          "name": "MYFILE",
          "locations": [
            "**/INCLUDELIB"
          ]
        }
      ]
    },
    {
      "name": "hlasm-local",
      "language": "hlasm",
      "type": "local",
      "syslib": [
        "**/ASMCOPY"
      ]
    },
    {
      "name": "zowe-mvs-cbl",
      "language": "cobol",
      "type": "mvs",
      "system": "zos1000.example.com",
      "syslib": [
        "USER1.SAMPLE.COBCOPY"
      ],
      "libraries": [
        {
          "name": "MYLIB",
          "locations": [
            "USER1.SAMPLE.COPYLIB"
          ]
        }
      ]
    },
    {
      "name": "zowe-mvs-pl1",
      "language": "pl1",
      "type": "mvs",
      "system": "zos1000.example.com",
      "syslib": [
        "USER1.SAMPLE.PLINC"
      ],
      "libraries": [
        {
          "name": "MYLIB",
          "locations": [
            "USER1.SAMPLE.PLI.INCLLIB"
          ]
        }
      ]
    }
  ],
  "profiles": [
    {
      "name": "dbb-userbuild",
      "type": "dbb",
      "settings": {
        "command": "$DBB_HOME/bin/groovyz",
        "buildScriptPath": "/u/dbb_common/dbb-zappbuild/build.groovy",
        "buildScriptArgs": [
          "-DBB_DAEMON_HOST 127.0.0.1",
          "-DBB_DAEMON_PORT 7380",
          "--userBuild",
          "--workspace ${zopeneditor.userbuild.userSettings.dbbWorkspace}",
          "--application Tag-test01-sample",
          "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}",
          "--outDir ${zopeneditor.userbuild.userSettings.dbbLogDir}"
        ],
        "additionalDependencies": [
          "application-conf"
        ]
      }
    },
    {
      "name": "RSE-Mappings",
      "type": "rseapi",
      "settings": {
        "mappings": [
          {
            "resource": "**.SAMPLE.COB**",
            "extension": "cbl",
            "transfer": "text",
            "encoding": "IBM-037",
            "memberMappings": [
              {
                "extension": "dat",
                "transfer": "binary",
                "resource": "*DAT"
              }
            ]
          },
          {
            "resource": "**PLI*",
            "extension": "pl1",
            "transfer": "text",
            "encoding": "IBM-037"
          }
        ],
        "default.encoding": "IBM-037"
      }
    }
  ]
}

.gitattributesファイルはサンプル提供のものをそのまま利用。

.gitattributes

.gitattributes

*.cpy zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.cbl zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.jcl zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.bms zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.pli zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.inc zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.asm zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.mfs zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.bnd zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.lnk zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.rex zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.txt zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.groovy zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.sh zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.properties zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.rexx zos-working-tree-encoding=ibm-1047 git-encoding=utf-8
*.config zos-working-tree-encoding=ibm-1047 git-encoding=utf-8

Jenkinsファイル作成。

Jenkinsfile

Jenkinsfile

// variables for Git
def srcGitRepo = null
def srcGitBranch = null
def srcGitCredentialsId = null
def srcGitRepoName = null

// variables for DBB, zAppBuild
def dbbHome = null
def zAppBuildHome = null
def dbbBuildExtraOpts = null

pipeline {
   agent {label 'wazi-test01'}

   options {
      skipDefaultCheckout(true)
   }

   stages {
      stage('Git Clone'){
         steps {
            script {
               // variables for Git
               srcGitRepo = scm.getUserRemoteConfigs()[0].getUrl()
               srcGitBranch = scm.branches[0].name
               srcGitCredentialsId = scm.getUserRemoteConfigs()[0].getCredentialsId()
               srcGitRepoName = srcGitRepo.tokenize('/').last().tokenize('\\.')[0]

               dir(srcGitRepoName){
                  /*sh """
                     echo 'srcGitRepo: ' $srcGitRepo
                     echo 'srcGitBranch: ' $srcGitBranch
                     echo 'srcGitCredentialsId: ' $srcGitCredentialsId
                     echo 'srcGitRepoName: ' $srcGitRepoName
                  """*/
                  def scmVars = checkout([
                     $class: 'GitSCM',
                     branches: [[name: srcGitBranch]],
                     userRemoteConfigs: [[ credentialsId: srcGitCredentialsId, url: srcGitRepo ]]
                  ])
               }
            }
         }
      }
      stage('Hello') {
         steps {
            echo 'Hello World'
         }
      }
      stage('Build'){
         steps {
            script {
               // variables for DBB, zAppBuild
               dbbHome = env.DBB_HOME
               zAppBuildHome = env.ZAPPBUILD_HOME
               dbbBuildExtraOpts = env.DBB_BUILD_EXTRA_OPTS

               sh """
                  $dbbHome/bin/groovyz $zAppBuildHome/build.groovy \
                     $dbbBuildExtraOpts  \
                     --logEncoding UTF-8 \
                     --workspace ${WORKSPACE} \
                     --application $srcGitRepoName \
                     --hlq JENKIN2.DBB \
                     --outDir /u/JENKIN2/logs \
                     --fullBuild
               """
            }
         }
      }
      stage('Test'){
          steps{
              echo 'Test Dummy'
          }
      }
      stage('Deploy'){
          steps{
              echo 'Deploy Dummy'
          }
      }
   }
}

※このJenkinsfileの例では前回の記事と異なりcheckout(Git Clone)をstepの中で明示的に実行しています(デフォルトで実行されるSCM checkoutだとディレクトリ名など細かな制御がしにくいため)。そのため、オプションでskipDefaultCheckout(true)を指定してデフォルトで実施されるcheckout処理を無効化しています。

Jenkins:Pipeline定義(ビルド・エンジニア)

上で作成したアプリケーション、Jenkinsfile(Pipeline Script)に紐づくJobの定義をJenkins上に行います。Webhookにより自動実行する設定を行うため、Multibranch Pipelineとして定義します。

参考: Jenkins: Pipeline定義

具体例

Branch SourcesとしてGitを追加

プロジェクト・リポジトリ: 上で作成したGitHub上のリポジトリを指定
Behaviors: "Filter by name"を追加し、includeに"wazi-master*"を指定 (wazi-master*ブランチのみを対象とする)
Trigger token: my-token01を指定(後続のWebhook設定で使用)

Webhook設定(リポジトリ管理者)

上で定義したPipeline定義に合わせてGiHubリポジトリ上にWebhookの設定を追加します。

参考:
GitServer: Webhookの設定

具体例

(1)コード修正 (コード開発者)

赤枠の中の操作を実施するイメージです。

環境整備

ビルド・エンジニアのガイドに従って、各PCの環境整備を行っておきます。(逆に言うとビルド・エンジニアはこの辺りの設定/利用ガイドも作成する必要があります)
実施する内容は主に以下の通りです。

Gitインストール、基本構成
Zowe CLIインストール
VSCodeおよび関連Extensionインストール
z/OS接続構成
- Zowe CLIのz/OSMFプロファイル作成
- Zowe CLIのsshプロファイル作成
- Debugger接続構成
VSCode上の各種プロパティ設定

参考:
VSCodeインストール
 DBB用設定
 Debugger用設定

VSCode設定例

上で設定したdbbWorkspace用のディレクトリ、dbbLogDir用のディレクトリをUSS上に作成しておきます。(dbbLogDirはDBB Daemonの実行ユーザーが書き込みできるようパーミッションを設定)

リポジトリのクローン

新規にVSCodeワークスペースを作成します。

適当なディレクトリを作成して保存

Ctrl + Shit + P から Git: Clone

GitHubのRepositoryを指定

適当なディレクトリを指定(ここではVSCodeワークスペースのディレクトリを指定)

ワークスペースに追加

ブランチ作成

ブランチを"wazi-master"に切替

新規ブランチ作成

ここではdev-tag02というブランチ名を指定

コード修正

SAM1.cblを修正 (ここではDISPLAY文を追加するのみ)

ビルド

まず、ビルド用のセットアップ処理を行います。
ソースを右クリックし、"Run Setup for IBM User Build"を選択

Run Setupのログ

Welcome to IBM User Build. Run User Build commands from the context menu in an open editor with a COBOL, PL/I, or HLASM program.
Visit our Knowledge Center to learn about IBM User Build here: https://www.ibm.com/support/knowledgecenter/SSCH39.
=====================
Running setup for user build...
Setup will upload files or folders defined in your ZAPP file or in .vscode/settings.json under "zopeneditor.userbuild.userSettings.additionalDependencies".
Checking ZAPP file or workspace settings...
DBB ZAPP or workspace settings should be defined in either your repository's zapp.yaml, zapp.json or .vscode/settings.json file.
    command: $DBB_HOME/bin/groovyz
    buildScriptArgs: -DBB_DAEMON_HOST 127.0.0.1,-DBB_DAEMON_PORT 7380,--userBuild,--workspace /u/TAGUCHI/projects,--application Tag-test01-sample,--hlq TAGUCHI.DBB,--outDir /u/TAGUCHI/projects/logs
    buildScriptPath: /u/dbb_common/dbb-zappbuild/build.groovy
    additionalDependencies: application-conf
---------------------
Checking user settings...
User settings should be defined in your VS Code or Theia Settings under zopeneditor.userbuild.userSettings
    localWorkspacePath: **Optional setting is missing**
    dbbWorkspace: /u/TAGUCHI/projects
    dbbHlq: TAGUCHI.DBB
    dbbLogDir: /u/TAGUCHI/projects/logs
---------------------
Using ssh profile ssh_Wazi01
Using Zowe profile prof_Wazi01

Checking if SSH profile ssh_Wazi01 can connect:
Connected successfully.

Identified local root workspace path as c:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample
Running setup to build c:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample\COBOL\SAM1.cbl program.
Executing ssh command: 
mkdir -p '/u/TAGUCHI/projects/Tag-test01-sample'
@@START OF COMMAND@@
$ mkdir -p '/u/TAGUCHI/projects/Tag-test01-sample'
Uploading additional dependencies...
Uploading c:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample\application-conf
Executing ssh command: 
mkdir -p '/u/TAGUCHI/projects/Tag-test01-sample/application-conf'
$ mkdir -p '/u/TAGUCHI/projects/Tag-test01-sample/application-conf'
User build setup FINISHED.

ビルドします。
ソースを右クリックし、"Run IBM User Build with full upload"を選択

Run IBM User Buildのログ

=====================
Running user build...
Identified local root workspace path as c:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample
---------------------
Checking ZAPP file or workspace settings...
DBB ZAPP or workspace settings should be defined in either your repository's zapp.yaml, zapp.json or .vscode/settings.json file.
    command: $DBB_HOME/bin/groovyz
    buildScriptArgs: -DBB_DAEMON_HOST 127.0.0.1,-DBB_DAEMON_PORT 7380,--userBuild,--workspace /u/TAGUCHI/projects,--application Tag-test01-sample,--hlq TAGUCHI.DBB,--outDir /u/TAGUCHI/projects/logs
    buildScriptPath: /u/dbb_common/dbb-zappbuild/build.groovy
    additionalDependencies: application-conf
---------------------
Checking user settings...
User settings should be defined in your VS Code or Theia Settings under zopeneditor.userbuild.userSettings
    localWorkspacePath: **Optional setting is missing**
    dbbWorkspace: /u/TAGUCHI/projects
    dbbHlq: TAGUCHI.DBB
    dbbLogDir: /u/TAGUCHI/projects/logs
---------------------
Using ssh profile ssh_Wazi01
Using Zowe profile prof_Wazi01

Checking if SSH profile ssh_Wazi01 can connect:
Connected successfully.

Executing ssh command: 
mkdir -p '/u/TAGUCHI/projects/Tag-test01-sample/COBOL'
$ mkdir -p '/u/TAGUCHI/projects/Tag-test01-sample/COBOL'
Uploading c:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample\COBOL\SAM1.cbl with encoding ibm-1047
Found total of 2 local include files:
C:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample\COPYBOOK\CUSTCOPY.cpy
C:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample\COPYBOOK\TRANREC.cpy
Executing ssh command: 
mkdir -p '/u/TAGUCHI/projects/Tag-test01-sample/COPYBOOK'
$ mkdir -p '/u/TAGUCHI/projects/Tag-test01-sample/COPYBOOK'
Uploading C:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample\COPYBOOK\CUSTCOPY.cpy with encoding ibm-1047
Uploading C:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample\COPYBOOK\TRANREC.cpy with encoding ibm-1047
---------------------
Executing ssh command: 
$DBB_HOME/bin/groovyz /u/dbb_common/dbb-zappbuild/build.groovy -DBB_DAEMON_HOST 127.0.0.1 -DBB_DAEMON_PORT 7380 --userBuild --workspace /u/TAGUCHI/projects --application Tag-test01-sample --hlq TAGUCHI.DBB --outDir /u/TAGUCHI/projects/logs /u/TAGUCHI/projects/Tag-test01-sample/COBOL/SAM1.cbl
$ $DBB_HOME/bin/groovyz /u/dbb_common/dbb-zappbuild/build.groovy -DBB_DAEMON_H
$
$ bb-zappbuild/build.groovy -DBB_DAEMON_HO                                    <ST 127.0.0.1 -DBB_DAEMON_PORT 7380 -
$
$ _HOST 127.0.0.1 -DBB_DAEMON_PORT 7380 --                                    <userBuild --workspace /u/TAGUCHI/pro
$
$  --userBuild --workspace /u/TAGUCHI/proj                                    <ects --application Tag-test01-sample
$
$ rojects --application Tag-test01-sample                                     <--hlq TAGUCHI.DBB --outDir /u/TAGUCH
$
$ le --hlq TAGUCHI.DBB --outDir /u/TAGUCHI                                    </projects/logs /u/TAGUCHI/projects/T
$
$ CHI/projects/logs /u/TAGUCHI/projects/Ta                                    <g-test01-sample/COBOL/SAM1.cbl
** Build start at 20210327.113259.032
** Build output located at /u/TAGUCHI/projects/logs
** Adding /u/TAGUCHI/projects/Tag-test01-sample/COBOL/SAM1.cbl to Building build list
** Writing build list file to /u/TAGUCHI/projects/logs/buildList.txt
** Invoking build scripts according to build order: BMS.groovy,Cobol.groovy,Assembler.groovy,PLI.groovy,LinkEdit.groovy
** Building files mapped to Cobol.groovy script
*** Building file Tag-test01-sample/COBOL/SAM1.cbl
** Writing build report data to /u/TAGUCHI/projects/logs/BuildReport.json
** Writing build report to /u/TAGUCHI/projects/logs/BuildReport.html
** Build ended at Sat Mar 27 11:33:13 GMT 2021
** Build State : CLEAN
** Total files processed : 1
** Total build time  : 13.830 seconds

__RC=0__
** Build finished
Looking for user-build logs in "/u/TAGUCHI/projects/logs".
Downloading logs to c:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample\logs
Downloading log file /u/TAGUCHI/projects/logs/buildList.txt. Binary: false
Downloading log file /u/TAGUCHI/projects/logs/SAM1.log. Binary: false
Downloading log file /u/TAGUCHI/projects/logs/BuildReport.json. Binary: true
Downloading log file /u/TAGUCHI/projects/logs/BuildReport.html. Binary: true
Downloading log file /u/TAGUCHI/projects/logs/ASAM1.log. Binary: false
Downloading log file /u/TAGUCHI/projects/logs/SAM1LIB.log. Binary: false
Downloading log file /u/TAGUCHI/projects/logs/SAM2.log. Binary: false
Downloading of 7 log files to c:\y\VSCode_workspace\DeveloperTest01_Sample\Tag-test01-sample\logs finished successfully.

ビルドはうまくいきました。

デバッグ

デバッグを行うために、デバッグ用にビルドしなおします。
zappファイルを修正し、デバッグオプション"--debug"をbuildScriptArgsに追加します。

zapp.json

...
  "profiles": [
    {
      "name": "dbb-userbuild",
      "type": "dbb",
      "settings": {
        "command": "$DBB_HOME/bin/groovyz",
        "buildScriptPath": "/u/dbb_common/dbb-zappbuild/build.groovy",
        "buildScriptArgs": [
          "-DBB_DAEMON_HOST 127.0.0.1",
          "-DBB_DAEMON_PORT 7380",
          "--userBuild",
          "--debug",
          "--workspace ${zopeneditor.userbuild.userSettings.dbbWorkspace}",
          "--application Tag-test01-sample",
          "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}",
          "--outDir ${zopeneditor.userbuild.userSettings.dbbLogDir}"
        ],
        "additionalDependencies": [
          "application-conf"
        ]
      }
...

変更を保存し、Setup, Buildを実行しなおします。SAM1.cbl, SAM2.cblの2つに対してBuildを行います。

"--debug"オプション付きでビルドを行うと、application-conf/Cobol.propertiesのcobol_compileDebugParmsに指定されている値(ここでは"TEST(SOURCE)")がコンパイルオプションとして追加されます。

logsディレクトリ以下にコンパイル時のSYSPRINTの結果がダウンロードされるので、TEST(SOURCE)オプションが指定されてコンパイルされたか確認します。

以下にならって、デバッグ用のlaunch.jsonファイルを作成、必要に応じてTLS通信用の証明書のインポートを行います。
参考: launch.jsonファイル作成

launch.json

launch.json

{
	"folders": [
		{
			"name": "Tag-test01-sample",
			"path": "Tag-test01-sample"
		}
	],
	"launch": {
		"version": "0.2.0",
		"configurations": [
			{
				"type": "zOpenDebug",
				"request": "launch",
				"name": "Connect to parked IBM Z Open Debug session",
				"useConnectionDetailsFromSettings": false,
				"host": "ocpw01",
				"port": 31125,
				"secure": true,
				"ignoreCertificateErrors": true,
				"password":"${command:AskForPassword}"
			},
			{
				"type": "zOpenDebug",
				"request": "attach",
				"name": "List parked IBM Z Open Debug sessions",
				"useConnectionDetailsFromSettings": false,
				"host": "ocpw01",
				"port": 31125,
				"secure": true,
				"ignoreCertificateErrors": true,
				"user": "TAGUCHI"
			}
		]
	}
}

SAM1.cblはSAM2.cblをCALLしています。また、SAMファイルをアクセスしているので実行するにはその辺りのセットアップを行う必要があります。以下を参考に、必要なデータセットのアロケートとSAMファイルのアップロードを行います。
参考:ジョブをコンパイル、リンク、および実行するための JCL の実行依頼チュートリアル

RUN.jclを元にして、デバッグオプションを指定したCOBOLバッチ実行用JCLを作成します。

SAM1DEBUG

SAM1DEBG

//SAM1DEBG JOB ,NOTIFY=&SYSUID,
// MSGCLASS=H,MSGLEVEL=(1,1),REGION=144M
//*****************************************************************
//    SET HLQ='TAGUCHI'                       *TSO USER ID
//    SET DBBHLQ='TAGUCHI.DBB'
//*************************
//* CLEAN UP
//*************************
//DELETE   EXEC PGM=IEFBR14
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//DD1      DD DSN=&HLQ..SAMPLE.CUSTRPT,DISP=(MOD,DELETE,DELETE),
//            UNIT=SYSDA,SPACE=(CYL,(0))
//DD2      DD DSN=&HLQ..SAMPLE.CUSTOUT,DISP=(MOD,DELETE,DELETE),
//            UNIT=SYSDA,SPACE=(CYL,(0))
/*
//*************************
//* RUN SAM1
//*************************
//SAM1  EXEC   PGM=SAM1
//STEPLIB  DD DSN=EQAF00.SEQAMOD,DISP=SHR
//         DD DSN=&DBBHLQ..LOAD,DISP=SHR
//CEEOPTS DD *
TEST(,,,RDS:*)
//*
//SYSOUT   DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//*
//* INPUT CUSTOMER FILE
//CUSTFILE DD DISP=SHR,DSN=&HLQ..SAMPLE.CUSTFILE
//*
//* INPUT TRANSACTION FILE
//TRANFILE DD DISP=SHR,DSN=&HLQ..SAMPLE.TRANFILE
//*
//* NEW CUSTOMER FILE
//CUSTOUT  DD DSN=&HLQ..SAMPLE.CUSTOUT,
//    DISP=(NEW,CATLG),UNIT=SYSDA,SPACE=(TRK,(10,10),RLSE),
//    DSORG=PS,RECFM=VB,LRECL=600,BLKSIZE=604
//*
//* OUTPUT CUSTRPT FILE
//CUSTRPT  DD DSN=&HLQ..SAMPLE.CUSTRPT,
//    DISP=(NEW,CATLG),UNIT=SYSDA,SPACE=(TRK,(10,10),RLSE),
//    DSORG=PS,RECFM=FB,LRECL=133,BLKSIZE=0

以下を参考にデバッグプロファイルを作成、有効化します(オプション)。
参考: Debugプロファイル準備

デバッグを実行します。

実行状況を確認しながら、必要に応じて適宜コード修正作業を実施します。

コミット/プッシュ

変更した内容を確認し、ステージング

コミットメッセージを記入してコミット

変更をプッシュ

OK

ブランチ状況確認 (Git History Extensionを使用しています)

新しくブランチを作成して、そのブランチ上でコードの修正を行い、リモートのリポジトリにプッシュされた状態になりました。
これで個別のコード修正の流れは一通り確認できました。

(2)ブランチのマスターへのマージによる後続処理の自動化

プル・リクエスト(コード開発者)

上で作成した新たなブランチをマスターのブランチにマージしてもらうべく、"Pull Request"の処理を行います。

ブラウザから当該リポジトリにアクセスし、作成したブランチの横の"Compare & pull request"をクリックします。

マージ先となるbaseとしてwazi-master、マージ元のcompareに今回作成したブランチdev-tag02を指定します。また、変更内容の指定やAssigneeなどを指定して、pull requestを作成します。(とりあえずここでは自分をAssigneeに指定)

Pull Requestが作成されました。

レビュー、マージ(リポジトリ管理者)

リポジトリ管理者は、Pull Requestが上がってきたらその内容をチェックします。(他にReviewerなどがいれば各Reviewerのコメントなども参照します。)

最終的にOKと判断されたら、そのブランチをマスターにマージします。
以下の"Merge pull request"をクリック

"Attmpt merge"をクリック

マージされました。

上のマージをトリガーに、JenkinsのPipelineが自動で起動します。

Jenkins Pipelineのログ

Branch indexing
 > git rev-parse --is-inside-work-tree # timeout=10
Setting origin to https://github.xxx.xxx/ISE-Showroom-MF/Tag-test01-sample.git
 > git config remote.origin.url https://github.xxx.xxx/ISE-Showroom-MF/Tag-test01-sample.git # timeout=10
Fetching origin...
Fetching upstream changes from origin
 > git --version # timeout=10
 > git --version # 'git version 1.8.3.1'
 > git config --get remote.origin.url # timeout=10
using GIT_ASKPASS to set credentials GitHub Enterprise Token
 > git fetch --tags --progress origin +refs/heads/*:refs/remotes/origin/* # timeout=10
Seen branch in repository origin/dev-tag01
Seen branch in repository origin/dev-tag03
Seen branch in repository origin/master
Seen branch in repository origin/tutorial-complete
Seen branch in repository origin/wazi-master
Seen branch in repository origin/wazi-tutorial-complete
Seen 6 remote branches
Obtained Jenkinsfile from 9be4aa58f32cbefd26bfd7956dde0651630c6720
Running in Durability level: MAX_SURVIVABILITY
[Pipeline] Start of Pipeline
[Pipeline] node
Running on wazi-test01 in /u/JENKIN2/agent/wazi-test01/workspace/g_test01_sample_wazi-master-3DOOQBEUC2QJMJVRM4PPEDIWOG5RVII2WQW6TATVNUMLYA6AZDYQ
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Git Clone)
[Pipeline] script
[Pipeline] {
[Pipeline] dir
Running in /u/JENKIN2/agent/wazi-test01/workspace/g_test01_sample_wazi-master-3DOOQBEUC2QJMJVRM4PPEDIWOG5RVII2WQW6TATVNUMLYA6AZDYQ/Tag-test01-sample
[Pipeline] {
[Pipeline] checkout
using credential TOMOTAG
 > git rev-parse --is-inside-work-tree # timeout=10
Fetching changes from the remote Git repository
 > git config remote.origin.url https://github.xxx.xxx/ISE-Showroom-MF/Tag-test01-sample.git # timeout=10
Fetching upstream changes from https://github.xxx.xxx/ISE-Showroom-MF/Tag-test01-sample.git
 > git --version # timeout=10
 > git --version # 'git version 2.14.4_zos_b09'
using GIT_ASKPASS to set credentials GitHub Enterprise Token
Using name charset 'IBM1047'
Using password charset 'IBM1047'
 > git fetch --tags --progress -- https://github.xxx.xxx/ISE-Showroom-MF/Tag-test01-sample.git +refs/heads/*:refs/remotes/origin/* # timeout=10
Checking out Revision 9be4aa58f32cbefd26bfd7956dde0651630c6720 (origin/wazi-master)
 > git rev-parse origin/wazi-master^{commit} # timeout=10
 > git config core.sparsecheckout # timeout=10
 > git checkout -f 9be4aa58f32cbefd26bfd7956dde0651630c6720 # timeout=10
Commit message: "Merge pull request #6 from ISE-Showroom-MF/dev-tag01"
 > git rev-list --no-walk ce97833912adb8de442a9a30a503bd35e63daef7 # timeout=10
[Pipeline] }
[Pipeline] // dir
[Pipeline] }
[Pipeline] // script
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (Hello)
[Pipeline] echo
Hello World
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (Build)
[Pipeline] script
[Pipeline] {
[Pipeline] sh
+ /usr/lpp/IBM/dbb/bin/groovyz /u/dbb_common/dbb-zappbuild/build.groovy -DBB_DAEMON_HOST 127.0.0.1 -DBB_DAEMON_PORT 7380 --logEncoding UTF-8 --workspace /u/JENKIN2/agent/wazi-test01/workspace/g_test01_sample_wazi-master-3DOOQBEUC2QJMJVRM4PPEDIWOG5RVII2WQW6TATVNUMLYA6AZDYQ --application Tag-test01-sample --hlq JENKIN2.DBB --outDir /u/JENKIN2/logs --fullBuild 

** Build start at 20210330.055449.054
** Repository client created for https://127.0.0.1:9998/dbb
** Build output located at /u/JENKIN2/logs/build.20210330.055449.054
** Build result created for BuildGroup:Tag-test01-sample-wazi-master BuildLabel:build.20210330.055449.054 at https://127.0.0.1:9998/dbb/rest/buildResult/824
** --fullBuild option selected. Building all programs for application Tag-test01-sample
** Writing build list file to /u/JENKIN2/logs/build.20210330.055449.054/buildList.txt
** Scanning source code.
** Invoking build scripts according to build order: BMS.groovy,Cobol.groovy,Assembler.groovy,PLI.groovy,LinkEdit.groovy
** Building files mapped to Cobol.groovy script
*** Building file Tag-test01-sample/COBOL/SAM2.cbl
*** Building file Tag-test01-sample/COBOL/SAM1.cbl
** Building files mapped to Assembler.groovy script
*** Building file Tag-test01-sample/ASM/ASAM1.asm
** Building files mapped to PLI.groovy script
*** Building file Tag-test01-sample/PLI/PSAM1.pli
*** Building file Tag-test01-sample/PLI/PSAM2.pli
** Writing build report data to /u/JENKIN2/logs/build.20210330.055449.054/BuildReport.json
** Writing build report to /u/JENKIN2/logs/build.20210330.055449.054/BuildReport.html
** Build ended at Tue Mar 30 05:57:50 GMT 2021
** Build State : CLEAN
** Total files processed : 5
** Total build time  : 3 minutes, 1.727 seconds

__RC=0__
** Build finished
[Pipeline] }
[Pipeline] // script
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (Test)
[Pipeline] echo
Test Dummy
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (Deploy)
[Pipeline] echo
Deploy Dummy
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
Finished: SUCCESS

マスターブランチの変更をトリガーに、Pipeline Scriptで指定した処理(今回の例ではBuildのみで、Deploy、Testはダミー)が自動実行されることが確認できました。

おわりに

従来のようなJCLでの管理ではなく、DBB/zAppBuildを使用してビルドを実行することで、VSCode、Jenkinsからビルドの実行が行いやすく、自動化にもつなげられることが確認できたと思います。今回はその先のデプロイやテストといった処理はダミーでしたが、Jenkinsは他にも多様なツールとの連携が行いやすいため、例えばAnsible経由でテスト用のインフラを整えたり、zUnitやVTP(Virtual Test Platform)というテスト自動化のツールを利用したテストの自動化を行ったり、UrbanCode Deployと連携して後続の環境にビルド結果のロードモジュールを配布するなど、CI/CDパイプラインの自動化/効率化の軸としてJenkins Pipelineを利用することができると思います。