Pipeline Customization

IBM Industry Solutions Workbench provides the possibility to define own pipeline types (templates) additionally to the available default pipelines types. Own pipeline types can be based on the default pipeline types to add a few own pipeline tasks or they can be completely different.

Own pipeline types can be created and added to the Solution Designer by creating an Openshift Pipeline Resource in the cluster. This needs to be done directly within the OpenShift Web Console. The default pipeline types can be used as example and starting point.

Prerequisites

Access to the OpenShift Admin Console
Clear understanding of OpenShift (Tekton) Pipelines, PipelineRuns and Tasks, and experience in writing pipelines/tasks using YAML
A copy of the pipeline resources (yaml files) mentioned below.

Create own Pipeline type (template)

Go to the OpenShift Web Console (or login via oc cli)
List all Pipeline resources and filter by label k5-pipeline-template=true
You should get the following Default Pipeline types (template):
- k5-template-java-deploy
- k5-template-java-release
- k5-template-node-deploy
- k5-template-node-release
The easiest way to create an own Pipeline type (in the first place) is to open and copy one of the existing default types, for example k5-template-java-deploy if you want to create an own type and add some additional tasks to a java deploy pipeline
Now you can adjust the metadata in the YAML accordingly and apply it to the cluster, for example:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  annotations:
    k5-display-name: Custom Deploy Pipeline
    k5-supported-stacks: java
  name: k5-template-java-deploy-my-custom
  namespace: namespace
  labels:
    k5-pipeline-type: deploy
    k5-pipeline-template: 'true'

The value in the annotation k5-display-name will be shown as Type in the Solution Designer
The annotation k5-supported-stacks defines for which stack the Type should by shown in the Solution Designer (java or node)
The label k5-pipeline-type which kind of Pipeline type (template) it should be (deploy, release or custom)
The label k5-pipeline-template marks the Pipeline as Pipeline type (template).

Note:

Only if the label k5-pipeline-template is set to true the Pipeline is considered as template and will be shown in the Solution Designer as Type.

Warning:

Own Pipeline templates or own custom Tasks are not managed by IBM Industry Solutions Workbench and therefore will not be updated or migrated. On the other side the default Pipeline templates and Tasks (installed and managed by IBM Industry Solutions Workbench) are always overwritten to the initial state and may also change in an upcoming version of IBM Industry Solutions Workbench in the future.

Different Pipeline types

As mentioned before there are three kinds of Pipeline types (templates): deploy, release and custom.

The difference is based on the purpose and on the input parameters that are provided by the Solution Designer.

The following input params are provided and expected by the different Pipeline types:

deploy
- repo-url: Defines the repository url
- revision: Defines the revision (or branch) of the git repository
- unittestfeature: Defines if unit tests should be executed
- prereleaseuniqueness: Defines whether it needs to be a unique pre-release
- enforceuniqueness: Defines where uniqueness needs to be enforced
- uniquesemvercheck: Defines whether a unique semVer check is executed
- solutionacronym: Defines the acronym of the service project
- k5project: Defines in which k5project it should be deployed
release
- repo-url: Defines the repository url
- revision: Defines the revision (or branch) of the git repository
- unittestfeature: Defines if unit tests should be executed
- prereleaseuniqueness: Defines whether it needs to be a unique pre-release
- enforceuniqueness: Defines where uniqueness needs to be enforced
- uniquesemvercheck: Defines whether a unique semVer check is executed
- solutionacronym: Defines the acronym of the service project
custom
- repo-url: Defines the repository url
- revision: Defines the revision (or branch) of the git repository
- solutionacronym: Defines the acronym of the service project

Note:

Depending on the k5-pipeline-type label the View and possible Parameters in the Solution Designer will be different, see also Pipeline Features.

Define Tasks in a Custom Pipeline Type

All Tasks that should be executed for this kind of pipeline are listed and defined in the tasks section of the Pipeline type (template). You can easily remove existing ones or add own Task to your custom pipeline type.

Tip:

You can see all available tasks by clicking Pipelines → Tasks in the left navigation area of the OpenShift Web Console

Custom Pipeline Type Example

The following example shows a manually created custom Deploy Pipeline that can be added as template to the cluster. The Pipeline contains all default Tasks provided by IBM Industry Solutions Workbench and additionally one custom Task (k5-custom-task) that will be executed before the Deploy Task (k5-deploy). After applying it into the IBM Industry Solutions Workbench namespace, the "Custom Deploy Pipeline" Pipeline Type will be available in the Solution Designer while creating a new CI/CD Pipeline configuration for all java service projects:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  annotations:
    k5-display-name: Custom Deploy Pipeline
    k5-supported-stacks: java
  name: k5-template-java-deploy-custom
  labels:
    k5-pipeline-template: 'true'
    k5-pipeline-type: deploy
spec:
  params:
    - description: Defines the repository url
      name: repo-url
      type: string
    - description: Defines the revision of the git repository
      name: revision
      type: string
    - description: Defines if unit tests should be executed
      name: unittestfeature
      type: string
    - description: Defines whether it needs to be a unique pre-release
      name: prereleaseuniqueness
      type: string
    - description: Defines where uniqueness needs to be enforced
      name: enforceuniqueness
      type: string
    - description: Defines in which k5project it should be deployed
      name: k5project
      type: string
    - description: Defines the solution acronym
      name: solutionacronym
      type: string
    - description: Defines whether a unique semVer check is executed
      name: uniquesemvercheck
      type: string
  tasks:
    - name: k5-git-clone
      params:
        - name: repo-url
          value: $(params.repo-url)
        - name: revision
          value: $(params.revision)
      taskRef:
        kind: Task
        name: k5-git-clone
      workspaces:
        - name: output
          workspace: source
        - name: basic-auth
          workspace: basic-auth
    - name: k5-validate
      params:
        - name: solutionacronym
          value: $(params.solutionacronym)
        - name: stack
          value: java
        - name: prereleaseuniqueness
          value: $(params.prereleaseuniqueness)
        - name: uniquesemvercheck
          value: $(params.uniquesemvercheck)
        - name: enforceuniqueness
          value: $(params.enforceuniqueness)
      runAfter:
        - k5-git-clone
      taskRef:
        kind: Task
        name: k5-validate
      workspaces:
        - name: source
          workspace: source
    - name: k5-generate-code-java
      params:
        - name: solutionacronym
          value: $(params.solutionacronym)
        - name: stack
          value: java
      runAfter:
        - k5-validate
      taskRef:
        kind: Task
        name: k5-generate-code-java
      workspaces:
        - name: source
          workspace: source
    - name: k5-build-application-java
      params:
        - name: solutionacronym
          value: $(params.solutionacronym)
        - name: stack
          value: java
        - name: unittestfeature
          value: $(params.unittestfeature)
      runAfter:
        - k5-generate-code-java
      taskRef:
        kind: Task
        name: k5-build-application-java
      workspaces:
        - name: source
          workspace: source
    - name: k5-build-publish-image-java
      params:
        - name: solutionacronym
          value: $(params.solutionacronym)
        - name: stack
          value: java
      runAfter:
        - k5-build-application-java
      taskRef:
        kind: Task
        name: k5-build-publish-image-java
      workspaces:
        - name: source
          workspace: source
    - name: k5-build-publish-chart-java
      params:
        - name: solutionacronym
          value: $(params.solutionacronym)
        - name: publish
          value: $(params.publish)
        - name: stack
          value: java
      runAfter:
        - k5-build-publish-image-java
      taskRef:
        kind: Task
        name: k5-build-publish-chart-java
      workspaces:
        - name: source
          workspace: source
    - name: k5-custom-task
      params:
        - name: solutionacronym
          value: $(params.solutionacronym)
      runAfter:
        - k5-build-publish-image-java
      taskRef:
        kind: Task
        name: k5-custom-task
      workspaces:
        - name: source
          workspace: source
    - name: k5-deploy
      params:
        - name: solutionacronym
          value: $(params.solutionacronym)
        - name: k5project
          value: $(params.k5project)
      runAfter:
        - k5-build-publish-chart-java
      taskRef:
        kind: Task
        name: k5-deploy
      workspaces:
        - name: source
          workspace: source
  workspaces:
    - name: source
    - name: basic-auth

Create a pipeline based on a Custom Pipeline Type

In the CI/CD tab you can now easily create a pipeline for your service (as usual) based on one of the available pipeline types.

Note:

IBM Industry Solutions Workbench will not validate Custom Pipelines/Tasks, it's the user's responsibility to take care of it.