Deployment Targets

Create Deployment Targets

In order to build and deploy projects developed with IBM Industry Solutions Workbench you need to have at least one OpenShift project used as deployment target for your projects. These OpenShift projects used as deployment targets are called k5-projects in IBM Industry Solutions Workbench.

Inside Solution Designer these k5-projects are referred to as deployment targets while in Solution Hub they are referred to as k5-projects. Reason is, that from Solution Designer perspective they are only targets for deploying microservices but from Solution Hub, which is the operations tool of IBM Industry Solutions Workbench, there is more to do, e.g. configurations, bindings, etc.

This guide explains how to create and configure such a project making use of the k5-project custom resource and the operator that was installed in a previous step.

💡tip

You can create as many of those k5-projects as you need to compartmentalize and stage a project or a set of projects.

After you completed this step you will have an OpenShift project that can be set as deployment target from the Solution Designer of IBM Industry Solutions Workbench.

Prerequisites

Please ensure, that the basic installation and configuration of IBM Industry Solutions Workbench on the cluster was successfully performed. At least the component Solution Hub is needed.

Provide default configurations for k5-projects

This task can be skipped, if the default configuration values have already been provided.

In order to make use of default configuration values within k5-project, the Configuration Management can be used. With the help of this component, you can specify environment specific values that apply for all k5-projects.

The Configuration Management API provides a REST service for reading and updating these configurations.

⚠warning

For using the Configuration Management a valid user is needed with the role of CM_ADMIN ( see User Role Model).

The configurations can be done with the provided Swagger UI or any other tool for calling APIs (like cURL, Postman). The Swagger UI for the Configuration Management API is accessible for example at https://configuration-management.apps.openshift-cluster.mydomain.cloud.

💡tip

You can find the URL for the Configuration Management API by inspecting the route named k5-configuration-management. It can be easily retrieved by executing oc get route k5-configuration-management -n <namespace>, whereby <namespace> points to the namespace, where IBM Industry Solutions Workbench is installed (e.g. k5-tools).

The configuration is mandatory for the k5-project-operator to run gracefully. Following values can be provided:

OIDC: Settings for the default OIDC compliant provider, which is used for authentication of running projects.
Mongo: Database settings for the deployed projects, which are using this database as persistent storage for their data
Kafka: Settings for accessing the Kafka messaging system (optional)

A detailed and more in-depth description can be found at Run Time Configuration.

Step 1: Create an OpenShift project

On the command line, login into the cluster and issue the command

oc new-project myprojectname

whereby myprojectname points to the name of the k5-project that should be created.

ℹ️note

This step can also be done in the OpenShift Web Console.

Step 2: Assign permissions

The second step is to grant admin permissions to the service-accounts, that are driving the k5-project-operator (k5-operator-sa) and pipelines (k5-pipeline-sa). Therefore, please select the k5-project created above (myprojectname).

oc project myprojectname
oc adm policy add-role-to-user admin system:serviceaccount:k5-tools:k5-operator-sa
oc adm policy add-role-to-user admin system:serviceaccount:k5-tools:k5-pipeline-sa

Please replace k5-tools with the name of the project, where IBM Industry Solutions Workbench is installed.

ℹ️note

This step can also be done in the OpenShift Web Console. To do this, create a new role binding that grants the admin role to the subject of type serviceaccount named k5-operator-sa and k5-pipeline-sa in the namespace where IBM Industry Solutions Workbench were installed.

Optionally

Grant admin permissions for the k5project to the openshift-gitops service account if you are using OpenShift GitOps Operator.

oc project myprojectname
oc adm policy add-role-to-user admin system:serviceaccount:openshift-gitops:openshift-gitops-argocd-application-controller

Step 3: Enable Strict mTLS policy for Istio namespaces

oc apply -f - <<EOF
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
  name: "default"
  namespace: istio-system
spec:
  mtls:
    mode: STRICT
EOF

Step 4: Create an instance of the custom resource k5-project

After setting up the OpenShift project and granting permissions, you can now create the custom resource k5-project. A k5-project is a custom resource definition in OpenShift, that can be treated like other Kubernetes resources.

Please log in into the OpenShift Web Console and open Custom Resource Definitions in the Administration section. Open the k5-project and select the Instances tab. Then click on Create k5-project.

💡tip

If the page should not be available, you can compose the URL for the browser at your own with the following scheme: https://console-openshift-console.openshift-cluster.mydomain.cloud/k8s/ns/myprojectname/k5.project.operator~v1~k5project , whereby you should adjust the hostname ( openshift-cluster.mydomain.cloud ) and the part with the projectname ( myprojectname ). View sidebar right above the editor will show a sidebar with detailed documentation and examples. Descriptions for the settings of a k5-project resource can be found below.

After creating the resource, the k5-project-operator will take over control and set up the OpenShift project automatically, so that all requirements are met to build, deploy and run projects.

Example configuration

apiVersion: k5.project.operator/v1
kind: k5project
metadata:
  name: dev-stage
  namespace: dev-stage
spec:
  configuration:
    configurationManagement:
      autoConfiguration:
        enabled: true
    iam:
      autoConfiguration:
        enabled: true
      host: 'https://keycloak.apps.ocp43.tec.uk.ibm.com'
      realm: ssob
    allowHttpOnly:
      enabled: false
    schemaRegistry:
      autoConfiguration:
        enabled: true
      realm: k5-tools
      securityEnabled: true
    truststore:
      autoConfiguration:
        enabled: true
      additionalCertificates:
        identity: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
  hostname: dev-stage.apps.ocp43.ibm.com
  stage: dev-stage
  tetheredTo: k5-tools
  type: DEV

Custom resource definition of a k5-project

Name	Description
`apiVersion`	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. (Example: `k5.project.operator/v1`)
`kind`	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated.
`metadata.name`	Name must be unique within a namespace. Required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition.
`metadata.namespace`	Namespace defines a logical boundary in which each element must be unique
`spec.configuration.configurationManagement.autoConfiguration.enabled`	Automatically setup default configuration values in the Configuration Management for deploying projects. Default value is true.
`spec.configuration.dashboard.configmap.extra`	A section containing settings for the behaviour of the dashboard, in the narrower sense all settings that do not fit to the logging or spring section.
`spec.configuration.dashboard.configmap.logging`	A section containing settings for the logging behaviour of the dashboard.
`spec.configuration.dashboard.configmap.spring`	A section containing spring boot settings for the behaviour of the dashboard, in the narrower sense the spring.boot framework.
`spec.configuration.dashboard.replicaSet`	The number of pods, that should be running the service. Default value is 2.
`spec.configuration.iam.additionalClientRedirectPatterns`	Additional redirect URIs, that should be considered, when the clients are created automatically.
`spec.configuration.iam.autoConfiguration.enabled`	Whether the autoconfiguration (creating clients in IAM and providing the secrets) will be done automatically. Autoconfiguration for the IAM will try to configure the necessary clients and provides the kubernetes secrets to the project containing the relevant security binding data.
`spec.configuration.iam.host`	The hostname including the protocol that is used as security provider (IAM, OIDC compliant).
`spec.configuration.iam.realm`	The realm that is used as security provider (IAM, OIDC compliant).
`spec.configuration.allowHttpOnly.enabled`	Allows you to disable SSL configuration for deployed projects for this namespace. Meaning for all communication HTTP will be used instead of HTTPS (Routes, Services). We strongly recommend to not disable SSL for production usage.
`spec.configuration.schemaRegistry.autoConfiguration.enabled`	Whether autoconfiguration for the schema registry configuration should be enabled or not.
`spec.configuration.schemaRegistry.securityEnabled`	Whether the configured schema registry requires authentication or not (see Schema Registry)
`spec.configuration.schemaRegistry.realm`	The realm that is used as security provider (IAM, OIDC compliant) for authentication with the configured schema registry (see Schema Registry
`spec.configuration.truststore.autoConfiguration.enabled`	Whether autoconfiguration should be enabled or not. Please be aware that enabling the trust store autoconfiguration may set the security of your system at risk. Please do not use this for production or high security scenarios. Autoconfiguration for the truststore will try to detect the necessary certificates and try to import them automatically to a trust store. By default, this feature will not be enabled.
`spec.configuration.truststore.additionalCertificates`	Specification for further certificates, that should be part of the default trust store. They will be appended regardless of the trust store autoconfiguration. This object contains all certificates in PEM ASCII format, whereby each certificate is specified with its own (json/yaml) key. The list should include all certificates in PEM ASCII format for the communication with the identity server, the MongoDB, the message hub service (Kafka) and any other systems that are called from project implementations. The line length of the certificates must comply with the standard for PEM messages, with each line containing exactly 64 printable characters except the last line and 64 or fewer printable characters in the last line.
`spec.configuration.kafka.enabled`	Whether Kafka will be available in the k5-project or not. Must not be changed after the creation of a k5-project.
`spec.configuration.istio.enabled`	Whether OpenShift Service Mesh will be available in the k5-project or not. Must not be changed after the creation of a k5-project.
`spec.configuration.istio.strictMtls`	Whether OpenShift Service Mesh will be available with Strict mTLS policy or not.
`spec.hostname`	The hostname under which the projects, that are running in the k5-project, will be accessible. Must not be changed after the creation of a k5-project.
`spec.stage`	A freely definable string, that refers to your logical staging name.
`spec.tetheredTo`	The project (namespace) where the base installation of IBM Industry Solutions Workbench is located. The k5-project will be tethered to this namespace. Tethering means that the accounts of the namespace given in `tetheredTo` fields also have access to the k5-project. This is for example required for metering. Must not be changed after the creation of a k5-project.
`spec.type`	The type of the k5-project. This refers to the type of usage this project is intended for. Possible values are "DEV" for development purposes, "TEST" for testing purposes, "STAGE" for staging purposes and "PROD" for production scenario. Please keep in mind, that this setting also has effects on the license type that is used in this project.

⚠warning

The certificates in the trust store should always contain the complete certificate chain. Certificates for services that are called with a cluster based URL (e.g. myservice.namespace.svc.cluster.local) may be omitted in trust stores, if the services are using certificates issued by the internal cluster certificate authority. The line length of the certificates must comply with the standard for PEM messages, with each line containing exactly 64 printable characters except the last line and 64 or fewer printable characters in the last line.

Step 5: Configuration management and users

After setting up the k5-project, you need to configure users, which will be able to access the projects.

Creating a user to login into the components ( see OpenShift User Configuration)
Proving access to OpenShift Pipelines to your users ( see IAM User Configuration)

For running the pipelines successfully for Domain Service Projects, you also need to set up a user that is used for testing purposes. Furthermore, you can adjust the default configuration for deployed projects and enable or disable certain features (see Project Configuration).

Validate the installation

After the operator is done with processing the information contained in the custom resource you should see a new deployment in the k5-project you created:

$ oc -n myprojectname get deployments
NAME                READY   UP-TO-DATE   AVAILABLE   AGE
k5-dashboard        2/2     2            2           25d

💡tip

You can find out the dashboard URL by viewing the route dashboard: oc -n myprojectname get route dashboard

Browse to the dashboard URL and check that

you are logged in or redirected to the OIDC provider
you can see k5-dashboard running when opening the Infrastructure page

Troubleshooting

Log inspection

In case you observe any issues during the installation, please check the logs of the k5-project-operator:

oc -n k5-tools get po | grep k5project
oc -n k5-tools logs k5projectoperator-845dbf97cf-8gvlr

Please replace k5-tools with the name of the project, where IBM Industry Solutions Workbench is installed.

Deleting a k5-project

In some situations you delete a k5-project, but the resources still remain. In this case, you may need to delete the resources manually. Those you can delete via command line (assuming that dev-stage is the k5-project, that should be deleted):

oc project dev-stage
oc delete k5dashboard k5-dashboard
oc delete k5realm --all
oc delete k5client --all
oc delete k5topic --all

💡tip

If the k5-project is still not deleted, edit YAML of the k5-project CRD instance and delete finalizers tag under metadata of the CRD.

Creating new deployment targets manually

This guide explains how to setup and configure a deployment target manually, not making use of the k5-project custom resource and the operator that is installed by IBM Industry Solutions Workbench.

Create needed Bindings/Secrets for Service Projects

The following examples show the bindings/secrets that are needed for starting the deployed service projects. Please adjust the namespace and the values accordingly.

IAM configuration

kind: Secret
apiVersion: v1
metadata:
  name: k5-default-iam-service-binding
  namespace: k5-deployment-target
data:
  oidc.issuer: https://keycloak-sso.apps.openshift.cloud/auth/realms/k5-deployment-target
  oidc.jwkUri: https://keycloak-sso.apps.openshift.cloud/auth/realms/k5-deployment-target/protocol/openid-connect/certs
type: Opaque

kind: Secret
apiVersion: v1
metadata:
  name: dashboard-oauth-client-secret
  namespace: k5-deployment-target
data:
  client.id: dashboard-client
  client.secret: PxvjHXXFwNQxG56taV14FbkZDUwrI
  issuer: https://keycloak-sso.apps.openshift.cloud/auth/realms/k5-deployment-target
  realm: k5-deployment-target
  token.endpoint: https://keycloak-sso.apps.openshift.cloud/auth/realms/k5-deployment-target/protocol/openid-connect/token
type: Opaque

MongoDB connection string

kind: Secret
apiVersion: v1
metadata:
  name: k5-default-document-storage-service-binding
  namespace: k5-deployment-target
data:
  binding: '{"uri":"mongodb://user:password@mongodb.mongodb.svc.cluster.local:27017/admin?ssl=true"}'
type: Opaque

Only needed if a events are used.

kind: Secret
apiVersion: v1
metadata:
  name: k5-default-message-service-binding
  namespace: k5-deployment-target
data:
  binding: '{"kafka_brokers_sasl":["kafka-kafka-bootstrap.foundation.svc:9093"],"user":"kafka-user","password":"password","saslJaasConfigLoginModuleQualifiedName":"org.apache.kafka.common.security.scram.ScramLoginModule","saslMechanism":"SCRAM-SHA-512"}'
type: Opaque

Url for Schema registry

Only needed if a schema registry is used.

kind: Secret
apiVersion: v1
metadata:
  name: k5-schema-registry-binding
data:
  securityEnabled: false
  url: https://schema-registry.apps.openshift.cloud
type: Opaque

Truststore

Here you can add all required certificates that the services should trust.

kind: Secret
apiVersion: v1
metadata:
  name: k5-truststore
  namespace: k5-deployment-target
data:
  mongo_cert: LS0t...UtLS0tLQo=
  kafka_cert: LS0t...US0tLQo=
  keycloak_cert: LS0t...LS0tLQo=
type: Opaque

Create needed ServiceAccount and RoleBinding for Service Projects

Please create the following service account and regarding role binding that will be used by the service projects and ensure that the service account has permission (image pull secret) for pulling the needed images.

kind: ServiceAccount
apiVersion: v1
metadata:
  name: k5-viewer-sa
  namespace: k5-deployment-target
imagePullSecrets:
  - name: k5-image-pull-secret

kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: k5-viewer-rb
  namespace: k5-deployment-target
subjects:
  - kind: ServiceAccount
    name: k5-viewer-sa
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: view

Configure Deployment Targets

Introduction

The run time configuration is all about the settings for deployed projects. If you want to configure the settings for Solution Designer or Solution Hub please see the product configuration.

The configuration of deployed projects is split up into three levels:

The environment level
The k5-project level
The deployment level

ℹ️note

The configurations mentioned on this page will only apply for single-service deployments. If you want to configure the behavior of application composition projects or their components, see application configuration or component configuration.

Environment level

This level is the top-most level as it sets up the default configuration for all k5-projects in your cluster. It is also the level to set up the initial values that are required to create k5-projects to which you will later deploy your projects.

Whenever you create a new k5-project, these settings will be applied until you create a k5-project configuration that will override these settings only for a certain k5-project.

⚠warning

These settings are also required for the k5-project-operator to run gracefully.

The environment configuration is the place to do the initial configuration of your run time. To be able to deploy projects you need to create at least one k5-project. This k5-project needs at least 2 service bindings to work and these two bindings can be created on the environment level.

Usually, you will only have to configure the environment settings once, but you could change them if needed. Any settings made at this level will only apply to new k5-projects.

The 2 service bindings can be created in 2 ways:

directly in Openshift
via Configuration Management REST API

Create service bindings directly in Openshift

The most important function of the Environment Configuration is to provide the cluster-wide default settings which are necessary to create k5-projects.

You can do the settings directly in OpenShift.

In the following configurations, the namespace k5-tools points to the namespace, where IBM Industry Solutions Workbench is installed.

Database

This configuration is required to define the connection to database that is used for the deployed services.

Configuration description in json format:

Form Field	Description
Name	Specify a unique name for this binding.
uri	The MongoDB connection string

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-default-document-storage-service-binding
  namespace: <k5-tools>
stringData:
  binding: '{"uri":"mongodb://mongoUser:mongoPassword@mongodb.namespace.svc.cluster.local:27017/admin?ssl=true"}'

Or:

kind: Secret
apiVersion: v1
metadata:
  name: k5-default-document-storage-service-binding
  namespace: <k5-tools>
stringData:
  binding: '{"uri":"mongodb://mongoUser:mongoPassword@portal-ssl1234.yp-89c7662a-e651.composedb.com:17647,portal-ssl5678.yp-89c7662a-e651.composedb.com:17647/compose?authSource=admin&ssl=true"}'

Messaging

This configuration is required to define the connection to kafka (Red Hat Integration - AMQ Streams) that is used for the deployed services.

Configuration description in json format:

Form Field	Description
kafka_brokers_sasl	The URL(s) of the bootstrap broker(s).
user	The provided Kafka user must have the permission to read and create topics.
password	Enter the password for the specified message hub user.
saslMechanism	Select the SASL mechanism to use with the message hub.
saslJaasConfigLoginModuleQualifiedName	The SASL JAAS Config Login Module used for the SASL mechanism.

Apply Configuration:

kind: Secret
apiVersion: v1
metadata:
  name: k5-default-message-service-binding
  namespace: <k5-tools>
stringData:
  binding: '{"kafka_brokers_sasl":["kafka-kafka-bootstrap.namespace.svc:9093"],"user":"kafka-user","password":"kafka-password","saslJaasConfigLoginModuleQualifiedName":"org.apache.kafka.common.security.scram.ScramLoginModule","saslMechanism":"SCRAM-SHA-512"}'

Create service bindings via Configuration Management REST API

Optionally you can do the settings via a REST API called Configuration Management API as well ( see API documentation). This API provides a Swagger UI for ease-of-use, but you can use the tool of your choice for calling APIs (e.g. cURL, Postman).

⚠warning

If you have created the service bindings already directly in Openshift, you can ignore this section.

💡tip

As long as not configured otherwise, the default URL where you can find the Configuration Management Swagger UI is built like this:

https://k5-configuration-<namespace>.apps.openshift-cluster.mydomain.cloud

The exact URL can be found within the route named k5-configuration-management. It can be easily retrieved by executing

oc get route k5-configuration-management -n <namespace>

whereby <namespace> points to the namespace, where IBM Industry Solutions Workbench is installed (e.g. k5-tools)..

Database

Form Field	Description
Name	Specify a unique name for this binding.
Database URI	The MongoDB connection string

Example:

mongodb://username:password@mongodb.domain.svc.cluster.local:27017/admin?ssl=false

Messaging

Form Field	Description
bindingName	Specify a unique name for this binding.
kafka_brokers_sasl	The URL(s) of the bootstrap broker(s).
user	The provided Kafka user must have the permission to read and create topics.
password	Enter the password for the specified message hub user.
saslMechanism	Select the SASL mechanism to use with the message hub.
saslJaasConfigLoginModuleQualifiedName	The SASL JAAS Config Login Module used for the SASL mechanism.

Example:

{
  "kafka_brokers_sasl": [
    "kafka-bootstrap-broker.your.domain:9093"
  ],
  "user": "username",
  "password": "password123",
  "saslJaasConfigLoginModuleQualifiedName": "org.apache.kafka.common.security.scram.ScramLoginModule",
  "saslMechanism": "SCRAM-SHA-512",
  "kafka_custom_config": [
    {
      "key": "some-custom-key",
      "value": "some-custom-value"
    }
  ]
}

k5-project level

The k5-project configuration will override the environment configuration and is intended to set specific configurations for a single k5-project. The settings you make on this level will be applied as default setting for all projects that will be deployed to this project.

The k5-project configuration provides configurations that apply to all new deployments within a k5-project. It is meant as a default configuration for deployments that can be overwritten by a deployment configuration.

New service bindings can only be created within the k5-project configuration.

ℹ️note

This configuration has to be done for each new k5-project.

You can find the k5-project configuration in Solution Hub after you selected a project.

💡tip

Alternatively, you can do the settings via a REST API called Configuration Management API ( see API documentation). This API provides a Swagger UI for ease-of-use but you can use the tool of your choice for calling APIs (e.g. cURL, Postman).

As long as not configured otherwise, the default URL where you can find the Configuration Management Swagger UI is built like this:

https://k5-configuration-<namespace>.apps.openshift-cluster.mydomain.cloud

The exact URL can be found within the route named k5-configuration-management. It can be easily retrieved by executing

oc get route k5-configuration-management -n <namespace>

whereby <namespace> points to the namespace, where IBM Industry Solutions Workbench is installed (e.g. k5-tools)..

See deployment configuration if you want to change the settings for a specific deployment.

The k5-project configuration tab provides the following categories of settings:

Authentication
Database
Features
Logging
Messaging
Operations
Testing

Authentication

Identity provider service binding:

Select an existing service binding from the list or create a new binding for the identity provider.

Form Field	Description
Name	Specify a unique name for this binding.
Client Id	The client ID of a registered OAuth client
Client Secret	The secret value which is bound to the referenced OAuth client.
Issuer	The issuer which has issued the JWT.
JWK URI	The URL of the JSON Web Key (JWK) set.
User Authorization URI	The URL of the OAuth authorization endpoint.
Token URI	The URL of the OAuth token endpoint.

Database

Database service binding:

Select an existing service binding from the list or create a new binding for the database connection.

Form Field	Description
Name	Specify a unique name for this binding.
Database URI	The MongoDB connection string

Example:

mongodb://username:password@mongodb.domain.svc.cluster.local:27017/admin?ssl=false

Features

Enable usage of DEV bindings:

Defines that deployments can use DEV bindings, that are defined in Solution Designer if no service binding was specified in the Configuration Management.

Enable CORS:

Defines if Cross-Origin Resource Sharing is enabled or not.

Publish internal helper API:

Defines if the internal helper API of a deployment is exposed within the Swagger UI.

Logging

Log level of the domain server:

Adjust the log level configuration used for the domain server. This can be one of the following values:

ALL
DEBUG
INFO
WARN
ERROR
FATAL
TRACE

Log level of deployments:

Set the default log level for the deployments.

You can set the log level for a specific path by creating a key/value pair for it. Enter the path to the files for which you want to set the log level into the left column and select the desired log level from the drop-down menu in the right column. Then click on the "+" sign to save this entry.

Messaging

Message hub binding:

Select an existing service binding from the list or create a new binding for the message hub.

Form Field	Description
bindingName	Specify a unique name for this binding.
kafka_brokers_sasl	The URL(s) of the bootstrap broker(s).
user	The provided Kafka user must have the permission to read and create topics.
password	Enter the password for the specified message hub user.
saslMechanism	Select the SASL mechanism to use with the message hub.
saslJaasConfigLoginModuleQualifiedName	The SASL JAAS Config Login Module used for the SASL mechanism. This field will be auto-filled depending on the selected SASL mechanism.

Enable audit trail:

Defines if deployments shall send events to a project-wide topic that records all access to any data.

Schema Registry

The Schema Registry provides a shared repository of schema definitions. Those schema definitions are used in events to describe their payload and therefore define a reliable contract between event producers and consumers.

In order to setup the Schema Registry integration, please add the secrets k5-schema-registry-binding and k5-schema-registry-oauth-secret to the deployment target using the below key-value pairs:

k5-schema-registry-binding

Key	Value
url	Schema Registry url
securityEnabled	Boolean indicating whether security is enabled for the Schema Registry. If yes, more data for authentication will have to be provided

k5-schema-registry-oauth-secret (only needed if k5-schema-registry-binding.securityEnabled is true)

Key	Value
baseurl	Base url of Schema Registry authentication server
realm	Schema Registry authentication realm
client.id	Schema Registry client id
client.secret	Schema Registry client secret

Operations

Automatic horizontal scaling:

Defines whether automatic horizontal scaling of the deployment is enabled or not.

Target CPU utilization:

Defines at with CPU usage percentage an additional pod will be started.

Min. number of pods:

Set the minimum number of running pods (1-100).

Max. number of pods:

Set the maximum number of running pods (1-100). Has to be greater or equal to Min. Number of Pods value.

Testing

Enable testing support:

Defines if an additional API for testing is available. If disabled, integration tests within the pipeline are not possible.

⚠warning

Activation of this feature is not recommended for PROD-deployments.

Username (default user for testing):

Default username used for executing the deployment tests (e.g. dev-envoy-test-user).

Password (default user for testing):

Password used for the specified default user for executing the deployment tests.

Deployment level

Lastly the deployment configuration overrides all other settings made on the higher levels. It is intended to override specific configurations made on the k5-project level. Some typical settings are the log level or setting up specific service bindings that will be applied to only this project when it gets deployed.

It is not necessary to set up a deployment configuration as long as you are fine with the k5-project configuration. You can also only override one or more single settings with a deployment configuration and let the rest be defined by the k5-project configuration.

It's possible to create a deployment-specific configuration to override the settings of the k5-project configuration. This deployment configuration will only apply to the selected project and only overrides the values that are explicitly set in the deployment configuration. So you have the chance to set your default configurations for all projects inside a k5-project and only override certain settings for a certain project.

Manage Solution Configurations

Similar to the k5-project configuration, you have two options to make the settings. The first option is to visit the Solution Hub and navigate to the k5-project that contains the project and then navigate to the project itself. There you find a tab Deployment configurations which shows all configurable settings and also the default values for this project.

💡tip

The list of configuration parameters is the same as for the k5-project configuration.

For each category listed there you have the option to edit the configuration or create new bindings. The column on the right always shows the current default setting for all projects in this k5-project. So you can easily decide whether to add specific settings or stick with the defaults.

The second option is via a REST API called Configuration Management API ( see API documentation). This API provides a Swagger UI for ease-of-use but you can use the tool of your choice for calling APIs (e.g. cURL, Postman).

💡tip

As long as not configured otherwise, the default URL where you can find the Configuration Management Swagger UI is built like this:

https://k5-configuration-<namespace>.apps.openshift-cluster.mydomain.cloud

The exact URL can be found within the route named k5-configuration-management. It can be easily retrieved by executing

oc get route k5-configuration-management -n <namespace>

whereby <namespace> points to the namespace, where IBM Industry Solutions Workbench is installed (e.g. k5-tools).

⚠warning

Any change to the configuration will only be applied to the project with a new deployment.

Configure OIDC

For authentication within solutions any arbitrary OIDC compliant Identity Provider can be configured and used. Please note that this only affects authentication within solutions, e.g. the verification of the sent JWT, and does not affect the Solution Designer or Solution Hub environment at all. If Keycloak is used as an identity provider all configuration can be setup automatically by enabling the autoconfiguration flag of the k5-project resource.

Gathering data and prerequisites of the Identity Provider

The following conditions must be met by your Identity Provider:

Supported authentication flows / grant types:
- Authorization Code (login to dashboard)
- Implicit (login via swagger-ui)
- Client Credentials (service execution by agents triggered by an event)
- Password (testing solutions in the pipeline)
The Identity Provider must be conformant to the OIDC protocol
The Identity Provider must provide its OIDC configuration via metadata at a URL, that is constructed by <ISSUER>.well-known/openid-configuration, whereby <ISSUER> is referring to the issuer, that is used in the resulting token
The issuer of the token must be the same regardless of the flow that was used to authenticate

ℹ️note
To achieve this in an Azure app registration, you have to update the manifest and set the property accessTokenAcceptedVersion to 2.
All authentication flows except Authorization Code must issue an id_token ::: Minimum required data:
client_id: the ID of an oauth-client
client_secret: a secret value, which is bound to the referenced oauth-client
issuer: The issuer which has issued the JWT
jwk uri: The URL of the Json Web Key Set
user authorization uri: The URL of the OAuth authorization endpoint
token uri: The URL of the OAuth token endpoint

Optional data - highly dependent on the Identity Provider:

audience: the audience that needs to be included within calls of the Client Credentials Flow
scope: the scope that needs to be included within calls of the Client Credentials Flow
name of the username attribute within the token - default preferred_username
name of the name attribute within the token - default name

Known restrictions:

A proper logout in the dashboard can only be performed, if the OIDC configuration metadata document provides a property named end_session_endpoint
Authentication calls are only sending scope=openid for the Implicit and Password flow. In case of Authorization Code flow all supported scopes will be sent
Currently, there is support only for one Identity Provider per k5-project, that is managed by the k5-project-operator.

Configuration settings

ℹ️note

Please do not forget to update the truststore to contain the complete certificate chain for a proper communication with the Identity Provider

Create secrets manually:

This step has to be repeated for every k5-project. Please ensure that your k5-project resource does not have the autoconfiguration flag for IAM enabled. If you do not want to configure the secrets manually, there is also the option to administer those secrets within the Configuration Management. Please note that those secrets are built out only during the creation of a k5-project from the default configuration values.

Create the following secrets within the namespace of the k5-project and provide the necessary information for each:

Secret Name	Usage	Supported Authentication Flows
dashboard-oauth-client-secret	used to provide the login information for the dashboard; also used in the swagger-ui.	Authorization Code, Implicit
debugserver-oauth-client-secret	used for debugging within the CLI	Password
event-manager-oauth-client-secret	used for service execution of agents, that were triggered by events	Client Credentials
solution-test-oauth-client-secret	used for executing tests within the pipeline	Password

The secret should always contain the following properties:

Key	Description	Example
issuer	The issuer of the token	microsoft login426abd8d-4518-4fd8-b768-107155ec5d15/v2.0>
client.id	The client id to use	8325d28e-840e-4420-928c-33382d4b92a9
client.secret	The client secret	aaf83822-6beb-4ea7-ab78-6af08e81ca8d
token.endpoint	The token url of the identity provider that is used to get tokens	microsoft login426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/token>
baseurl	The base url of the identity provider (only needed for legacy reasons; should be similar to the issuer)	microsoft login426abd8d-4518-4fd8-b768-107155ec5d15/>
realm	The realm that is used for authentication (only needed for legacy reasons)	mySecurityRealm

Example call for create a secret:

This sample call will create a secret named dashboard-oauth-client-secret and specifies all required values.

oc create secret generic dashboard-oauth-client-secret \
--from-literal=issuer='https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/v2.0'  \
--from-literal=client.id='8325d28e-840e-4420-928c-33382d4b92a9'  \
--from-literal=client.secret='aaf83822-6beb-4ea7-ab78-6af08e81ca8d'  \
--from-literal=token.endpoint='https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/token' \
--from-literal=baseurl='https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/'  \
--from-literal=realm='mySecurityRealm'

Configuration settings for the Identity Provider

List of redirect-URIs

The application (dashboard and swagger-ui) will send the following redirect URIs. Please ensure that your Identity Provider does explicitly accept these.

<HOSTNAME>/login/oauth2/code/dashboard
<HOSTNAME>/swagger-ui/oauth2-redirect.html

Special configuration possibilities

For the Client Credentials Flow working properly, different Identity Providers need different properties to set. In order to give full flexibility, there are some configuration properties that can be set additionally. They can be specified via a solution configuration within the Configuration Management (see Solution default configuration).

In order to specify the needed values, you can put the values inside the configmap property:

configmap
extraConfiguration: |
  # Optional additional configuration
  de.knowis.cp.ds.action.helper.overwriteParameter.scope: "api://8325d28e-840e-4420-928c-33382d4b92a9/.default"
  de.knowis.cp.ds.action.helper.overwriteParameter.audience:

You can specify any arbitrary key value pairs, that are sent to the Identity Provider by just using the pattern de.knowis.cp.ds.action.helper.overwriteParameter.KEY: VALUE. Declaring a key with no value, will actually result in an empty form parameter with this specific key.

Attribute names for name and username

Since the tokens may look very different, there is the possibility to configure the attribute names under which the token sends the desired information. Despite the default attributes like sub, issuer, exp, there needs to be information present about name and username of the user. The names of these attributes can be configured, if the default (name, preferred_username) is not sufficient.

The settings can be applied via configuration of the k5-project resource in the section of dashboard.

spec:
  configuration:
    dashboard:
      configmap:
        extra:
          de.knowis.cp.dashboard.security.claim.username: nickname
          de.knowis.cp.dashboard.security.claim.name: fullname

Reference calls

This section aim to outline the actual calls that are sent to the Identity Provider.

Password

curl -i -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -d "grant_type=password" \
   -d "client_id=8325d28e-840e-4420-928c-33382d4b92a9" \
   -d "scope=openid" \
   -d "username=User@mydomain.com" \
   -d "password=passw0rd" \
   -d "client_secret=aaf83822-6beb-4ea7-ab78-6af08e81ca8d" \
 'https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/token'

Client Credentials

curl -i -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -d "grant_type=client_credentials" \
   -d "client_id=8325d28e-840e-4420-928c-33382d4b92a9" \
   -d "client_secret=aaf83822-6beb-4ea7-ab78-6af08e81ca8d" \
 'https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/token'

Please note that the overrideParameter as described above will be appended to this call as specified with -d key=value

Calls for Authorization Code or Implicit cannot be done on the command line, since they are only working with enabled redirects in the browser.

Create Deployment Targets​

Prerequisites​

Provide default configurations for k5-projects​

Step 1: Create an OpenShift project​

Step 2: Assign permissions​

Optionally​

Step 3: Enable Strict mTLS policy for Istio namespaces​

Step 4: Create an instance of the custom resource k5-project​

Example configuration​

Custom resource definition of a k5-project​

Step 5: Configuration management and users​

Validate the installation​

Troubleshooting​

Log inspection​

Deleting a k5-project​

Creating new deployment targets manually​

Create needed Bindings/Secrets for Service Projects​

IAM configuration​

MongoDB connection string​

AMQ Streams/Kafka login configuration​

Url for Schema registry​

Truststore​

Create needed ServiceAccount and RoleBinding for Service Projects​

Configure Deployment Targets​

Introduction​

Environment level​

Create service bindings directly in Openshift​

Database​

Messaging​

Create service bindings via Configuration Management REST API​

Database​

Messaging​

k5-project level​

Authentication​

Database​

Features​

Logging​

Messaging​

Schema Registry​

Operations​

Testing​

Deployment level​

Manage Solution Configurations​

Configure OIDC​

Gathering data and prerequisites of the Identity Provider​

Configuration settings​

Configuration settings for the Identity Provider​

Special configuration possibilities​

Attribute names for name and username​

Reference calls​

Create Deployment Targets

Prerequisites

Provide default configurations for k5-projects

Step 1: Create an OpenShift project

Step 2: Assign permissions

Optionally

Step 3: Enable Strict mTLS policy for Istio namespaces

Step 4: Create an instance of the custom resource k5-project

Example configuration

Custom resource definition of a k5-project

Step 5: Configuration management and users

Validate the installation

Troubleshooting

Log inspection

Deleting a k5-project

Creating new deployment targets manually

Create needed Bindings/Secrets for Service Projects

IAM configuration

MongoDB connection string

AMQ Streams/Kafka login configuration

Url for Schema registry

Truststore

Create needed ServiceAccount and RoleBinding for Service Projects

Configure Deployment Targets

Introduction

Environment level

Create service bindings directly in Openshift

Database

Messaging

Create service bindings via Configuration Management REST API

Database

Messaging

k5-project level

Authentication

Database

Features

Logging

Messaging

Schema Registry

Operations

Testing

Deployment level

Manage Solution Configurations

Configure OIDC

Gathering data and prerequisites of the Identity Provider

Configuration settings

Configuration settings for the Identity Provider

Special configuration possibilities

Attribute names for name and username

Reference calls