Frequently Asked Questions
Got a quick question? You're likely to find the answer here.
Browse through common topics about getting started, using core features, account management, and more.
Lets dive in!
Please note that the links to the workbench tools in this tutorial only apply to the IBM Education Environment we provide. If you are using a different environment, e.g. your own installation, you will need to navigate directly to the required tools.
General FAQs
Installation
You need write permissions for node_modules and bin.
k5 setup?You should use the same credentials as for the Solution Designer.
This is due to missing permissions. Please find the documentation for configuring users here.
Yes, you can make use of all git commands to commit, push, merge etc. Only for the pull, it is necessary to use k5 pull.
Project Basics FAQs
Project
Depending on the used Git provider, special permissions need to be granted. You can find the necessary permissions described here.
To delete a project, other permissions than the ones for creation are needed. Please check the Product Documentation regarding this topic. If the correct permissions are not granted, the delete action will not be available in the tooling.
Application Composition Project
Only released projects can be added to an application. Please ensure that the release pipeline of the service successfully finished.
Yes, every component which was successfully added to the component repository can be added and deployed within an application. That means, also components which were built with other tools than IBM DevOps Solution Workbench.
There is currently not possibility to see in the Solution Designer in which Application(s) a Project is used as Component.
Assets
Yes, within the Asset Catalog, you can remove the Asset from the catalog. The original Project will not be affected by the action.
If a project gets deleted, the previously created Assets will not get deleted automatically and will still remain in the Asset Catalog.
You need write permissions on the Asset Catalog to perform this action. This permission can be set within the Git repository of the Asset Catalog.
You have to add several component repositories in your admin settings where you will configure each image registry separately under the same helm repository details. You need to configure the first image registry to the helm repository and then redo the process to add each of the other image registries. Make sure to set the same helm repository URL, username and password for all the related image registries.
Development FAQs
Domain Service Project Design
Within IBM DevOps Solution Workbench it is best practice that for each consumed microservice one Integration Namespace is created. This helps you to visualize your dependencies to external services. In addition, it is recommended that an Integration Service is created and implemented for each operation to be used in your Project.
If an entity has multiple parents, it inherits properties, incl. the type of association -either required or optional-, of its parents. If it is a root entity, that applies also for commands. When one parent has a property associated as required, while it is for the other parent only optional, it will be required for the child. The generated code varies depending on whether the project stack is Java or Typescript. This still means that both the inherited properties and commands (for root entities) are available to the child entity. However, multi-inheritance should be used with caution since it can increase complexity as it might also contradict the principles of domain-driven-design if it leads to overlapping boundaries or uncertainty.
Yes, you can. When creating your API, you have the flexibility to set a custom base path that is independent of the namespace acronym. The path has to start with a "/" and must not end with a trailing slash so it can be appended to the Base-URL in order to construct the full URL. This allows you to define a more meaningful or tailored URL structure for your API endpoints, separate from the default namespace.
Domain Service Project Implementation
Having the parent entity as Service output and based on your Service logic you can return any of its children (with their additional properties). When this Service is called (i.e. by another Service), you can use the instanceOf operator to detect which child was returned as output.
Only pushed changes from the Solution Designer will have an effect on the implementation. Please ensure that you have executed the "Commit and Push" action in the Designer and then run k5 pull in your project folder again.
Only the design artefacts are automatically deleted in the git repository after committing and pushing. The implementation files are not deleted, neither from the git repository nor from your local workspace. You have to delete the implementation and test files separately with your IDE. This way you have the option to keep the implementation code, e.g. if you want to move the command or service to another location.
Yes, you can make use of all git commands to commit, push, merge etc. Only for the pull, it is necessary to use k5 pull.
Yes, you can differentiate two schemas by using the Discriminator. The discriminator is a mandatory property in the schema. This discriminator must have a unique ENUM value and should be present in each of the OneOf schemas. This helps in identifying the correct schema and hence it is recommended to use the name of the schema for this ENUM value. Note: It is not sufficient for differentiation if a schema has additional properties than the other schema(s).
Domain Service Typescript Project Implementation
As Commands are meant to only create new aggregates or change the state of the aggregate, it is not possible to call Domain Services and REST Integration Services from the Command Implementation.
Instead, it would be best practice to call the Service before calling the Command and provide the data which is necessary for the Command as the Command input.
No. Solutions are separated and have also separated databases. It is not intended and supported to access the database of a different solution. It also doesn't matter if the names and prefixes of entities are the same. Each solution has it's own life-cycle and the integration cannot and must not happen through database, but using the API provided by the solution. In general it is always a good thing to question the requirement and the coupling. If two solutions are highly coupled, it might be a hint, that perhaps the separation was not perfect.
Event handling
You can use the Environment page and visit the "Topic Bindings" tab to see all Topic Bindings.
With Events 2.0 feature, you have a centralized registry that has all the schemas named schema registry. To be able to receive an event from another Workbench Project, you have to select the schema and then remodel the event in the receiving project. Please find the documentation for it here.
Merge conflicts
If you have pushed changes and encountered merge conflicts, first thing to do is to checkout your project in your IDE, then identify the conlicts and review your changes. Next step is to resolve the conflict by deciding either to keep your changes, keep incoming changes or merge both changes manually. If your IDE add conflict markers, make sure to remove them to clean up the file. Last step to do is to preview the changes, add, commit, and push your changes into your main branch.
Pipelines and Deployment FAQs
Pipelines
Yes. When a Workbench project is deleted, the pipeline configurations and pipeline runs associated to it are automatically deleted with it.
Yes. You can specify the branch you want to use in the pipeline while creating it.
No. A deploy pipeline will not have any effect on application components. To update a service in an application, a new version of the service has to be released first and then specified in the application.
To enable the automatically triggering of the pipeline, the flag "Auto Trigger" needs to be set when creating the Pipeline Configuration.
Additionally, some prerequisites need to be prepared on the infrastructure side. Please find the documentation for it here.
No. Pipeline configurations are very lightweight assets and can be easily recreated. Also the deployed service will not be affected by the deletion of a pipeline configuration.
You can configure your workspace storage from your OpenShift console. All you need to do is to change the value for values.service-builder.k5-pipeline-manager.tekton.workspace.storageas you can see in the following image.
For further details how to change this parameter, see the product documentation Product Documentation - Install Configuration.
Service Deployment
Yes. When a Workbench project is deleted, the service which was deployed via a Deploy Pipeline is automatically deleted with it.
Services which were deployed through an application composition project, will persist until the service was removed from the application or the application gets deleted as well.
A good way to browse the logs is to use something like stern, which is a multi pod and container log tailing for Kubernetes.
IBM DevOps Solution Workbench automatically provisions a Swagger UI to access the deployed APIs of a service. The Swagger UI can be accessed on the Environment page UI in the Service Deployments view.
Depending on your installation, permissions for viewing the OpenShift topology might have to be explicitly granted. Please ask your cluster admin to provide you access.
Infrastructure FAQs
Infrastructure
Currently IBM DevOps Solution Workbench doesn't support disabling of Istio once it is enabled.
Yes, there is a way to define custom environment variables. Therefore, please check the Product Documentation.
Yes, PI is included: The host IP address of the user performing the operation to be audited is logged in the audit logging.
When audit logging is enabled (via product configuration by an OpenShift administrator), audit log entries are transferred to a third-party service (Fluentd Service or IBM Audit Logging Service) that is not part of the product and must be secured by the customer with access rights. In the event of a Fluentd service outage/unavailability, the audit payload is stored in log files within the Audit Common Service container that can only be accessed by privileged OpenShift users with access to pods and deployments within the product namespace.
In general we are following Cloud Auditing Data Federation (CADF) format (see https://www.dmtf.org/standards/cadf). More info about the Audit Logging is available in the Release Documentation:
Here is an example of an audit log entry created when a Kafka binding is created with user credentials in the API call. As seen here, the SPI (like credentials) is not logged, only a PI (host IP address):
{
"observer": {
"typeURI": "ssob:target"
},
"typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event",
"id": "cma:305a83db-2130-4cd7-bf65-a92838f66361",
"version": "v1",
"requestPath": "/api/v1/audit/event",
"initiator": {
"id": "83645c0c53246701",
"typeURI": "/api/cfg/v1/runtimes/k5ProjectBindings/kafka/release-dev/mme",
"name": "k5-configuration-management-5cfcf8b4c8-h5dd9",
"credential": {
"type": "token"
},
"host": {
"agent": "java:springboot",
"address": "10.131.3.92"
}
},
"target": {
"id": "2aa00581-a9f4-4de5-a2ec-23db53df5958",
"typeURI": "/api/v1/namespaces/release-dev/secrets",
"name": "Secret",
"addresses": null
},
"reason": {
"reasonType": "HTTPS",
"reasonCode": 201
},
"action": "CREATE",
"eventType": "ACTIVITY",
"severity": "MEDIUM",
"eventTime": "2023-03-14T12:44:13.409680Z",
"outcome": "SUCCESS",
"tags": null,
"kubernetes.container_id": "b65d74b1-8f02-4a25-8667-abeb4d8dc698",
"kubernetes.container_name": "k5-configuration-management-5cfcf8b4c8-h5dd9",
"kubernetes.pod": "k5-configuration-management-5cfcf8b4c8-h5dd9",
"kubernetes.namespace": "release",
"origination": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/537.36"
}