Configuring IBM Industry Solutions Workbench

Introduction

After you completed the installation process you are ready to do the initial configuration of IBM Industry Solutions Workbench to get Solution Designer and Solution Hub up and running. Be aware, that even if all necessary pods are running without this configuration you are not able to work with neither one of the components.

All the configurations mentioned in this chapter are related to Solution Designer and Solution Hub. This chapter is not about the configurations related to deployed projects. You can find this information under Run Time Configuration.

The initial configuration of IBM Industry Solutions Workbench is done via Kubernetes Secrets.

For a new installation at least, the following configurations must be provided:

ArgoCD: Configures the properties to access ArgoCD service
IAM: Configures the properties to access the Identity and Access Management system ( IAM), respectively Keycloak
Master key: Configures the master key, needed to have encryption at rest for some sensitive user data, like Git tokens or API keys
MongoDB: Configures the connection to the Mongo database, which is used by the Solution Designer
Schema Registry: Configures the connection to Schema Registry
Truststore: Updates the truststore, which holds a bunch of certificates, that should be trusted within IBM Industry Solutions Workbench

The following configurations are optional:

Audit binding: Optional - Configure connection to the audit logging collector
Vault: Optional - Configures the properties to access a HashiCorp Vault

ArgoCD

These configurations are required to connect to the ArgoCD service.

Configuration description:


Key	Description
url	The url of the ArgoCD service
username	The username to login into the ArgoCD service
password	The password to login into the ArgoCD service
namespace	The namespace (or OpenShift project) of the ArgoCD installation

Warning:

Please use the public route URL as url or ensure that all certificates (whole chain) of the ArgoCD Service are included in the Truststore.

Warning:

In the following "k5-tools" is the name of the namespace where IBM Industry Solutions Workbench is installed.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-argocd-binding
  namespace: <k5-tools>
  labels:
    k5-configuration: 'true'
stringData:
  url: "https://openshift-gitops-server.apps.openshift-cluster.mydomain.cloud"
  username: "user"
  password: "pw123"
  namespace: "openshift-gitops"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

IAM

These configurations are required to connect to the IAM Provider.

IAM Configuration

Configuration description:


Parameter	Description
hostname	The hostname of the IAM provider
realm	The default realm name

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-iam-settings
  namespace: <k5-tools>
  labels:
    k5-configuration: 'true'
stringData:
  hostname: "https://auth.apps.openshift-cluster.mydomain.cloud"
  realm: "k5-tools"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

IAM Credentials

Configuration description:


Parameter	Description
adminUsername	The IAM admin’s username
adminPassword	The IAM admin’s password

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-iam-secret
  namespace: <k5-tools>
  labels:
    k5-configuration: 'true'
stringData:
  adminUsername: "keycloak"
  adminPassword: "pw456"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

Master Key

This configuration specifies the private AES key for encrypting API keys for associated Cloud Pack services and for encrypting Git user tokens.

Configuration description:


Parameter	Description
key	The AES private key. No empty values can be used here, as this would be a security risk. The data (especially user tokens) would not be encrypted and would therefore be stored in clear text in the database, which must not happen.

This information needs to be provided by the customer. There are no further restrictions on the key, but it is recommended to provide a master key that matches the common AES rules.

Warning:

Losing/changing the master key will cause data loss, because user tokens are encrypted with that and can't be decrypted without it! In this case all encrypted data is invalid, hence all users have to remove and renew the saved Git Tokens and API Keys.

In the initial state the value is empty, which is why the encryption is failing. Only due to that it is safe in respect of data loss in the initial state.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-encryption-master-key
  namespace: <k5-tools>
  labels:
    k5-configuration: 'true'
stringData:
  key: "yOuRkEy123!"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

MongoDB

This configuration is necessary to connect to the Mongo database.

Configuration description:


Parameter	Description
connectionString	The mongoDB connectionString for the Solution Designer.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-designer-mongodb
  namespace: <k5-tools>
  labels:
    k5-configuration: 'true'
stringData:
  connectionString: "mongodb://admin:pw678@mongodb.mongo.svc.cluster.local:27017/admin?ssl=true"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

Schema Registry

This configuration is necessary to connect to the Schema Registry.

Configuration description:


Parameter	Description
cleanUpTaskTime (optional)	The time when the clean up job should be run. Please use cron schedule expressions. (Default: `0 0 20 * * Saturday`)
cleanUpTaskTimeZone (optional)	The timezone you're in. Example: `Europe/Berlin` (Default timezone: `UTC`)
url	Url of the Schema Registry.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-schema-registry-binding
  namespace: <k5-tools>
  labels:
    k5-configuration: 'true'
stringData:
  url: "https://schema-registry.apps.openshift-cluster.mydomain.cloud"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

Truststore

Updates the truststore, which holds a bunch of certificates, that should be trusted within IBM Industry Solutions Workbench.

Configuration description:


Parameter	Description
arbitrary key	Trusted certificate

You can add as many certificates as you want with key names of your choice.

Note:

By default all Solution Designer and Hub services (pods) and with IBM Industry Solutions Workbench created services trust the default certificates that are provided by the Red Hat Universal Base Image (UBI) image and don't need to be included manually into the truststore. Open /etc/pki/tls/certs/ca-bundle.crt in any pod to check the trusted certificates.

Warning:

The line length of the certificates must comply with the PEM standard, with each line containing exactly 64 printable characters except the last line and 64 or fewer printable characters in the last line.

Apply Configuration:

It is easier to add certificates via base64-encoded strings. To do so, you need your certificate as pem file. Then execute the following command and copy the string output:

base64 --wrap=0 my-cert.pem
# copy the string output

kind: Secret
apiVersion: v1
metadata:
  name: k5-hub-truststore
  namespace: <k5-tools>
  labels:
    k5-configuration: 'true'
data:
  arbitraryKey: "the previously copied base64-encoded string"
  arbitraryKey2: "another copied base64-encoded string"

Adjust metadata.namespace and data and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

Audit Binding

This configuration is necessary to connect to your audit logging collector (e.g. Fluentd). By default, the audit logging is disabled since it is not meant to be used without a connection to an audit logging collector. If you do not wish Audit Logging, you can skip this configuration.

Configuration description:


Parameter	Description
auditEnabled	Enables or disables the Audit logging.
connectionString	The Fluentd connectionString for Audit logging.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-auditlog-settings
  namespace: <k5-tools>
  labels:
    k5-configuration: 'true'
stringData:
  auditEnabled: "boolean"
  connectionString: "string"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml

Vault

Configures properties to access a HashiCorp Vault. This configuration is not mandatory!

Configuration description:


Parameter	Description
url	The url of the HashiCorp Vault
role	The name of the role you configured in your vault. You can find information how to do that here.

Warning:

Losing/changing the vault configuration can cause errors and secrets need to be recreated.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-vault-binding
  namespace: <k5-tools>
  labels:
    k5-configuration: 'true'
stringData:
  url: "string"
  role: "string"

Adjust metadata.namespace and stringData and then create this secret via UI or save it as a file and apply it with the following command:

oc apply -f secret.yaml