Single Service Deployment

As an easy and lightweight way for deploying a single service, there is the possibility to directly deploy a project within the Deploy Pipeline. With this technique, any user gets a quick way to see and try out the implemented functionality.

Warning:

It is not unreservedly recommended to use this deployment type for deploying projects to production. The recommended way to roll-out services is to use Application Composition

Settings

In general the helm chart of a projects consists of following but not exclusively these resources:

values.yaml: to adjust the deployment configuration
configmap: storing the configuration for the deployed project
deployment: deployment definition
hpa: horizontal pod autoscaler definition
pdb: pod disruption budget
routes: exposing the service to the outside world; only if istio is not used
service: service definition
solution: custom resource to define the project
istio related resources:
- destination rules: the istio replacement of routes
- virtual service: the istio replacement of service

values.yaml

The values.yaml defines the defaults and options to adjust the deployment of a project.

In general but not exclusively following sections exists:

routes: Configuration of hsts headers, rate limits, exposed paths
horizontal pod autoscaler: enables and configures the horizontal pod autoscaler; must be in sync with deployment replica count and pod disruption budget
pod disruption budget: enables and configures the pod disruption budget; must be in sync with horizontal pod autoscaler and deployment replica count
deployment replica count: desired number of deployed containers; must be in sync with horizontal pod autoscaler and pod disruption budget
deployment container: in deep configuration of the container like resource requests and limits, security context, extra containers and init containers, extra volumes and volume mounts, startup, readiness and liveness probes
features flags: enabling or disabling of, e.g., kafka, mongo, etc. support
configuration secret source names: the names of secret storing the configuration and credentials of kafka, mongo, and oidc services
deployment configuration: the project name, identifier etc.
images: the used docker images
rbac: the service account name
configmap: additional config map configuration like logging

The details how to configure the project are described in Create or Update K5-Project Configurations

Warning:

The route configuration for limiting the number of concurrent TCP connections made through the same source IP address is set to 50 by default for any component, see OpenShift annotation haproxy.router.openshift.io/rate-limit-connections.concurrent-tcp in the OpenShift documentation - Route configuration.

Undeploy

For undeploying services, that have been deployed as single-service-deployment, the usage of the k5-undeploy task is recommended. This task cleans up all the resources, that have been created during the deployment in a safe manner. It does not remove any kafka or database resources.

Swagger UI

If the Swagger UI Support extension is enabled for your service project, the deployed service offers a Swagger UI to easily consume the provided API. The Swagger UI built within the service can be accessed from the following url: {service-host}/{service-acronym}/swagger-ui/index.html.

Manage API Bindings

API bindings are externalized specifications created per API dependency. They can be used to store API-related information that may be stage-dependent.

Applying stage-dependent values

Tip:

API bindings can be used to provide different information for different stages/projects. Don't forget to re-deploy the solution to have access to any updated or appended key/value pairs.

To create an API binding, you have to use the Configuration Management API under Solution Configuration and create a new Solution Configuration.

Tip:

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

https://ssob-config.<domain>

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).## Managing API bindings

API bindings are created as Solution Configurations. Therefore, you can use the same operations to query them. Each API binding results in an OpenShift secret and will be stored and handled as an OpenShift secret.

Get all Solution configurations of a project

Use GET method Get all Solution Configurations in the Swagger UI or

curl -X GET "{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations" -H "accept: application/json" -H  "Authorization: Bearer {BearerToken}"

Get a specific Solution Configuration of a project

Use GET method Get a specific Solution Configuration in the Swagger UI or

curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}" -H  "accept: text/plain" -H "Authorization: Bearer {BearerToken}"

Request Parameters:


Parameter	Type	Description
runtimeName	path parameter (String)	The name of the specific k5-project, e.g. dev-stage
solutionAcronym	path parameter (String)	The acronym of a solution, e.g. ORDERS
configurationName	path parameter (String)	The name of the specific Solution Configuration.

Create or edit API bindings

Use POST method Create or update a specific Solution Configuration in the Swagger UI or

curl -X POST "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}" -H "accept: */*" -H "Authorization: Bearer {BearerToken}" -H  "Content-Type: text/plain" -d ""


Parameter	Type	Description
configurationName	path parameter (String)	The name of the configuration - must be the integration namespace's acronym concatenated by a dash with the API-dependency name in Solution Designer (e.g. acronym-dependencyname)
runtimeName	path parameter (String)	The name of the deployment target, e.g. dev-stage.
solutionAcronym	path parameter (String)	Acronym (in capitals) of the specific project/component that uses the dependency, e.g. ORDERS.
configurationValue	body parameter (JSON)	The binding information needed to call the dependency.

Tip:

You might not need a specific API binding if the named dependency is also developed with IBM Industry Solutions Workbench , and you marked "Local Lookup" while adding the API dependency in your solution. If the JSON Web Token (JWT) that is used in a solution should be forwarded to call the API dependency, the following must be included in the configuration value (as JSON): "k5_propagate_security_token": true

Delete API bindings

Use DELETE method Delete a specific Solution Configuration in the Swagger UI or

curl -X DELETE "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}" -H  "accept: text/plain" -H "Authorization: Bearer {BearerToken}"

Request Parameters:


Parameter	Type	Description
runtimeName	path parameter (String)	The name of the specific k5-project, e.g. dev-stage
solutionAcronym	path parameter (String)	The acronym of a solution, e.g. ORDERS
configurationName	path parameter (String)	The name of the specific Solution Configuration.

Examples

Call an internal API (built with IBM Industry Solutions Workbench)

In this example, there is a service project with an acronym of "MYPROJ" that contains an integration namespace with the prefix "extdat". This integration namespace has an API dependency modelled with an identifier "querydata" to query data from the REST API ("v1") of another service project with an acronym of "CNR". Both service projects have been built with IBM Industry Solutions Workbench and have the same deployment target "dev-stage" configured. The service project "CNR" has to be deployed already on that deployment target to be called by "MYPROJ".

Since both projects are built with IBM Industry Solutions Workbench and running on the same target, we also want to pass on the JWT token automatically. To do so, we also add k5_propagate_security_token to the binding and set its value to true.

Now to actually make use of the methods to call that REST API, you need to create an API binding as described below:

runtimeName            dev-stage
solutionAcronym        MYPROJ
configurationName      extdat-querydata
Request body           {
                         "url": "https://dev-stage.apps.openshift-host.cloud/cnr/api/v1",
                         "k5_propagate_security_token": true
                       }

Call an external API

Now if the above-mentioned service project needs to query data from an external REST API (e.g., an ML-Service) that is not running in the same deployment target, you would create another API dependency inside the same integration namespace with an identifier of "callexternalapi". Querying this external REST API requires passing credentials with each request. These can also be added to the API binding using custom fields.

Note:

The custom fields depend on the REST API you want to query. Please be aware, that none of the custom fields get auto-mapped to any part of the HTTP request. But you have access to these key/value pairs while implementing without having to care about their values since these can be configured from outside the project. This allows you to map any custom value to the required part of the request, e.g. headers, parameters or even the request body.

The required API binding can be created as described below:

runtimeName            dev-stage
solutionAcronym        MYPROJ
configuratioName       extdat-callexternalapi
Request body           {
                         "url": "https://mlpattern.123.456.789.10.example.io",
                         "user": "userName",
                         "password": "passWord"
                       }

Warning:

Any change to the API binding will only be applied to the projects after a new deployment.