Managing applications

After creating an application composition project you will be presented with the Overview page of the new project. This page gives an overview on the project, e.g., the creator, the creation date, in which Git repository it is stored, etc. But there is also the Documentation tab which lets you describe all aspects of this application including UML diagrams.

The documentation section

Every project built with IBM Industry Solutions Workbench provides a documentation section and so do application composition projects. The built-in Markdown editor lets you write extensive documentation in a WYSIWYG or text mode with support for text formatting, links, tables and code-blocks. The text editor supports both CommonMark and GitHub Flavored Markdown (GFM) specifications.

Besides that, there is a built-in diagram generator that renders UML diagrams using the plantUML language. To draw a diagram you have two options:

WYSIWYG mode:

  1. Place your cursor where you want to insert a diagram
  2. In the menu bar of the text editor click on "CB" (code block) to create a new code block at the cursor position
  3. On the right side of the line with the code block there will appear a button called "Editor" - click on it
  4. This will open a new CodeBlock Editor window
  5. Select plantuml from the Choose language dropdown menu on the top of the window
  6. This will start the diagram renderer, and you can start creating your UML diagram with live preview
  7. When you're done, click on "OK" to save your diagram

Markdown mode:

  1. Place your cursor where you want to insert a diagram
  2. Type three back-ticks followed by "PlantUML": ```plantuml
  3. This will start the diagram renderer, and you can start creating your UML diagram with live preview
  4. When you're done, hit "Enter" to create a new line and enter three back-ticks again to close the UML renderer
Tip:

Please see the official PlantUML Language Reference Guide for extensive description on how to draw PlantUML diagrams.

Deployment targets

These are the k5-projects to where you want to deploy your application. These deployment targets have to be configured in advance to be available for applications. Please refer to creating new deployment targets if you don't have configured them yet.

Each deployment target represents a separate stage, so you can apply your own staging concept. Typically, this includes DEV, TEST, STAGE and PROD, but you are not limited to these. As these deployment targets are separated, each of them has its very own configuration and also the components added to each of these targets can be configured individually. This enables you to adjust every component to the requirements of the environment it is running in.

All deployment targets can be easily accessed on the Components page by clicking on their tab.

Adding deployment targets:

The following steps will create a new deployment target (stage) for the chosen application.

  1. Click on the "Add deployment target" button
  2. Select the deployment target from the dropdown menu
  3. Click on "Add"

Removing deployment targets:

  1. Click on the trashcan icon next to the filter options button (not the big icon in the right upper corner)
  2. Confirm the removal in the confirmation dialog
Note:

This will only remove the application and its configuration from the deployment target and not affect the deployment target itself.

Components

Now that you have added at least one deployment target you can add components to it.

Adding components

First, you have to select one of the deployment targets by clicking on its tab. Then you can add components by clicking on the Add component action next to the "Commit" button. This opens a dialog showing you the list of the component repositories. After selecting your component repository you can select the component you want to add. As described in composing applications you can either add one of the components listed or add a placeholder for to-be-built components by using the drop-down action Add planned component.

Planned components:

A planned component is considered to be used whenever it is not yet clear how to implement a single microservice, but it is already decided that this component will be needed later. Therefore, planned components should be seen as a placeholder that can later be replaced either by

  • creating a Service Project in case you want to implement the component on your own
  • choosing an Existing Component from the component repository and setting a version to deploy
Warning:

If you choose to replace a planned component with a service project you can only use this service project as a component of the application as soon as you released at least one version of it. An application composition project can only use components that are already in the component repository.

To add planned component you can click on "Add Planned Component" Button. You will then be prompted to provide the following information:

  • Component Name (required)
  • Tags (optional)
  • Icon (optional)
  • Description (optional)

Click on "Add" to add the planned component.

Tip:

If you're working with multiple planned components we recommend providing extensive description, so you have proper information regarding the requirements when creating a service project to implement this component.

Existing components:

An existing component is an already implemented service that either

  • has been created as a service project by the user and has already been released and registered at the component repository, so it can get deployed to an arbitrary deployment target or
  • is a pre-built service delivered by the software manufacturer (framework component) or a third party
  • has been created by the user without IBM Industry Solutions Workbench but is deployable via a Helm chart and therefore can be provided within the component repository

If you want to add existing components from the component repository you can click component's card to view its details and choose the version (the latest version will be pre-selected by default) to use before adding the component(can be changed later).

Note:

Any component will be added only to the deployment target that is currently selected (active tab). You can add different components on the different namespaces or use the same components but different versions of them.

Warning:

It is not possible to add the same component multiple times to an application on the same deployment target.

Removing components

You can easily remove a component by clicking on the three-dots menu button on a component's card and click on "Delete".

Note:

Deleting a component from one deployment target will not remove it from any other deployment target.

Edit versions

There will be times when you want to edit the version of multiple components without having to click on each of the components' cards. You can use the "Edit versions" feature by clicking on the pencil icon next to the "Commit" button. This will open a dialog listing all components added to the currently selected deployment target and their version. Here you can edit the version of multiple components and set them in one action.

Compare Deployment Targets

When working with multiple deployment targets it is most likely that they consist of the same components but may use different versions. In case you composed your initial stage (e.g., DEV) then you would have to do the same setup again for the succeeding deployment target (e.g., TEST) resulting in adding all components again to the second target. To avoid that, there is feature called "compare deployment targets" located left of the "+" icon to add components.

This feature allows you to choose a source target and compare it with another target. The dialog will list all components and their used version of the source target and lets you set a version for the second target. This way, you can duplicate a whole deployment target and edit the version in one go. This will only add the components you selected from the list.

When you're done, click on "Set" to apply the changes to the current deployment target.

Show Application in Solution Hub

You can access a deployed Application Composition Project directly in the Solution Hub by using the jump symbol.

Configuring bindings

Bindings are a way to configure the connection of components to other resources, e.g., external REST APIs or messaging. To edit these bindings you can use the cogwheel icon next to the "Commit" button. This lets you choose between the following bindings:

  • API bindings: used to store information required to call external REST APIs (e.g., URL, certificates, token, etc.)
  • Event topic bindings: used to store information on the event topic used for messaging
Warning:

The configuration of these bindings will only apply for the currently selected deployment target. The bindings need to be configured for each component on each deployment target.

Warning:

If the component repository that the component was added from is deleted then you will need to remove the component and add it again after selecting the component repository that it is in

Deploying applications

After having added all necessary components and configured them according to the requirements of the different deployment targets you need to commit your changes to the Git repository to actually apply these changes.

Clicking on the "Commit" button will persist your changes in the linked Git repository and trigger the GitOps mechanism which will look for deviations between the live state and the desired target state and then sync them. This results in re-deploying one or more components according to your changes.

Warning:

The "Commit" button only applies changes for the currently selected deployment target. To persist your changes on other deployment targets select the corresponding target tab and click on "Commit" again.

Warning:

If the component repository that any component was added from is deleted then you will need to remove the component that has "Error" label and add it again after selecting the component repository that it is in

Migrating old components

When current selected deployment target has any old component that does not have component repository selected yet then:

  • The component card will be labeled by red "Error" label.
  • User will not be able to commit or change API/Topic bindings
  • A modal will be displayed to inform User with the list of component that has Error when User tries to commit
  • User can select a component repository for the component repository by clicking on change version in the three dots on the card.

When current selected deployment target has any component that has an unknown component repository (the selected component repository was deleted):

  • The component card will be labeled by red "Error" label.
  • User will not be able to commit or change API/Topic bindings.
  • A modal will be displayed to inform User with the list of component that has Error when User tries to commit.
  • An error will be displayed to inform the user that the component repository is not existed.
  • User needs to delete and add the component again after selecting the component repository that component exists in.