Create OpenShift Projects as Deployment Targets

Overview

In order to build and deploy the 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 k5project 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 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 of Financial Services Workbench on the cluster was successfully performed. At least the component Solution Hub is needed.

Install OpenShift Pipelines

Attention: To complete this task a user in the the cluster admin role 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).

Step 1: Create an OpenShift project

On the commandline 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 ). Herefore 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. Is 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.iam.additionalClientRedirectPatterns Additional redirect URIs, that should be considere, 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. 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 autoconfiguration should be enabled or not. Please be aware that enabling the truststore 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 truststore. By default this feature will not be enabled.
spec.configuration.truststore.additionalCertificates Specification for further certificates, that should be part of the default truststore. They will be appended regardless of the truststore 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 mongo database
  • the messagehub service (kafka)
  • any other systems that are called from solution implementations
See Format Example
spec.configuration.kafka.enabled Whether kafka will be availabe in the k5 project or not. true
spec.hostname The hostname under which the solutions, that are running in the k5-project will be accessible. dev-world.apps.openshift-cluster.mydomain.cloud
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. zen
spec.type The type of the k5 project. This refers to the type of useage 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 truststore 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 truststores, if the services are using certificates issued by the internal cluster certificate authority.

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:

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