Creating new deployment targets

Overview

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

NameDescription
apiVersionAPIVersion 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)
kindKind 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.nameName 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.namespaceNamespace defines a logical boundary in which each element must be unique
spec.configuration.configurationManagement.autoConfiguration.enabledAutomatically setup default configuration values in the Configuration Management for deploying projects. Default value is true.
spec.configuration.dashboard.configmap.extraA 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.loggingA section containing settings for the logging behaviour of the dashboard.
spec.configuration.dashboard.configmap.springA section containing spring boot settings for the behaviour of the dashboard, in the narrower sense the spring.boot framework.
spec.configuration.dashboard.replicaSetThe number of pods, that should be running the service. Default value is 2.
spec.configuration.iam.additionalClientRedirectPatternsAdditional redirect URIs, that should be considered, when the clients are created automatically.
spec.configuration.iam.autoConfiguration.enabledWhether 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.hostThe hostname including the protocol that is used as security provider (IAM, OIDC compliant).
spec.configuration.iam.realmThe realm that is used as security provider (IAM, OIDC compliant).
spec.configuration.schemaRegistry.autoConfiguration.enabledWhether autoconfiguration for the schema registry configuration should be enabled or not.
spec.configuration.schemaRegistry.securityEnabledWhether the configured schema registry requires authentication or not (see Schema Registry)
spec.configuration.schemaRegistry.realmThe realm that is used as security provider (IAM, OIDC compliant) for authentication with the configured schema registry (see Schema Registry)
spec.configuration.truststore.autoConfiguration.enabledWhether 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.additionalCertificatesSpecification 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.enabledWhether Kafka will be available in the k5-project or not. Must not be changed after the creation of a k5-project.
spec.configuration.istio.enabledWhether 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.strictMtlsWhether OpenShift Service Mesh will be available with Strict mTLS policy or not.
spec.hostnameThe 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.stageA freely definable string, that refers to your logical staging name.
spec.tetheredToThe 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.typeThe 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 4: Configuration management and users

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

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.