Create and Configure OpenShift Projects as Deployment Targets

Overview

In order to build and deploy solutions developed with IBM Financial Services Workbench you need to have at least one OpenShift project used as deployment target for your solutions.

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.

You can create as many of those projects as you need to compartmentalize and stage a solution or a set of solutions.

After you completed this step you will have an OpenShift project that you will be able too choose as the deployment target from the Solution Designer of IBM Financial Services Workbench.

Prerequisite

Please ensure, that the basic installation and configuration (see Configuration of Solution Designer and Solution Hub) of Financial Services Workbench on the cluster was successfully performed. At least the component Solution Hub is needed.

Install OpenShift Pipelines

This task can be skipped, if the OpenShift Pipelines Operator was already installed.

Attention: To complete this task a user in the role of a cluster admin is required.

Please install the OpenShift Pipelines Operator. A detailed installation tutorial can be found in the OpenShift Pipelines documentation .

Depending on your cluster settings, it might be necessary that the first two steps are executed by a person with cluster admin permissions (Role: Red Hat OpenShift cluster administrator).

Provide Default Configurations for k5-projects

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

In order to make use of default configuration values within k5-projects, 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 thus configurations.

Note: For using the Configuration Management a valid user is needed with the role of CM_ADMIN (see ../../configuration/content/user-overview.html#user-configuration__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 the Solution Hub is installed.

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 solutions.

  • Mongo: Database settings for the deployed solutions, 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 Provide k5-project default configurations

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 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-account, that is driving the k5-project-operator ( k5-operator-sa ). Therefore please select the project created above ( myprojectname ). 

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

Please replace cpd with the name of the project, e.g. zen , where IBM Cloud Pak for Data and the Solution Hub were 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 in the namespace where cpd and the Solution Hub were installed.

Step 3: Create an Instance of the Custom Resource k5project

After setting up the project and granting permissions, you can now create a new k5project . k5project is a custom resource definition in OpenShift, that can be treated like other kubernetes resources.

Please login into the OpenShift web console and open Custom Resource Definitions in the Administration section. Open k5project and select the Instances tab. Then click on Create k5project .

Trouble: 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 ).
Tip: View sidebar right above the editor will show a sidebar with detailed documentation and examples.

Descriptions for the settings of a k5project resource can be found below.

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

Example configuration 

apiVersion: k5.project.operator/v1
kind: k5project
metadata:
  name: dev-stage
  namespace: dev-stage
spec:
  configuration:
    configurationManagement:
      autoConfiguration:
        enabled: true
      replicaSet: 2
    pipelineManager:
      replicaSet: 2
    iam:
      autoConfiguration:
        enabled: true
      host: 'https://keycloak.apps.ocp43.tec.uk.ibm.com'
      realm: ssob
    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: zen
  type: DEV

Custom Resource Definition of a k5project

Variable
Description
Example
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. 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 k5project
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 dev-world
metadata.namespace Namespace defines the space within each name must be unique myprojectname
spec.configuration.configurationManagement.autoConfiguration.enabled Automatically setup default configuration values in the configuration management for deploying solutions. Default value is true. 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. 2
spec.configuration.pipelineManager. configmap.extra A section containing settings for the behaviour of the pipelineManager, in the narrower sense all settings that do not fit to the logging or spring section.
spec.configuration.pipelineManager. configmap.logging A section containing settings for the logging behaviour of the pipelineManager.
spec.configuration.pipelineManager. configmap.spring A section containing spring boot settings for the behaviour of the pipelineManager, in the narrower sense the spring.boot framework.
spec.configuration.pipelineManager. replicaSet The number of pods, that should be running the service. Default value is 2. 2
spec.configuration.pipelineManager. webhookUrl Webhook url that can be used for the auto deploy feature of "Build and Deploy" pipelines. Default is https://k5-pipeline-trigger-webhook-k5project.domain https://k5-pipeline-trigger-webhook-dev-stage.apps.openshift-cluster.mydomain.cloud
spec.configuration.iam. additionalClientRedirectPatterns Additional redirect URIs, that should be considered, when the clients are created automatically.
spec.configuration.iam. autoConfiguration.enabled Whether the auto-configuration (creating clients in IAM and providing the secrets) will be done automatically. Auto-configuration for the IAM will try to configure the necessary clients and provides the kubernetes secrets to the project containing the relevant security binding data. true
spec.configuration.iam. host The hostname including the protocol that is used as security provider (IAM, OIDC compliant). https://keycloak.apps.openshift-cluster.mydomain.cloud
spec.configuration.iam. realm The realm that is used as security provider (IAM, OIDC compliant). dev-world
spec.configuration.truststore. autoConfiguration.enabled Whether auto-configuration should be enabled or not. Please be aware that enabling the trust store auto-configuration may set the security of your system at risk. Please do not use this for production or high security scenarios. Auto-configuration 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 auto-configuration. 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 mongo database
  • the messagehub service (kafka)
  • any other systems that are called from solution implementations
Note: 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.
 See Format Example
spec.configuration.kafka.enabled Whether kafka will be availabe in the k5 project or not.
Attention: This Variable must not be changed after the creation of a k5 project.
 true
spec.configuration.istio.enabled Whether OpenShift Service Mesh will be availabe in the k5 project or not.
Attention: This Variable must not be changed after the creation of a k5 project.
 false
spec.configuration.istio.strictMtls Whether OpenShift Service Mesh will be availabe with Strict mTLS policy or not. false
spec.hostname The hostname under which the solutions, that are running in the k5-project, will be accessible.
Attention: This Variable must not be changed after the creation of a k5 project.
 dev-world.apps.openshift-cluster.mydomain.cloud
spec.previousStages A list of k5 projects (project name) that can be used as previous stage. That means by setting a previous stage you will be able to create a "Deploy"-pipeline based on an already built solution from a "Build And Deploy"-pipeline in previous stage (k5 project). If previous stages are set the k5 project operator will create a rolebinding to allow the "Deploy"-pipelines and the Pipeline Manager to get/watch imagestreams from the previous stage. This permission settings can be done manually as well, please see Build and Deploy. 
previousStages: 
- my-dev-projectname
spec.stage A freely defineable string, that referes to your logical staging name. dev-stage
spec.tetheredTo The project (namespace) where the base installation of cpd 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.
Attention: This Variable must not be changed after the creation of a k5 project.
 zen
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. DEV

Format Example spec.configuration.truststore.additionalCertificates 

additionalCertificates:
  identity: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  messagehub: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
Attention: 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.
Attention: 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 4: Configure Configuration Management and Users

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

For running the pipelines successfully for managed low code typescript solutions, you also need to setup a user, that is used for testing purposes. Furthermore you can adjust the default configuration for deployed solutions and enable or disable certain features (see Configuration Management API ).

Validate the Installation

After the operator is done with processing the information contained in the custom resource you should see two new deployments in the project you created: 

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

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 dashboard and pipeline manager 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 zen get po | grep k5project
$ oc -n zen logs k5projectoperator-845dbf97cf-8gvlr

Designer CI/CD issues

In case you observe issues with the CI/CD pipeline, please check the logs of the k5-query operator as follows:

$ oc -n zen get po | grep k5-query
$ oc -n zen logs k5-query-6d6f88f8f9-hcb8x

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 commandline for example (assuming that fsw-dev is the project, that should be deleted): 

$ oc project fsw-dev 
$ oc delete k5dashboard k5-dashboard 
$ oc delete k5pipelinemanager k5-pipeline-manager 
$ oc delete k5realm --all 
$ oc delete k5client --all
$ oc delete k5topic --all

Note: If still k5project is not deleted then edit YAML of the k5project CRD instance then delete finalizers tag under metadata of CRD