Installation Process OpenShift

This will guide you through the installation process for OpenShift.

The Cloud Solutions Workbench installation is using the Operator Lifecycle Manager mechanism to install Operators provided by Red Hat.

After the installation finished successfully, you will have

• a running instance of Solution Builder
• 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)
• Installing the CatalogSource
• Installing the Cloud Solutions Workbench Operator

Project administrator

The project administrator is responsible for:

• Installing Cloud 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 Builder, 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.

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 Cloud 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

Step 1: Create and Apply CatalogSource

Create the pull secrets

• Create an image pull secret in the openshift-marketplace and your installation namespace with Secret name knowis-csw-pull-secret (default name of the expected image pull secret) and the following values:
  • Registry server address, Username, Password
• Apply the CatalogSource for the Cloud 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: csw-operator-catalog
  namespace: openshift-marketplace
spec:
  displayName: CSW Cloud Solutions Workbench Catalog
  image: de.icr.io/csw_release/csw-operator-catalog:stable
  publisher: knowis
  sourceType: grpc
  updateStrategy:
    registryPoll:
      interval: 30m
  secrets:
    - knowis-csw-pull-secret
EOF

Step 2: Install Operator via Catalog

Introduction

After creating the CatalogSource it will be possible to install the Cloud Solutions Workbench Operator.

⚠warning

If you did not install Tekton before, you need to add this configuration [Build with container based technology(../../../build-run/byo-pipeline/byo-pipeline.md)

Description

• Create a new namespace where you want to install Cloud Solutions Workbench
• Search for ' Cloud 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 3: Create an CSW Resource to install the product

Introduction

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

Description

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

apiVersion: k5.ibm.com/v1beta1
kind: CSW
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 Builder	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 3: 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 4: Validate the installation

To validate the results of the previous installation steps, you can check the status.conditions of your created CSW 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 1.0.0
      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.0.0
    - name: CSW
      version: '1.0.0'

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

ℹ️note

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

Step 5: 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 Cloud 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 Cloud 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, Cloud 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.