Installation process

This will guide you through the installation process of IBM Industry Solutions Workbench 4.1.

The IBM Industry Solutions Workbench installation is using the Operator Lifecycle Manager mechanism to install Operators on restricted networks (disconnected environments) provided by Red Hat, see also Red Hat documentation - Mirroring an Operator catalog.

After the installation finished successfully, you will have

a running instance of Solution Designer
a running instance of Solution Hub

Warning:

Please note that both components are not fully configured after the installation.

Roles in the installation process

Red Hat OpenShift cluster administrator

The cluster administrator is responsible for:

Creating projects (namespaces)
Pushing all Container Images to the Image Registry
Installing the ImageContentSourcePolicy
Installing the CatalogSource
Installing the IBM Industry Solutions Workbench Operator

Project administrator

The project administrator is responsible for:

Installing IBM Industry Solutions Workbench
Installing Envoys on prepared namespaces
Providing necessary configuration data

Namespaces

You will need to have different namespaces for different purposes as described below


Namespace	Description
k5-tools	The namespace that has the tool setup installed and basic configuration.
k5-projects	Openshift projects used as deployment targets. In Solution designer, they are referred to as deployment targets as they are only used to deploy and execute microservices. In Solution hub, they are referred to as k5-projects and in other cases it can be referred to as Envoy. You can have at least one or more deployment targets as per your preference.
imgreg-namespace	In case you are using the cluster internal image registry, you will need to have another namespace just to host the container images.

Before you begin

Warning:

Please make sure that all system requirements are met, especially the OpenShift setup including OpenShift Pipelines installation.

In order to install IBM Industry Solutions Workbench the following requirements should be met on the machine from where the installer is executed:

You are logged-in into the OpenShift cluster as a user with sufficient rights for the task at hand
```
oc login
```
You have created a config.json file for the login into the Image Registry in the installation folder, like:
```
{"auths":{"my.image.registry.io":{"username":"iamapikey","password":"pw","auth":"aWFtYXBpa2V5OnB3"}}}
```
Your current working directory is set to the directory of the unpacked installer package. The package contains all contents of the IBM Industry Solutions Workbench Operator index image.

Step 0: Choose an image registry

You need to choose an image registry to store the container images that IBM Industry Solutions Workbench are comprised of and needs to be able to load for its installation.

You can choose any OCI compliant container registry (Red Hat Quay, Harbor etc.) or you can choose to use the internal Red Hat OpenShift Container registry if that is available on your instance of Red Hat OpenShift. If you choose the internal registry, you might want to choose a namespace that is not the namespace you intend to install IBM Industry Solutions Workbench into. No matter what registry you choose make a note of the registry name (the hostname) including the port and any path following that. Wherever the placeholder <YOUR_PRIVATE_REGISTRY> in this document is used specify the full registry name, i.e. if using the internal registry.

image-registry.openshift-image-registry.svc:5000/isw-images # do not use a protocol like docker:// or https://

Step 1: Push images to private registry

Warning:

Introduction

The oc adm catalog mirror command will push all required container images into your private image registry and create all needed kubernetes resources that are needed to configure the image mirroring and to add the IBM Industry Solutions Workbench Operator into the Operator Hub in your cluster.

Description

Executing the oc adm catalog mirror command pushes all required container images into the specified image registry. You can either use your own container image registry with its credentials or you can decide to use the OpenShift cluster internal image registry and in this case you might want to have a separate namespace just for hosting the container images that make up IBM Industry Solutions Workbench. Please update the value of <my.image.registry.io/my_namespace> to your registry host and namespace. In case you are using the internal cluster image registry update the value of <my.image.registry.io/my_namespace> to point to that registry and the namespace you have chosen, i.e. image-registry.openshift-image-registry.svc.cluster.local:5000/imgreg-namespace (if you want to use the internal service url of the openshift image registry).

oc adm catalog mirror file://local/index/isw_release/isw-operator-catalog@sha256:70c8f879bb0b861329b92286e6299b33281aafffe573386236b629d3c1c6bc9e my.image.registry.io/my_namespace -a ./config.json

Warning:

Please ensure that you are using the latest version that is available in Passport Advantage Online

Parameters

The oc adm catalog mirror command script has the following parameters:

oc adm catalog mirror SRC DEST -a ./config.json


Variable	Description	Example	Default
`SRC`	Source files	-	-
`DEST`	Target or destination image registry	-	-
`-a, --registry-config`	Path to your registry credentials (Optional)	-	-
`--manifests-only`	Calculate the manifests required for mirroring, but do not actually mirror image content (Optional)	-	-

Step 2: Create and Apply Manifest files

Introduction

The mirror command needs to be rerun using the --manifests-only flag to create proper CatalogSource and ImageContentSourcePolicy files in the installation folder.

Description

Executing the oc adm catalog mirror using the --manifests-only flag to create proper ImageContentSourcePolicy file in the installation folder. Please update the value of <my.image.registry.io/my_namespace> to your registry host and namespace. In case you are using the internal cluster image registry update the value of <my.image.registry.io/my_namespace> to point to that registry and the namespace you have chosen, i.e. image-registry.openshift-image-registry.svc.cluster.local:5000/imgreg-namespace (if you want to use the internal service url of the openshift image registry).

oc adm catalog mirror my.image.registry.io/imgreg-namespace/local-index-isw_release-isw-operator-catalog@sha256:70c8f879bb0b861329b92286e6299b33281aafffe573386236b629d3c1c6bc9e my.image.registry.io/my_namespace -a ./config.json --manifests-only

Apply created Manifest files to cluster

Warning:

If you are working with a cluster that doesn't have the machine config operator as it is the case e.g. when using IBM ROKS please directly proceed to the manual Step 3 after generating the manifest file.

Go into the latest created folder, like manifests-local-index-isw_release-isw-operator-catalog-1666465423
- You should find a imageContentSourcePolicy.yaml file
Check that this imageContentSourcePolicy.yaml file contains a valid metadata.name: This name must consist of lowercase alphanumeric characters, - or ., and must begin and end with an alphanumeric character (for example, local-index-xxx-xxx-xxx-operator-catalog, the regex used for validation is [a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*). If necessary, remove the invalid characters such as / or _ and any non-alphanumeric characters at the beginning or end.
Add your image pull secret as additional entry to the following existing cluster pull-secret. The easiest way to do this is via web console. Do not delete or remove something!
- Search for the secret pull-secret in the namespace openshift-config in the web console
- Open the pull-secret
- Edit the secret and add a new entry using Add credentials
- Add your Registry server address, Username, Password and an Email
- Save the secret
  - The newly added credentials then should be added to the file /var/lib/kubelet/config.json in your worker nodes. To validate that you can connect to your nodes and perform following commands:

chroot /host
sudo cat /var/lib/kubelet/config.json

Create an image pull secret in the openshift-marketplace and your installation namespace with Secret name ibm-entitlement-key (default name of the expected image pull secret) and the following values:
- Registry server address, Username, Password
Apply the generated ImageContentSourcePolicy to the cluster

oc apply -f imageContentSourcePolicy.yaml

Check that the imageContentSourcePolicy.yaml file looks like the following (<YOUR_PRIVATE_REGISTRY> is a placeholder for your registry here):

apiVersion: operator.openshift.io/v1alpha1
kind: ImageContentSourcePolicy
metadata:
  labels:
    operators.openshift.org/catalog: 'true'
  name: isw-operator-catalog
spec:
  repositoryDigestMirrors:
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-build-low-code-gen-ts
      source: de.icr.io/isw_release/build-low-code-gen-ts
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-component-repository-controller
      source: de.icr.io/isw_release/k5-component-repository-controller
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-prepare-denormalize-domain-model
      source: de.icr.io/isw_release/prepare-denormalize-domain-model
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-secret-operator
      source: de.icr.io/isw_release/k5-secret-operator
    - mirrors:
        - >-
          <YOUR_PRIVATE_REGISTRY>/cp_solutions-local-index-isw_release-isw-operator-catalog
      source: <YOUR_PRIVATE_REGISTRY>/local-index-isw_release-isw-operator-catalog
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-isw-operator-controller
      source: de.icr.io/isw_release/isw-operator-controller
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-backend
      source: de.icr.io/isw_release/backend
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-plantuml-server
      source: de.icr.io/isw_release/k5-plantuml-server
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-asset-manager
      source: de.icr.io/isw_release/k5-asset-manager
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-step-handle-version
      source: de.icr.io/isw_release/step-handle-version
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-solution-ubi8-openjdk-11
      source: de.icr.io/isw_release/solution-ubi8-openjdk-11
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-solution-ubi8-openjdk-17
      source: de.icr.io/isw_release/solution-ubi8-openjdk-17
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-solution-ubi8-openjdk-17-ppc64le
      source: de.icr.io/isw_release/solution-ubi8-openjdk-17-ppc64le
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-hub-backend
      source: de.icr.io/isw_release/hub-backend
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-code-generation-provider
      source: de.icr.io/isw_release/code-generation-provider
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-mvn-dependencies
      source: de.icr.io/isw_release/k5-mvn-dependencies
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-cli-provider
      source: de.icr.io/isw_release/cli-provider
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-project-operator
      source: de.icr.io/isw_release/k5-project-operator
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-isw-documentation
      source: de.icr.io/isw_release/isw-documentation
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-pipeline-manager
      source: de.icr.io/isw_release/k5-pipeline-manager
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-pipeline-manager-migration
      source: de.icr.io/isw_release/k5-pipeline-manager-migration
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-configuration-management
      source: de.icr.io/isw_release/configuration-management
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-build-low-code-gen-java
      source: de.icr.io/isw_release/build-low-code-gen-java
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-build-bpm-toolkit
      source: de.icr.io/isw_release/build-bpm-toolkit
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-step-build-code
      source: de.icr.io/isw_release/step-build-code
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-rollout-config
      source: de.icr.io/isw_release/k5-rollout-config
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-query
      source: de.icr.io/isw_release/k5-query
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-step-unit-test
      source: de.icr.io/isw_release/step-unit-test
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-frontend
      source: de.icr.io/isw_release/frontend
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-step-delete-solution
      source: de.icr.io/isw_release/step-delete-solution
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-application-manager
      source: de.icr.io/isw_release/k5-application-manager
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-audit-common-service
      source: de.icr.io/isw_release/k5-audit-common-service
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-iam-operator
      source: de.icr.io/isw_release/k5-iam-operator
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-dashboard
      source: de.icr.io/isw_release/dashboard
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-step-pack-solution-docker
      source: de.icr.io/isw_release/step-pack-solution-docker
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-domain-server
      source: de.icr.io/isw_release/domain-server
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-git-integration-controller
      source: de.icr.io/isw_release/git-integration-controller
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-prepare-validate-design-model
      source: de.icr.io/isw_release/prepare-validate-design-model
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-isw-operator-bundle
      source: de.icr.io/isw_release/isw-operator-bundle
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-service-project-manager
      source: de.icr.io/isw_release/k5-service-project-manager
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-mvn-dependencies-pipeline
      source: de.icr.io/isw_release/k5-mvn-dependencies-pipeline
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-secret-manager
      source: de.icr.io/isw_release/k5-secret-manager
    - mirrors:
        - >-
          <YOUR_PRIVATE_REGISTRY>/isw_release-k5-service-project-manager-templates
      source: de.icr.io/isw_release/k5-service-project-manager-templates
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-k5-topic-management
      source: de.icr.io/isw_release/k5-topic-management
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-hub-frontend
      source: de.icr.io/isw_release/hub-frontend
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-step-pack-helm-chart
      source: de.icr.io/isw_release/step-pack-helm-chart
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-solution-ubi8-node
      source: de.icr.io/isw_release/solution-ubi8-node
    - mirrors:
        - <YOUR_PRIVATE_REGISTRY>/isw_release-step-deploy-solution
      source: de.icr.io/isw_release/step-deploy-solution
    - mirrors:
        - de.icr.io/cp_solutions/isw_release-step-git-clone
      source: de.icr.io/isw_release/step-git-clone
    - mirrors:
        - de.icr.io/cp_solutions/isw_release-design-model-validation
      source: de.icr.io/isw_release/design-model-validation

Warning:

Configuring the image mirror using the ImageContentSourcePolicy does require the OpenShift Machine Operator which is available on OpenShift by default. But in case in your Cluster installation the Operator is not available or supported, it's necessary to configure the image mirror manually. Please follow the steps described in Step 3: Optional - Manual Configuration of Image Registry Mirror.

Apply the CatalogSource for the IBM Industry Solutions Workbench Operator with the following command to the cluster (<YOUR_PRIVATE_REGISTRY> needs to be replaced with your registry):

cat <<EOF | oc apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: isw-operator-catalog
  namespace: openshift-marketplace
spec:
  displayName: IBM Industry Solutions Workbench Catalog
  image: <YOUR_PRIVATE_REGISTRY>/local-index-isw_release-isw-operator-catalog@sha256:70c8f879bb0b861329b92286e6299b33281aafffe573386236b629d3c1c6bc9e
  publisher: IBM
  sourceType: grpc
  updateStrategy:
    registryPoll:
      interval: 30m
  secrets:
    - ibm-entitlement-key
EOF

Step 3: Optional - Manual Configuration of Image Registry Mirror

This step is only necessary if the ImageContentSourcePolicy is not supported on your cluster.

Copy the content of following file and replace all <YOUR_PRIVATE_REGISTRY> entries with your private registry and save the file


[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/backend"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-backend"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/build-bpm-toolkit"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-build-bpm-toolkit"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/build-low-code-gen-java"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-build-low-code-gen-java"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/build-low-code-gen-ts"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-build-low-code-gen-ts"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/cli-provider"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-cli-provider"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/code-generation-provider"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-code-generation-provider"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/configuration-management"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-configuration-management"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/dashboard"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-dashboard"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/domain-server"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-domain-server"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/frontend"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-frontend"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/git-integration-controller"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-git-integration-controller"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/hub-backend"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-hub-backend"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/hub-frontend"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-hub-frontend"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/isw-operator-bundle"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-isw-operator-bundle"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/isw-operator-controller"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-isw-operator-controller"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-application-manager"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-application-manager"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-asset-manager"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-asset-manager"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-audit-common-service"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-audit-common-service"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-component-repository-controller"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-component-repository-controller"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-secret-operator"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-secret-operator"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-iam-operator"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-iam-operator"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-mvn-dependencies"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-mvn-dependencies"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-mvn-dependencies-pipeline"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-mvn-dependencies-pipeline"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/isw-documentation"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-isw-documentation"
    
[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-pipeline-manager-migration"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-pipeline-manager-migration"
    
[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-pipeline-manager"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-pipeline-manager"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-plantuml-server"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-plantuml-server"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-project-operator"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-project-operator"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-query"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-query"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-rollout-config"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-rollout-config"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-secret-manager"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-secret-manager"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-service-project-manager"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-service-project-manager"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-service-project-manager-templates"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-service-project-manager-templates"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/k5-topic-management"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-k5-topic-management"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/prepare-denormalize-domain-model"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-prepare-denormalize-domain-model"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/prepare-validate-design-model"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-prepare-validate-design-model"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/solution-ubi8-node"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-solution-ubi8-node"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/solution-ubi8-openjdk-11"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-solution-ubi8-openjdk-11"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/solution-ubi8-openjdk-17"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-solution-ubi8-openjdk-17"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/solution-ubi8-openjdk-17-ppc64le"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-solution-ubi8-openjdk-17-ppc64le"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/step-build-code"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-step-build-code"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/step-delete-solution"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-step-delete-solution"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/step-deploy-solution"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-step-deploy-solution"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/step-handle-version"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-step-handle-version"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/step-pack-helm-chart"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-step-pack-helm-chart"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/step-pack-solution-docker"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-step-pack-solution-docker"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/step-unit-test"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-step-unit-test"
    
[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/step-git-clone"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-step-git-clone"

[[registry]]
  prefix = ""
  location = "de.icr.io/isw_release/design-model-validation"
  mirror-by-digest-only = true

  [[registry.mirror]]
    location = "<YOUR_PRIVATE_REGISTRY>/isw_release-design-model-validation"

Connect to your cluster via oc cli
List all Nodes

oc get nodes

Then perform the following commands for every node (to connect to every node and add needed mirrors to the registries.conf file)

oc debug node/<node-name>
chroot /host
vi /etc/containers/registries.conf

Add the content of the file from step 1 to /etc/containers/registries.conf (please be do not change the format of the file and do not remove/delete the original content)
Restart all nodes

Step 4: Install Operator via Catalog

Introduction

After pushing all needed images into your image registry, configuring the image mirroring and creating the CatalogSource it will be possible to install the IBM Industry Solutions Workbench Operator.

Description

Create a new namespace where you want to install IBM Industry Solutions Workbench
Search for 'IBM Industry Solutions Workbench' in the OperatorHub
Install the Operator into your chosen namespace (Previously named setup-namespace and from here after called "k5-tools")
Choose Update channel: stable-v1.1

Step 5: Create an ISW Resource to install the product

Introduction

After the successful installation of the Operator you can install the product by creating an ISW Resource.

Description

Open the installed Operator and in your namespace and go to ISW and create a new Resource, see also Configure ISW Custom Resource:

apiVersion: k5.ibm.com/v1beta1
kind: ISW
metadata:
  name: k5-tools
  namespace: k5-tools 
spec:
  designer:
    enabled: true
  domain: apps.openshift.my.cloud
  license:
    accept: true

Parameters


Variable	Description	Required	Default
designer.enabled	Enabled or disables the Solution Designer	no	true
domain	Domain is the ingress domain which is used to create routes. It can be retrieved by calling `oc get ingresses.config/cluster -o jsonpath={.spec.domain}`	yes	-
license.accept	A value that confirms that you accept the license	yes	-
values	A set of values to configure the installation	no	-

Step 6: Manual Installation steps

The following manual installation steps must be done before the installation is complete:

Add the already created k5-pipeline-sa Service Account the OpenShift Pipelines SCC privileged to give the pipelines enough permissions to build new container images

oc adm policy add-scc-to-user -n k5-tools -z k5-pipeline-sa privileged

Step 7: Validate the installation

To validate the results of the previous installation steps, you can check the status.conditions of your created ISW CustomResource. If there is an Available condition with status: true, the installation was successful:

status:
  conditions:
    - lastTransitionTime: '2024-05-21T10:00:00Z'
      message: Deployed version 4.1.1-1
      reason: Deployed
      status: 'True'
      type: Available
  endpoints:
    - name: solution-hub
      scope: External
      type: UI
      uri: 'https://k5-hub-release.apps.openshift.my.cloud/'
    - name: solution-designer
      scope: External
      type: UI
      uri: 'https://k5-designer-release.apps.openshift.my.cloud/'
  versions:
    - name: operator
      version: 1.3.1
    - name: ISW
      version: '4.1.1-1'

The status also provides you the links to Solution Hub and Solution Designer, just checkout the uris in status.endpoints.

Note:

Solution Hub or Solution Designer are not fully functional before you configure the product, see next steps

Step 8: Validate the base image ImageStreams

Please open the ImageStreams overview in your installation namespace (e.g. k5-tools) in the OpenShift Console
- Navigate to Builds → ImageStreams
Validate that the following ImageStreams are created and are not showing an error if you open them:
- k5-domain-server
- k5-solution-ubi8-node
- k5-solution-ubi8-openjdk
- k5-solution-ubi8-openjdk-ppc64le
If an ImageStream is showing an error try to delete the ImageStream, it will be re-created immediately by the IBM Industry Solutions Workbench Operator (this problem can typically occur if the image mirroring did not work when the ImageStreams were created the first time)

Warning:

The image mirroring for ImageStreams is not working properly for IBM Cloud OpenShift Clusters please check and follow the Manual setup of the base image ImageStreams to work around.

Next steps

With your successful installation of IBM Industry Solutions Workbench, you can go on to configure the product which is a mandatory step.

You must also review the configuration of Network Policies. Without disabling or configuring the EgressNetworkPolicy, IBM Industry Solutions Workbench can not work.

Troubleshooting

CrashLoopBackOff - missing CRD

If the operator is in CrashLoopBackOff, please check the logs of the pod. If the logs suggest that the EgressNetworkPolicy does not exist, please have a look at Network Policies.

k5 clone is not working on MacOs (base64 issue)

If the k5 clone command is failing on MacOS like this

k5 clone -s MYSOLUTION -p "my-git"
========= Cloning Solution to filesystem =================================================
--------- > Authenticating ---------------------------------------------------------------
--------- > Cloning Solution from Solution Git Repository --------------------------------
Cloning into '/dev/MYSOLUTION'...
fatal: unable to access 'https://my-git/MYSOLUTION.git/': error setting certificate verify locations:
CAfile: /Users/MyUser/.k5/k5-cli/default/designtime.ca.crt
CApath: /Users/MyUser/.k5/k5-cli/default

[ERROR] Cloning failed, removing directory: /dev/MYSOLUTION

Then please verify, if the file /Users/MyUser/.k5/k5-cli/default/designtime.ca.crt has proper base64 encoded values only. To do so, open the file and verify, that all lines between the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- do not exceed 64 characters. For manual and local fixing you can adjust the lines by breaking after 64 characters. And verify, that this is solving the experienced issue.

To fix it generally, the value of global.truststore.trustMap.identity must be adjusted in a similar way. Afterwards the setup of k5 must be reset by downloading the designtime.config.json and executing k5 setup --file ./cli-config.json.

How to analyze JWT in case of unauthorized responses

If a request is rejected and the response contains invalid_token, then it is helpful to decode the JWT itself by using for example jwt.io. So it is easier to see, if the JWT is decode-able and what kind of content it has, and to understand, what might cause the unexpected rejections.

Understanding the reason of The iss claim is not valid

If a request is rejected and the response contains invalid_token in combination of The iss claim is not valid, then the JWT was created by an OIDC provider using a different issuer URL, than the configured one.

It is helpful to decode the JWT itself by using for example jwt.io and check the value of iss. That must be the same as it is configured described by configuring OIDC provider for solutions and configuring deployment targets.