Run Time Configuration

Introduction

The Run Time Configuration is used to set up all necessary parameters for running solutions, that have been deployed within this particular k5-project. These settings will not affect Solution Designer or Solution Hub.

Settings can be made for each k5-project which then will be set as the default settings for every solution in this k5-project. Each solution can have its own individual settings that will override the project settings.
Attention: It is mandatory to provide the default configuration values as stated in the Provide Default Configuration Values section.

This includes also the test configuration which needs to be set on project level but can be overwritten by a solution-specific configuration.

The Run Time Configuration is split up in three parts:

The configuration of k5-projects and built solutions is done via a REST API called Configuration Management API. This API provides a Swagger UI for ease-of-use but you can use the tool of your choice for calling APIs (e.g. cURL, Postman).

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 -n <namespace>
, whereby <namespace> points to the namespace, where the Solution Hub is installed.

One of the main purposes of the Configuration Management API is to create the most important bindings for each k5-project.

  • MongoDB: Database settings for deployed solutions, which are using this database as persistent storage for their data
  • OIDC: Settings for the default OIDC compliant IAM provider, which is used for authentication of deployed solutions.
  • Kafka: Settings for accessing the Kafka messaging system (optional)

The operations to create those bindings are located within the section of k-5-project-configuration-controller.

Provide Default Configuration Values

Providing cluster-wide default configuration values is following the same procedure as stated below for the project-wide configuration of the 3 bindings:

The small but nevertheless important difference is to specify the namespace where the Solution Hub was installed and not the project's namespace. The name must be set, but is effectively determined by the system itself.

So for example, if you want to provide a default Mongo database connection and the Solution Hub was installed within the namespace zen, the corresponding cURL command could look like:

curl -X POST "https://configuration-management.apps.openshift-cluster.mydomain.cloud/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/zen/mongodb" \
-H  "accept: */*" \
-H  "Authorization: Bearer eyJhb...." \
-H  "Content-Type: application/json;charset=UTF-8" \
-d "mongodb://mongoUser:mongoPassword@mongodb.mymongonamespace.svc.cluster.local:27017/admin?ssl=false"

Default configuration values are only considered during the creation of a new k5-project. Altering the default configuration values will not have any effect on existing k5-projects. To alter yet existing values for a k5-project, the given operations can be used within the affected namespace directly.

Note: The names of the bindings for default configurations are determined by the system.For administering default configuration values, the namespace of the Solution Hub must be specified.
Attention: The configuration is mandatory for the k5-project-operator to run gracefully.

Managing MongoDB Bindings

Listing MongoDB settings of a namespace

Use GET method Get all MongoDB bindings of a project in the Swagger UI or
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}" -H  "accept: application/json" -H  "Authorization: Bearer {Bearer Token}"
Table 1. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be reported for cpd-hub Passing the namespace of the Solution Hub will return the results for the default.

Reading a specific MongoDB setting of a namespace

Use GET Get a specific MongoDB binding of a project in the Swagger UI or
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}/{bindingName}" -H  "accept: application/json" -H  "Authorization: Bearer {Bearer Token}"
Table 2. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be reported for fsw-dev Passing the namespace of the Solution Hub will return the results for the default.
bindingName path parameter (String) the bindingName which should be read special-mongo-02 The existing binding names can be listed via the Operation Get all MongoDB bindings of a project

Set values for a specific MongoDB setting of a namespace

Use POST method Create or update a specific MongoDB binding for a project in the Swagger UI or
curl -X POST "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}/{bindingName}" -H  "accept: */*" -H  "Authorization: Bearer {Bearer Token}" -H  "Content-Type: application/json;charset=UTF-8" -d ""
Table 3. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be reported for fsw-dev Passing the namespace of the Solution Hub will set the values for the default.
bindingName path parameter (String) the bindingName which should be set special-mongo-02 The existing binding names can be listed via the Operation Get all MongoDB bindings of a project
Request body body (String) the content which should be set 
mongodb://mongoUser:mongoPassword@mongodb.mymongonamespace.svc.cluster .local:27017/admin?ssl=false
 The string refers to the database connection string, that should be used

Delete a specific MongoDB setting of a namespace

Use DELETE method Delete a specific MongoDB binding of a project in the Swagger UI or
curl -X DELETE "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{runtimeName}/{bindingName}" -H  "accept: */*" -H  "Authorization: Bearer {Bearer Token}"
Table 4. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be deleted fsw-dev Passing the namespace of the Solution Hub will delete the default.
bindingName path parameter (String) the bindingName which should be deleted special-mongo-02 The existing binding names can be listed via the Operation Get all MongoDB bindings of a project

OIDC Settings

Listing OIDC settings of a namespace

Use GET method Get all authentication bindings for a project in the Swagger UI or
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}" -H  "accept: application/json" -H  "Authorization: Bearer {Bearer Token}"
Table 5. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be reported for fsw-dev Passing the namespace of the Solution Hub will return the results for the default.

Reading a specific OIDC setting of a namespace

Use GET method Get a specific authentication binding of a project in the Swagger UI or
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}/{bindingName}" -H  "accept: application/json" -H  "Authorization: Bearer {Bearer Token}"
Table 6. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be reported for fsw-dev Passing the namespace of the Solution Hub will return the results for the default.
bindingName path parameter (String) the bindingName which should be read special-oidc-cloud-iam The existing binding names can be listed via the Operation Get all authentication bindings of a project

Set values for a specific OIDC setting of a namespace

Use POST method Create or update an authentication binding for a project in the Swagger UI or
curl -X POST "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}/{bindingName}" -H  "accept: */*" -H  "Authorization: Bearer {Bearer Token}" -H  "Content-Type: application/json;charset=UTF-8" -d "{\"issuer\":\"string\",\"clientId\":\"string\",\"clientSecret\":\"string\",\"tokenUri\":\"string\",\"jwkUri\":\"string\",\"userAuthorizationUri\":\"string\",\"baseUrl\":\"string\",\"realm\":\"string\",\"tokenEndpoint\":\"string\"}"
Table 7. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be reported for fsw-dev Passing the namespace of the Solution Hub will set the values for the default.
bindingName path parameter (String) the bindingName which should be set special-oidc-cloud-iam The existing binding names can be listed via the Operation Get all authentication bindings of a project
Request body body (OidcBinding) the content which should be set see example below The entry refers to schema given in the table below.
Example of a request body 
{
  "issuer": "https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/v2.0",
  "clientId": "8325d28e-840e-4420-928c-33382d4b92a9",
  "clientSecret": "aaf83822-6beb-4ea7-ab78-6af08e81ca8d",
  "tokenUri": "https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/token",
  "jwkUri": "https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/discovery/v2.0/keys",
  "userAuthorizationUri": "https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/authorize",
  "baseUrl": "https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/",
  "realm": "mySecurityRealm",
  "tokenEndpoint": "https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/discovery/v2.0/keys"
}
Table 8. Explanation of an OIDC binding:
Property Type Description Example
issuer string The issuer of the token https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/v2.0
clientId string The client id to use 8325d28e-840e-4420-928c-33382d4b92a9
clientSecret string The client secret aaf83822-6beb-4ea7-ab78-6af08e81ca8d
tokenUri string The token URL of the identity provider that is used to get tokens https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/token
jwkUri string The URL of the JSON Web Key Set https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/discovery/v2.0/keys
userAuthorizationUri string The URL of the identity provider that is used to authenticate https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/oauth2/v2.0/authorize
baseUrl string The base URL of the identity provider (only needed for legacy reasons; should be similar to the issuer) https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/
realm string mySecurityRealm The realm that is used for authentication (only needed for legacy reasons)
tokenEndpoint string The token URL of the identity provider that is used to get tokens https://login.microsoftonline.com/426abd8d-4518-4fd8-b768-107155ec5d15/discovery/v2.0/keys
For a general overview on how to enable an OIDC provider for solutions see Configuring OIDC Provider for solutions

Delete a specific OIDC setting of a namespace

Use DELETE method Delete a specific authentication binding of a project in the Swagger UI or
curl -X DELETE "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}/{bindingName}" -H  "accept: */*" -H  "Authorization: Bearer {Bearer Token}"
Table 9. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be deleted fsw-dev Passing the namespace of the Solution Hub will delete the default.
bindingName path parameter (String) the bindingName which should be deleted special-oidc-cloud-iam The existing binding names can be listed via the Operation Get all authentication bindings of a project

Kafka Settings

Listing Kafka settings of a namespace

Use GET method Get all Kafka bindings for a namespace in the Swagger UI or
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}" -H  "accept: application/json" -H  "Authorization: Bearer {Bearer Token}"
Table 10. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be reported for fsw-dev Passing the namespace of the Solution Hub will return the results for the default.

Reading a specific Kafka setting of a namespace

Use GET method Get a specific Kafka binding of a project in the Swagger UI or
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}/{bindingName}" -H  "accept: application/json" -H  "Authorization: Bearer {Bearer Token}"

Reads a dedicated setting for Kafka messaging.

Table 11. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be reported for fsw-dev Passing the namespace of the Solution Hub will return the results for the default.
bindingName path parameter (String) the bindingName which should be read special-kafka-cloud The existing binding names can be listed via the Operation Get all Kafka bindings of a project

Set values for a specific Kafka setting of a namespace

Use POST method Create or update a Kafka binding for a projectin the Swagger UI or
curl -X POST "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}/{bindingName}" -H  "accept: */*" -H  "Authorization: Bearer {Bearer Token}" -H  "Content-Type: application/json" -d "{\"kafka_brokers_sasl\":[\"string\"],\"user\":\"string\",\"password\":\"string\",\"saslJaasConfigLoginModuleQualifiedName\":\"org.apache.kafka.common.security.scram.ScramLoginModule\",\"saslMechanism\":\"SCRAM-SHA-512\",\"kafka_custom_config\":[{\"key\":\"null\",\"value\":\"null\"}]}"
Table 12. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be reported for fsw-dev Passing the namespace of the Solution Hub will set the values for the default.
bindingName path parameter (String) the bindingName which should be set special-kafka-cloud The existing binding names can be listed via the Operation Get all Kafka bindings for a namespace
Request body body (KafkaBinding) the content which should be set see example below The entry refers to schema given in the table below.
Example of a request body :
{
  "kafka_brokers_sasl": ["kafka-bootstrap.kafka-namespace.svc.cluster.local:9093"],
  "user": "kafka-user",
  "password": "secret123",
  "saslJaasConfigLoginModuleQualifiedName": "org.apache.kafka.common.security.scram.ScramLoginModule",
  "saslMechanism": "SCRAM-SHA-512",
  "kafka_custom_config": []
}
Table 13. Explanation of a Kafka binding
Property Type Description Example
kafka_brokers_sasl Array of string bootstrap address, that will be used for bootstrapping the messaging server ["kafka-bootstrap.kafka-namespace.svc.cluster.local:9093"]
user string name of the user, that will be used for accessing the messaging server kafka-user
password string password of the user, that will be used for accessing the messaging server secret123
saslMechanism string SASL mechanism that is used by the Kafka client to communicate with the messaging server; either PLAIN or SCRAM-SHA-512 SCRAM-SHA-512
saslJaasConfigLogin ModuleQualifiedName string SASL Jaas Config Login Module that is used by the Kafka client to communicate with the messaging server; either org.apache.kafka.common.security .plain.PlainLoginModule or org.apache.kafka.common.security .scram.ScramLoginModule org.apache.kafka.common.security. scram.ScramLoginModule
kafka_custom_config Array of key/value string-pairs Allows to specify some custom arguments for connecting to the messaging server; usually this is not needed 
[{
  "key": "mySpecialKey",
  "value": "mySpecialValue"
}]

Delete a specific Kafka setting of a namespace

Use DELETE method Delete a specific Kafka binding of a project in the Swagger UI or
curl -X DELETE "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}/{bindingName}" -H  "accept: */*" -H  "Authorization: Bearer {Bearer Token}"
Table 14. Request Parameter
Parameter Type Description Example Comment
namespace path parameter (String) the namespace (k5-project) where the settings should be deleted fsw-dev Passing the namespace of the Solution Hub will delete the default.
bindingName path parameter (String) the bindingName which should be deleted special-kafka-cloud The existing binding names can be listed via the Operation Get all Kafka bindings of a project