Installation Process
This guide walks you through installing IBM DevOps Solution Workbench .
IBM DevOps Solution Workbench is installed via a Helm chart. When installation completes successfully, you will have a running instance of Solution Designer.
Roles in the installation process
Cluster administrator
The cluster administrator is responsible for:
- Creating projects (namespaces)
- Creating image pull secrets
- Deploying the Helm chart (including Custom Resource Definitions, Roles, RoleBindings, and ServiceAccounts)
Project administrator
The project administrator is responsible for:
- Installing Envoys in prepared namespaces
- Providing required configuration data
Namespaces
You need separate namespaces for different purposes:
| Namespace | Description |
|---|---|
| devops-solution-workbench | The Installation namespace. Holds the tool setup and base configuration. |
| k5-projects | OpenShift projects / Kubernetes namespaces used as deployment targets. In Solution Designer they are called deployment targets (used to deploy and run microservices). On the Environment page they appear as k5-projects; elsewhere they may be referred to as Envoys. You can define one or more deployment targets. |
Before you begin
Ensure the following on the machine where you run the installer:
-
Cluster access — You are logged in to the OpenShift or Kubernetes cluster with sufficient rights. For example:
oc login -
Fetch the Helm chart — Add the repo and pull the chart:
helm repo add ibm-helm https://raw.githubusercontent.com/IBM/charts/master/repo/ibm-helm --force-update
helm pull --untar ibm-helm/ibm-devops-solution-workbench --version 5.1.1
Installation
Follow the installation instructions in the README.md of the Helm chart.
Configuration
The following table explains the most important available Helm parameters that can be used for installation:
| Parameter | Description | Required | Default |
|---|---|---|---|
license | Confirmation that the EULA has been accepted. For example true | yes | - |
global.domain | Domain is the ingress domain which is used to create routes. | yes | - |
global.rationalLicenseKeyServer | Where floating licenses are hosted to entitle use of the product. For example @ip-address | yes | - |
global.k5.identity.url | Keycloak URL (including /auth path if needed) | yes | - |
global.k5.identity.realm | Keycloak Realm that will be created during installation | yes | - |
global.k5.identity.username | Keycloak Admin username | yes | - |
global.k5.identity.password | Keycloak Admin password | yes | - |
global.k5.autoscaling.enabled | Enable/disable Horizontal Pod Autoscaling (if disabled 1 pod per service is created) | true | |
global.k5.network.routing.routes.enabled | Enable/disable creation of Routes | true | |
global.k5.openshiftConsole | Url of your Openshift Console, will be used for generating links to the OpenShift Console (e.g. tekton pipelineruns) | - | |
global.k5.runtime.enabled | Enable/disable default runtime components | true | |
k5-pipeline-manager.tekton.initialize | Enable/disable creation of tekton pipeline resources (if set to true OpenShift Pipelines needs to be installed before) | true | |
database.enabled | Enable/disable deployment and usage of included product database (if set to false a own mongoDB instance must be provided) | true | |
rbac.create | Enable/disable creation of needed ServiceAccounts, RoleBindings and Roles | true | |
runtime.aggregateRoles.create | Enable/disable creation of aggregation roles (needed for runtime) | true | |
runtime.crds.create | Enable/disable creation of CustomResourceDefinitions (needed for runtime) | true | |
runtime.scc.create | Enable/disable creation of Security Context Constraints (needed for runtime) | true | |
networkPolicy.create | Enable/disable default Ingress Network Policy | false | |
truststore.create | Enable/disable creation of Default Truststore | true |
Product Database
The IBM DevOps Solution Workbench Helm chart creates and configures its own database by default.
If the built-in product database is enabled (see database.enabled is not set to false), the chart deploys an implementation of PostgreSQL
(including DocumentDB extension) and FerretDB together in a single StatefulSet named k5-database-postgresql.
The database binding secret k5-designer-mongodb (used by services to connect to the database), the required Services,
ServiceAccount, Role and RoleBindings are created automatically. No additional configuration is required by default.
The following parameters can be used for configuration:
| Parameter | Description | Default |
|---|---|---|
database.enabled | Enable/disable built-in product database | true |
k5-database.persistence.size | Size of the PersistentVolumeClaim | 20Gi |
Use MongoDB database
To use an existing MongoDB (version 6) as the designer database — whether it runs inside the cluster or externally (e.g. as a SaaS offering) — configure the following before running the Helm install command:
#Set MONGODB_CONNECTION_STRING accordingly
#if you are using an own or external mongoDB
#E.g.: "mongodb://mongoUser:password@mongodb.namespace.svc.cluster.local:27017/admin"
MONGODB_CONNECTION_STRING=
NAMESPACE=devops-solution-workbench
# Create database binding secret
if [ -n "${MONGODB_CONNECTION_STRING}" ]; then
if ! oc get secret k5-designer-mongodb --namespace ${NAMESPACE} > /dev/null 2>&1; then
oc create secret generic k5-designer-mongodb --namespace ${NAMESPACE} --from-literal=connectionString="${MONGODB_CONNECTION_STRING}" 1> /dev/null || { echo "Failed to create MongoDB secret"; return 1; }
fi
# Add the helm parameter to disable the built-in product database to your helm install command
HELM_OPTIONS="${HELM_OPTIONS} --set database.enabled=false"
fi
Routes Configuration
On OpenShift, the chart creates the following routes. They use the same host derived from global.domain (e.g. k5-designer.<cluster-domain>) except where a route has its own host.
In case the Routes need to be created manually the creation can be disabled via the helm chart setting: global.k5.network.routing.routes.enabled=false
The following table shows the required Routes:
| Route Name | Path | Target Service | Rewrite target | Target port | TLS policy | TLS termination |
|---|---|---|---|---|---|---|
k5-designer-frontend-route | / | k5-designer-frontend-service | — | https | Redirect | reencrypt |
k5-designer-backend-route | /backend | k5-designer-backend-service | / | https | Redirect | reencrypt |
k5-diagram-modeller-route | /diagram | k5-diagram-modeller-service | / | https | Redirect | reencrypt |
k5-code-generation-provider-route | /codegen | k5-code-generation-provider-service | / | https | Redirect | reencrypt |
k5-git-integration-controller-route | /gic | k5-git-integration-controller-service | / | https | Redirect | reencrypt |
k5-configuration-management | /cfg | k5-configuration-management | — | https | Redirect | reencrypt |
k5-hub-backend-route | /hub | k5-hub-backend-service | / | https | Redirect | reencrypt |
k5-shortlink-route | /shortlink | k5-shortlink-service | / | https | Redirect | reencrypt |
k5-pipeline-triggerwebhook | — (own host) | el-k5-git-trigger | — | http-listener | — | edge |
Validate the installation
To verify the installation use the following commands to check if the helm deployment was successful and all pods are running:
helm list -n $NAMESPACE
oc get pod -n $NAMESPACE
Next steps
After the installation was successful and all components are up and running, the Post installation tasks have to be checked before the product is ready to use.
Troubleshooting
Included Database fails with initdb: error
If pod k5-database-postgresql pod si not able to start and fails with following error:
upgrade initdb: error: directory "/var/lib/postgresql/data" exists but is not empty
This can be caused by some StorageClasses.
Please check if there is an empty lost+found directory in the mentioned folder and try to delete the folder.
Then the pod should be able to start and perform the initdb process successfully.
k5 clone fails on macOS (base64 issue)
If k5 clone fails on macOS with an error like:
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
Local fix: Check that /Users/MyUser/.k5/k5-cli/default/designtime.ca.crt contains only valid base64. Open the file and ensure every line between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- is at most 64 characters. If needed, break long lines at 64 characters and confirm the issue is resolved.
Persistent fix: Adjust the value of global.truststore.trustMap.identity in the same way (64-character lines). Then reset the k5 setup by downloading designtime.config.json and running:
k5 setup --file ./cli-config.json
Analyzing JWT for unauthorized responses
If a request is rejected with invalid_token, decode the JWT (for example at jwt.io) to inspect its contents and identify why it was rejected.
The iss claim is not valid
If the response includes invalid_token and The iss claim is not valid, the JWT was issued by an OIDC provider whose issuer URL does not match the configured one.
Decode the JWT at jwt.io and check the iss value. It must match the issuer URL configured in Configuring the OIDC provider for solutions and Configuring deployment targets.