Configuration Management API
Introduction
The configuration of k5-projects and solutions is done via a REST API called Configuration Management API.
It is split up into two controllers:
- K5Project Configuration - create and configure cluster-wide default service bindings
- Solution Configuration - project-wide default settings and solution-specifc configurations and service bindings
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).
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. API Endpoints of K5Project Configuration
The following API endpoints are available:
-
/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}
GET
: Get all Kafka bindings of a project
-
/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}/{bindingName}
-
/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}
GET
: Get all MongoDB bindings of a project
-
/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}/{bindingName}
-
/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}
GET
: Get all authentication bindings of a project
-
/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}/{bindingName}
Parameters
Parameter | Type | Description |
---|---|---|
bindingName |
string |
The name of the binding. |
runtimeName |
string |
The name of the specific k5-project, e.g.
cpd-runtime-default . Passing the namespace of
the Solution Hub will return the results for the default. |
Get all Kafka bindings of a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}
HTTP method
GET
Description
Get all Kafka bindings of a project
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}" -H "accept: application/json" -H "Authorization: Bearer {BearerToken}"
Responses
- 200 - Get a list of Kafka settings (media type: application/json)
Get a specific Kafka binding of a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}/{bindingName}
HTTP method
GET
Description
Get a specific Kafka binding of a project
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}/{bindingName}" -H "accept: application/json" -H "Authorization: Bearer {BearerToken}"
Responses
- 200 - Get the settings of a specific Kafka binding of a certain k5-project. (media type: application/json)
Create or update a Kafka binding for a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}
HTTP method
POST
Description
Create or update a Kafka binding for a project
curl -X POST "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}/{bindingName}" -H "accept: */*" -H "Authorization: Bearer {BearerToken}" -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\"}]}"
Parameter | Description |
---|---|
|
Bootstrap address, that will be used for bootstrapping the messaging server |
|
Name of the user, that will be used for accessing the messaging server |
|
Password of the user, that will be used for accessing the messaging server |
|
SASL mechanism that is used by the Kafka client to
communicate with the messaging server; either
PLAIN or
SCRAM-SHA-512 |
|
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 |
|
Allows to specify some custom arguments for connecting to the
messaging server; usually this is not needed
|
Responses
- 201 - The Kafka binding has been successfully created. (media type: */*)
Delete a specific Kafka binding of a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}/{bindingName}
HTTP method
DELETE
Description
Delete a specific Kafka binding of a project
curl -X DELETE "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/kafka/{namespace}/{bindingName}" -H "accept: */*" -H "Authorization: Bearer {BearerToken}"
Responses
- 204 - The Kafka binding has been deleted. (media type: */*)
Get all MongoDB bindings of a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}
HTTP method
GET
Description
Get all MongoDB bindings of a project
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}" -H "accept: application/json" -H "Authorization: Bearer {BearerToken}"
Responses
- 200 - Get a list of MongoDB settings (media type: application/json)
Get a specific MongoDB binding of a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}/{bindingName}
HTTP method
GET
Description
Get a specific MongoDB binding of a project
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}/{bindingName}" -H "accept: application/json" -H "Authorization: Bearer {BearerToken}"
Responses
- 200 - Get the settings of a specific MongoDB binding of a certain k5-project. (media type: application/json)
Create or update a MongoDB binding for a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}
HTTP method
POST
Description
Create or update a MongoDB binding for a project
curl -X POST "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}/{bindingName}" -H "accept: */*" -H "Authorization: Bearer {BearerToken}" -H "Content-Type: application/json;charset=UTF-8" -d "string"
Body parameter
Enter the mongodb connection string directly.
Responses
- 201 - The MongoDB binding has been successfully created. (media type: */*)
Delete a specific MongoDB binding of a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}/{bindingName}
HTTP method
DELETE
Description
Delete a specific MongoDB binding of a project
curl -X DELETE "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/mongoDb/{namespace}/{bindingName}" -H "accept: */*" -H "Authorization: Bearer {BearerToken}"
Responses
- 204 - The MongoDB binding has been deleted. (media type: */*)
Get all authentication bindings of a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}
HTTP method
GET
Description
Get all authentication bindings of a project
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}" -H "accept: application/json" -H "Authorization: Bearer {BearerToken}"
Responses
- 200 - Get a list of authentication settings (media type: application/json)
Get a specific authentication binding of a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}/{bindingName}
HTTP method
GET
Description
Get a specific authentication binding of a project
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}/{bindingName}" -H "accept: application/json" -H "Authorization: Bearer {BearerToken}"
Responses
- 200 - Get the settings of a specific authentication binding of a certain k5-project. (media type: application/json)
Create or update a authentication binding for a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}
HTTP method
POST
Description
Create or update a authentication binding for a project
curl -X POST "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}/{bindingName}" -H "accept: */*" -H "Authorization: Bearer {BearerToken}" -H "Content-Type: application/json" -d "{\"issuer\":\"string\",\"clientId\":\"string\",\"clientSecret\":\"string\",\"tokenUri\":\"string\",\"jwkUri\":\"string\",\"userAuthorizationUri\":\"string\"}"
Parameter | Description |
---|---|
|
The issuer of the token |
|
The client id to use |
|
The client secret |
|
The token URL of the identity provider that is used to get tokens |
|
The URL of the JSON Web Key set |
|
The URL of the identity provider that is used to authenticate |
|
Deprecated: The base URL of the identity provider |
|
Deprecated: The realm that is used for authentication |
|
Deprecated: The token URL of the identity provider that is used to get tokens |
Responses
- 201 - The authentication binding has been successfully created. (media type: */*)
Delete a specific authentication binding of a project
Endpoint
/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}/{bindingName}
HTTP method
DELETE
Description
Delete a specific authentication binding of a project
curl -X DELETE "https://{your-hostname}/api/cfg/v1/runtimes/k5ProjectBindings/oidc/{namespace}/{bindingName}" -H "accept: */*" -H "Authorization: Bearer {BearerToken}"
Responses
- 204 - The authentication binding has been deleted. (media type: */*)
API Endpoints of Solution Configuration
The following API endpoints are available:
-
/api/cfg/v1/runtimes/{runtimeName}/solutions/
GET
: Get all solutions that have a Solution Configuration
-
api/cfg/v1/runtimes/{runtimeName}/solutions/-/configurations
GET
: Get all Project Configurations
-
api/cfg/v1/runtimes/{runtimeName}/solutions/-/configurations{configurationName}
-
/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations
GET
: Get all Solution Configurations
-
/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}
Parameters
Parameter | Type | Description |
---|---|---|
configurationName |
string |
The name of the configuration:
ssob-sdo-values-yaml |
runtimeName |
string |
The name of the specific k5-project, e.g.
cpd-runtime-default |
solutionAcronym |
string |
The acronym of a solution, e.g. ORDERS |
Get all solutions that have a Solution Configuration
Endpoint
/api/cfg/v1/runtimes/{runtimeName}/solutions/
HTTP method
GET
Description
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/" -H "accept: application/json" -H "Authorization: Bearer {Bearer Token}"
Responses
- 200 - A list of all acronyms of solutions that have a Solution Configuration. (media type: application/json)
Get all Project Configurations
Endpoint
/api/cfg/v1/runtimes/{runtimeName}/solutions/-/configurations
HTTP method
GET
Description
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/-/configurations" -H "accept: application/json" -H "Authorization: Bearer {Bearer Token}"
Responses
- 200 - A list of all Project Configurations (media type: application/json)
Get a specific Project Configuration
Endpoint
/api/cfg/v1/runtimes/{runtimeName}/solutions/-/configurations/{configurationName}
HTTP method
GET
Description
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/-/configurations/{configurationName}" -H "accept: text/plain" -H "Authorization: Bearer {Bearer Token}"
Responses
- 200 - The content of the requested Project Configuration (media type: application/json)
Create or Update Project Configurations
Each new k5-project needs a project configuration. These settings can be edited later, but the changes will only affect new solutions or existing solutions without a Solution Configuration after they have been re-deployed.
Endpoint
/api/cfg/v1/runtimes/{runtimeName}/solutions/-/configurations/{configurationName}
HTTP method
POST
Description
curl -x POST "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/-/configurations/{configurationName}" -H "accept: text/plain" -H "Authorization: Bearer {BearerToken}" -H "Content-Type: text/plain" -d ""
Responses
- 201 - The Project Configuration has been successfully created (media type: */*)
Parameter | Description | Default Value |
---|---|---|
|
Hostname of the specific k5-project (e.g.
cpd-runtime-default.apps.openshift-cluster.mydomain.cloud ) |
required - no default value available |
|
Secret of the OIDC configuration for the event manager. | event-manager-oauth-client-secret |
|
Defines if cross-origin resource sharing is enabled or not. If
set to true , CORS policy where the value is set to
'*' (any origin is allowed) is enabled. |
false |
|
Defines if solutions shall send events to a k5-project namespace-wide topic. | false |
|
Defines that solutions use DEV bindings, that are defined in the
Solution Designer if no service binding is deployed in the
Kubernetes cluster. This feature flag will be set automatically
(true for DEV projects) if
spec.configuration.configurationManagement.
autoConfiguration.enabled is set in the k5-project crd
instance (see Create a
k5project) |
false |
|
Defines if the internal APIs of a solution are exposed to the provided Swagger UI. | false |
|
Defines if Kafka will be available in the deployed solution. If
Kafka events are enabled, sent business events (see
Managing Events) are sent to the Kafka service and then
handled and executed by the solution. If Kafka events are not
enabled, sent business events are directly handled and executed by
the solutions without using a Kafka service (event-streaming). The
revision logging (audit) and data events are also not sent to a
Kafka service and just written to the log output without Kafka being
enabled. The logger names are audit-event for the
revision logging and data-event for the data
events. Ensure that a Kafka service is available and enabled in the
k5project if it should be used by solutions. This feature flag will
be set automatically if
spec.configuration.configurationManagement.
autoConfiguration.enabled is set in the k5project crd
instance (see Create a
k5project) |
true |
|
Defines if an additional API for testing is available. This
feature flag will be set automatically to true if
spec.configuration.configurationManagement.
autoConfiguration.enabled is set in the k5project crd
instance (see Create a
k5project) |
false |
|
Specifies the image registry for the solution. | image-registry.openshift-image-registry.svc:5000 |
|
The secret used to pull images for solution deployment (not needed for OpenShift registry). | nil |
|
Service binding name for the MongoDB service (created by the k5-project-operator). | k5-default-document-storage-service-binding |
|
Service binding name for the message hub service (created by the k5-project-operator). | k5-default-message-service-binding |
|
The name of the secret holding the OIDC configuration for the solution. | k5-default-iam-service-binding |
|
Use self-created default service account, role and role binding. If true the specific service account names are not used. | false |
|
Set existing service account name for the solution deployment, only used if rbac.useSelfCreated is false. | cpd-viewer-sa |
|
Set existing service account name for the deployment jobs, only used if rbac.useSelfCreated is false. | cpd-editor-sa |
|
Adjust the log level configuration for low-code solutions. The configured log config.json will be used in the solution's Helm deployment and the information will be saved in the deployment of the solution. For more information about the log level configuration see How to change the default log level for a Low-Code-Solution | see example below |
Example of parameter solution.logging:
solution:
logging: {
"/src-impl/api/apitest/operations/*" : "trace",
"/src-impl/api/apitest/operations/addDate.test" : "info",
"/src-impl/api/apitest/operations/addNumber" : "error",
"/sdk/v1/*" : "info",
"/sdk/v1/handler/*" : "trace"
}
Delete Project Configurations
Endpoint
/api/cfg/v1/runtimes/{runtimeName}/solutions/-/configurations/{configurationName}
HTTP method
DELETE
Description
DELETE
method Delete a specific Project Configuration in
the Swagger UI
orcurl -X DELETE "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/-/configurations/{configurationName}" -H "accept: text/plain" -H "Authorization: Bearer
Responses
- 204 - The Project Configuration has been deleted (media type: */*)
Get all Solution Configurations of a Solution
Endpoint
/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations
HTTP method
GET
Description
curl -X GET "{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations" -H "accept: application/json" -H "Authorization: Bearer {BearerToken}"
Responses
- 200 - A list of all Solution Configurations of the requested solution (media type: application/json)
Get a specific Solution Configuration of a Solution
Endpoint
/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}
HTTP method
GET
Description
curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}" -H "accept: text/plain" -H "Authorization: Bearer {BearerToken}"
Responses
- 200 - The content of the requested Solution Configuration (media type: text/plain)
Create or Update Solution Configurations
Endpoint
/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}
HTTP method
POST
Description
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 | Description | Default Value |
---|---|---|
|
Hostname of the specific k5-project (e.g.
cpd-runtime-default.apps.openshift-cluster.mydomain.cloud ) |
required - no default value available |
|
Secret of the OIDC configuration for the event manager. | event-manager-oauth-client-secret |
|
Defines if cross-origin resource sharing is enabled or not. If
set to true , CORS policy where the value is set to
'*' (any origin is allowed) is enabled. |
false |
|
Defines if solutions shall send events to a k5-project namespace-wide topic. | false |
|
Defines that solutions use DEV bindings, that are defined in the
Solution Designer if no service binding is deployed in the
Kubernetes cluster. This feature flag will be set automatically
(true for DEV projects) if
spec.configuration.configurationManagement.
autoConfiguration.enabled is set in the k5-project crd
instance (see Create a
k5project) |
false |
|
Defines if the internal APIs of a solution are exposed to the provided Swagger UI. | false |
|
Defines if Kafka will be available in the deployed solution. If
Kafka events are enabled, sent business events (see
Managing Events) are sent to the Kafka service and then
handled and executed by the solution. If Kafka events are not
enabled, sent business events are directly handled and executed by
the solutions without using a Kafka service (event-streaming). The
revision logging (audit) and data events are also not sent to a
Kafka service and just written to the log output without Kafka being
enabled. The logger names are audit-event for the
revision logging and data-event for the data
events. Ensure that a Kafka service is available and enabled in the
k5project if it should be used by solutions. This feature flag will
be set automatically if
spec.configuration.configurationManagement.
autoConfiguration.enabled is set in the k5project crd
instance (see Create a
k5project) |
true |
|
Defines if an additional API for testing is available. This
feature flag will be set automatically to true if
spec.configuration.configurationManagement.
autoConfiguration.enabled is set in the k5project crd
instance (see Create a
k5project) |
false |
|
Specifies the image registry for the solution. | image-registry.openshift-image-registry.svc:5000 |
|
The secret used to pull images for solution deployment (not needed for OpenShift registry). | nil |
|
Service binding name for the MongoDB service (created by the k5-project-operator). | k5-default-document-storage-service-binding |
|
Service binding name for the message hub service (created by the k5-project-operator). | k5-default-message-service-binding |
|
The name of the secret holding the OIDC configuration for the solution. | k5-default-iam-service-binding |
|
Use self-created default service account, role and role binding. If true the specific service account names are not used. | false |
|
Set existing service account name for the solution deployment, only used if rbac.useSelfCreated is false. | cpd-viewer-sa |
|
Set existing service account name for the deployment jobs, only used if rbac.useSelfCreated is false. | cpd-editor-sa |
|
Adjust the log level configuration for low-code solutions. The configured log config.json will be used in the solution's Helm deployment and the information will be saved in the deployment of the solution. For more information about the log level configuration see How to change the default log level for a Low-Code-Solution | see example below |
|
Username used for executing the solution's tests (e.g.
dev-test-user ). The test user must exist or be
created in the realm that this k5-project is using. |
|
|
Password used for the specified default user for executing the
solution's tests (e.g. password123 ). This user must
match the value provided above for the user-alias. |
|
Example of parameter solution.logging:
solution:
logging: {
"/src-impl/api/apitest/operations/*" : "trace",
"/src-impl/api/apitest/operations/addDate.test" : "info",
"/src-impl/api/apitest/operations/addNumber" : "error",
"/sdk/v1/*" : "info",
"/sdk/v1/handler/*" : "trace"
}
Responses
- 201 - The Solution Configuration has been successfully created (media type: */*)
configurationName
.
New parameters cannot be appended to existing configurations.Delete Solution Configurations
Endpoint
/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}
HTTP method
DELETE
Description
curl -X DELETE "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}" -H "accept: text/plain" -H "Authorization: Bearer {BearerToken}"
Responses
- 204 - The Solution Configuration has been deleted (media type: */*)
Examples
-
The following example creates a Solution Configuration named "example-configuration" for the solution "service1" to
- disable the test support
- use the DEV binding for calling API dependencies
- not support events
- not expose the internal APIs
Enter the following values at the Swagger UI:
runtimeName cpd-runtime-test solutionAcronym service1 configurationName example-configuration Request body(data) feature: testSupport: false devBinding: true kafkaEvents: false exposeInternalApi: false
Or use the following cURL command:
curl -X POST "https://{your-hostname}/api/cfg/v1/runtimes/cpd-runtime-test/solutions/service1/configurations/example-configuration" -H "accept: */*" -H "Authorization: Bearer {BearerToken}" -H "Content-Type: text/plain" -d "feature: testSupport: false devBinding: true kafkaEvents: false exposeInternalApi: false"
- Create a solution-specific test configuration with a Solution
Configuration
The following example creates or changes the test configuration of the solution "service1" to user "Testuser" with password "Password".
Enter the following values at the Swagger UI:
runtimeName cpd-runtime-test solutionAcronym service1 configurationName service1-test Request body user-alias: default: "Testuser" user: Testuser: "Password"
Or use the following cURL command:
curl -X POST "https://{your-hostname}/api/cfg/v1/runtimes/cpd-runtime-test/solutions/service1/configurations/service1-test" -H "accept: */*" -H "Authorization: Bearer {BearerToken}" -H "Content-Type: text/plain" -d "user-alias: default: \"Testuser\" user: Testuser: \"Password\""
-
Example body parameter for a typical development stage (data):
environment: host: "cpd-runtime-default.apps.openshift-cluster.mydomain.cloud" feature: corsPolicy: true devBinding: true testSupport: true
-
Example body parameter for a typical production stage (data):
environment: host: "prod.apps.openshift-cluster.mydomain.cloud" feature: corsPolicy: true