Installation Process
This guide walks you through installing Cloud Solution Workbench .
Cloud 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)
Namespaces
The core installation uses one namespace for the workbench:
| Namespace | Description |
|---|---|
| cloud-solution-workbench | The Installation namespace. Holds the tool setup and base configuration. |
k5-project namespaces (deployment targets) are needed only for Managed Stacks. See Install runtime for Managed Stacks.
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 knowis-helm de.icr.io/k5_release --force-update
helm pull --untar knowis-helm/knowis-cloud-solution-workbench --version 26.05
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.
By default the chart is configured for Keycloak and a design-time workbench. Managed Stacks (runtime, pipelines, k5-projects) is off by default. To use Microsoft Entra ID instead of Keycloak, see Use Microsoft Entra ID as OIDC provider. To enable Managed Stacks, see Install runtime for Managed Stacks.
| 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.k5.identity.url | OIDC provider URL. For Keycloak, the Keycloak URL (including /auth path if needed). For Microsoft Entra ID, https://login.microsoftonline.com. | yes | - |
global.k5.identity.realm | For Keycloak, the realm that will be created during installation. For Microsoft Entra ID, the tenant ID (Directory ID). | yes | - |
global.k5.identity.username | Keycloak Admin username. Not required when Microsoft Entra ID is used. | yes (Keycloak) | - |
global.k5.identity.password | Keycloak Admin password. Not required when Microsoft Entra ID is used. | yes (Keycloak) | - |
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.featureFlags.designAssistantChatbotFeatureFlag | Enable/disable Design Assistant feature, if enabled the following configuration is needed, see AI providers | false | |
global.k5.featureFlags.modellingSupportMCPServerFlag | Enable/disable Modelling Support MCP server | true | |
global.k5.featureFlags.enableHeritageStacks | Enable/disable Managed Stacks (Deprecated). Off by default. Runtime Helm values, third-party tools, and k5-projects are documented in Install runtime for Managed Stacks | false | |
database.enabled | Enable/disable deployment and usage of included product database (if set to false a own mongoDB instance must be provided) | true | |
cache.enabled | Enable/disable deployment and usage of included Redis cache (if set to false an own Redis instance must be provided) | true | |
k5-cache.cache.ha.enabled | Enable/disable High Availability mode for the included Redis cache (if enabled a 6-node cluster with 3 master and 3 replica nodes is created, if disabled a single Redis instance is deployed) | false | |
rbac.create | Enable/disable creation of needed ServiceAccounts, RoleBindings and Roles | true | |
networkPolicy.create | Enable/disable default Ingress Network Policy | false | |
truststore.create | Enable/disable creation of Default Truststore | true | |
k5-design-assistant.llmMaxInputTokens | Maximum input tokens the Design Assistant uses per request (prompt, tools, and conversation history) before compacting the conversation. Caps usage below native 1M-token windows on cloud models, and defines the context window size for custom Azure deployment names or self-hosted models. | 250000 | |
k5-design-assistant.externalSystemsReadOnly | When false (default), the Design Assistant lists and can execute writing MCP tools as well as read-only ones. Each call still asks for consent. Set to true to execute only tools the server annotates as read-only (readOnlyHint set to true). | false |
Use Microsoft Entra ID as OIDC provider
The Helm chart defaults assume Keycloak: during install it creates the realm, OIDC clients, roles, and OAuth client secrets. Microsoft Entra ID does not support that automation. Register the workbench application in Entra ID first, then disable client and secret creation and point identity at Entra ID.
Set the following Helm parameters in addition to global.domain and the other required values. global.k5.identity.username and global.k5.identity.password are not required.
| Parameter | Description | Required for Entra ID | Default |
|---|---|---|---|
global.k5.identity.url | Microsoft Entra ID login endpoint. Use https://login.microsoftonline.com. | yes | - |
global.k5.identity.realm | Entra ID tenant ID (Directory ID) of the directory that hosts the app registration. | yes | - |
global.k5.identity.createClient | Must be false. The chart must not create Keycloak clients, realms, or roles. Create the app registration and roles in Entra ID instead. | yes | true |
global.k5.identity.createSecret | Must be false. The chart must not generate OAuth secrets with Keycloak-style issuer and token URLs. Provide the secrets in the installation namespace before you install. | yes | true |
global.k5.identity.useIdToken | Must be true. API calls then send the OIDC ID token as the Bearer token. Entra ID access tokens are not always JWT access tokens that the workbench APIs can validate. | yes | false |
k5-user-license-service.defaultIdentityProvider.enabled | Must be false. The license service then does not list users through the Keycloak admin API. Users are taken from the product database instead. | yes | true |
Because createSecret is false, create the OAuth client secrets in the installation namespace before you run Helm install. The default secret names are k5-designer-client-oauth-secret and k5-configuration-management-client-secret. The secrets must contain Entra ID issuer, authorization, token, logout, and JWKS URLs for your tenant, plus the application (client) ID from the app registration.
Example Helm parameters:
HELM_OPTIONS="${HELM_OPTIONS} \
--set global.k5.identity.url=https://login.microsoftonline.com \
--set global.k5.identity.realm=<entra-tenant-id> \
--set global.k5.identity.createClient=false \
--set global.k5.identity.createSecret=false \
--set global.k5.identity.useIdToken=true \
--set k5-user-license-service.defaultIdentityProvider.enabled=false"
Equivalent values file:
global:
k5:
identity:
url: https://login.microsoftonline.com
realm: <entra-tenant-id>
createClient: false
createSecret: false
useIdToken: true
k5-user-license-service:
defaultIdentityProvider:
enabled: false
Replace <entra-tenant-id> with the Directory (tenant) ID of your Entra ID tenant.
Assign the workbench roles (dc_developer or dc_admin) as app roles on the Entra ID app registration, and grant them to users. The install does not create realms, clients, or roles when Entra ID is used. See Configure users and permissions.
Redis Cache
The Cloud Solution Workbench Helm chart creates and configures its own Redis cache (k5-cache) by default.
If the built-in cache is enabled (see cache.enabled is not set to false), the chart deploys a Redis StatefulSet named k5-cache (or k5-cache-cluster when High Availability mode is enabled).
The Redis binding secret k5-redis-binding (used by services to connect to the cache) and 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 |
|---|---|---|
cache.enabled | Enable/disable built-in Redis cache | true |
k5-cache.cache.ha.enabled | Enable/disable High Availability mode (6-node cluster vs. single instance) | false |
Use external Redis
To use an existing Redis instance — whether it runs inside the cluster or externally — configure the following before running the Helm install command:
- Set
cache.enabled=falsein your Helm install command to skip deployment of the included k5-cache component. - Create the Redis binding secret as described in Redis.
Example Helm parameter:
HELM_OPTIONS="${HELM_OPTIONS} --set cache.enabled=false"
Product Database
The Cloud 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 7) 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=cloud-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 | optional |
|---|---|---|---|---|---|---|---|
k5-designer-frontend-route | / | k5-designer-frontend-service | — | https | Redirect | reencrypt | - |
k5-designer-backend-route | /backend | k5-designer-backend-service | / | https | Redirect | reencrypt | - |
k5-design-assistant-api-route | /designassistant | k5-design-assistant-service | / | https | Redirect | reencrypt | yes, only created if global.k5.featureFlags.designAssistantChatbotFeatureFlag is enabled |
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.