K5 Project Configuration

Introduction

Attention: All given configurations are only effective for deployed solutions and not for Solution Hub or Solution Designer.

K5-project configuration offers the ability to administer bindings of the following types:

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

Those settings are used for running solutions, that get deployed within this particular k5-project. The concrete used setting for a running solution is finally determined by specifying the name of the configuration within Solution Default Configuration or Solution-Specific Configuration. The possible configuration values can be administered individually per k5-project.

The Configuration Management API provides a REST service for reading and updating this configurations.

The configurations can be done with the provided Swagger UI or any other tool for calling APIs (like 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.

All necessary operations are located within the section of k-5-project-configuration-controller.

Provide Default Configuration Values

Providing default configuration values for k5-projects is following the same procedure as stated below for the 3 areas (Mongo, OIDC, Kafka). The small but nevertheless important difference is to specify the namespace, where the Solution Hub was installed. 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.

Notice: The names of the bindings for default configurations are determined by the system.

Tip: 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.

Mongo Database Settings

Listing Mongo Database Settings of a Namespace

Operation: GET /api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}

Lists all the available settings for the Mongo database.


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 Mongo Database Setting of a Namespace

Operation: GET /api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}

Reads a dedicated setting for the Mongo database.


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` /api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}

Set Values for a Specific Mongo Database Setting of a Namespace

Operation: POST /api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}

Set the values for the Mongo database binding. This operation is capable of updating or creating new bindings.


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` /api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}
`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 Mongo Database Setting of a Namespace

Operation: GET /api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}

Delete a dedicated setting for the Mongo database.


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` /api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}

OIDC Settings

Listing OIDC Settings of a Namespace

Operation: GET /api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}

Lists all the available settings for user authentication via an OIDC compliant Security Provider.


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

Operation: GET /api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}

Reads a dedicated setting for user authentication via an OIDC compliant Security Provider.


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` /api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}

Set Values for a Specific OIDC Setting of a Namespace

Operation: POST /api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}

Set the values for user authentication via an OIDC compliant Security Provider. This operation is capable of updating or creating new bindings.


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` /api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}
`Request body`	body (OidcBinding)	the content which should be set	see example below	The entry refers to schema given in the table below.

Request Body Example

{
  "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"
}

OidcBinding:


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 how to enable OIDC Provider for solutions see Configuring OIDC Provider for solutions

Delete a Specific OIDC Setting of a Namespace

Operation: GET /api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}

Delete a dedicated setting for user authentication via an OIDC compliant Security Provider.


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` /api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}

Kafka Settings

Listing Kafka Settings of a Namespace

Operation: GET /api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}

Lists all the available settings for Kafka messaging.


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

Operation: GET /api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}

Reads a dedicated setting for Kafka messaging.


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` /api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}

Set Values for a Specific Kafka Setting of a Namespace

Operation: POST /api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}

Set the values for Kafka messaging. This operation is capable of updating or creating new bindings.


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` /api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}
`Request body`	body (KafkaBinding)	the content which should be set	see example below	The entry refers to schema given in the table below.

Request Body Example:

{
  "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": []
}

KafkaBinding:


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

Operation: GET /api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}

Delete a dedicated setting for Kafka messaging.


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` /api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}