Creating new Deployment Targets

Overview

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

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 you will be able to choose as the deployment target from the Solution Designer of IBM Financial Services Workbench.

Prerequisites

Please ensure, that the basic installation and configuration (see Product Configuration) of IBM 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 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.

Attention: 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 the Solution Designer and Hub are installed (e.g. zen).

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

After setting up the k5-project and granting permissions, you can now create a new k5-project . k5-project 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 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 setup 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
      replicaSet: 2
    pipelineManager:
      replicaSet: 2
      migrateExistingPipelines: false
      useDefaultPipelineTemplates: true
    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 k5-project

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.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.
spec.configuration.pipelineManager.webhookUrl: Webhook URL that can be used for the Auto Deploy feature of Build & 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.pipelineManager.useDefaultPipelineTemplates: By enabling this to true will reset all custom pipeline template definition to default. Default is true
spec.configuration.pipelineManager.migrateExistingPipelines: By enabling this to true will reset migrate all existing pipelines to new pipeline template definition. Default is false
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.
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.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 MongoDB, the message hub service (Kafka) and any other systems that are called from project implementations.
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.
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 ak5-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.previousStages: A list of k5-projects 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 project from a Build & 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 & Deploy.
spec.stage: A freely definable string, that refers to your logical staging name.
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. 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.

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. 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: 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 Low-Code Projects, you also need to setup 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 two new deployments in the k5-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

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 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 command line (assuming that fsw-dev is the k5-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

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.