Dev Deployments can be used to share work with others or integrate it with other applications still under development.

BAMOE Canvas allows for Dev Deployments targeting OpenShift or simple Kubernetes clusters. This is achieved by applying pre-defined Kubernetes or OpenShift resources, depending on the selected authentication provider.

These authentication provider’s connections can be made with local and remote Kubernetes/OpenShift instances. They can be configured via the "Accounts modal," which is accessed using the person icon at the top-right corner of the page. Instructions for configuring Kubernetes or OpenShift connections are provided upon selection. For more detailed information, refer to the Connecting accounts section.

This connection enables the deployment of all Decisions, Workflows, and even complete Java projects for development purposes only. Within any open project, select the connected account intended for the Dev Deployment and confirm the selection.

kubernetes deploy
Figure 1. Deploy dropdown for a project called "bamoe-sample-project" on BAMOE Canvas

After clicking Deploy, you will be presented with options for different types of deployment:

Kogito Quarkus Blank App

deployment option kogito quarkus blank app
Figure 2. Kogito Quarkus Blank App deployment option

This is the most "hands-off" Dev Deployment option, but it has a few requirements:

  • Your project should only have Decisions and Workflows; all other files will be ignored;

  • The deployment will fail if an error is found in any file.

It’s a pre-defined Quarkus project template that already includes all the dependencies necessary to run a Decision or Workflow. It runs on a container image with Java and Maven, as well as the Dev Deployment Upload Service (read more about it here).

A parameter is shown, giving the user the option to Include DMN Form Webapp. This is a sidecar container containing a webapp that parses the backend service API and dynamically generates a form with all of the Decisions inputs and outputs, allowing the user to fill the inputs simulate differente scenarios.

form
Figure 3. Dev Deployment application for a Decision created from BAMOE Canvas

The current Decision can be changed using the dropdown in the top-right corner (if the deployment has more than one Decision). The Swagger UI can be opened via the kebab menu.

Note
 The DMN Form Webapp only works for Decisions. Workflows should be handled directly via the API or Dev UIs.

Images used in this deployment:

Custom Image

deployment option custom image
Figure 4. Custom Image deployment option

The Custom Image option is the most configurable one and should allow users to create all kinds of different deployments. The deployed image can be changed to whatever the user decides, alongside the container port and initial container command to be executed.

This combination of parameters makes it a highly flexible option, but should be used with care and follow a few requirements still:

  • The deployed image must have an instance of the Dev Deployment Upload Service running on startup, and the service binary should be available in the PATH (The Command parameter is executed after the Dev Deployment Upload Service finishes, in other words, the final command executed by the container will be something like: dev-deployment-upload-service && <CUSTOM_COMMAND>).

  • The Dev Deployment Upload Service must run on the same port defined by the Container Port parameter.

  • After BAMOE Canvas uploads the current project to the container it expects an HTTP 200 response from the <DEPLOYMENT_URL>/q/health endpoint to make sure the deployment was successful (Your deployment will be made even without this endpoint, but BAMOE Canvas won’t be able to know if it was successful or not).

Images used in this deployment:

Note
 This image is used by default, but it can be changed to any other available image. If using another image, it’s recommended creating it based off of quay.io/bamoe/canvas-dev-deployment-base:9.1.0-ibm-0001, more information here)

Deployment tokens

tokens
Figure 5. Dev Deployment tokens list

Dev Deployment tokens are "variables" that can be used inside the parameters on the Dev Deployment modal. They are also used inside the resource YAMLs applied to the Kubernetes/OpenShift cluster (see the topic below). These tokens are then interpolated during the deployment, replacing their strings with a runtime value.

devDeployment: {
  labels: {
    createdBy: "tools.kie.org/created-by",
    partOf: "tools.kie.org/part-of",
 },
  annotations: {
    workspaceId: "tools.kie.org/workspace-id",
    workspaceName: "tools.kie.org/workspace-name",
 },
  uniqueName: string,
  uploadService: {
    apiKey: string,
 },
  workspace: {
    id: string,
    name: string,
 },
  kubernetes: {
    namespace: string,
 },
},
Note
 Some tokens are pre-defined, and others are generated during runtime (like uniqueName and uploadService.apiKey).

These tokens are referenced in the YAML resources using the following notation: ${{ varPath.varName }}. Here are some examples from the tokens above:

  • ${{ devDeployment.labels.createdBy }}

  • ${{ devDeployment.annotations.workspaceId }}

  • ${{ devDeployment.uniqueName }}

  • ${{ devDeployment.kubernetes.namespace }}

Deployment resources requirements

The Kubernetes/OpenShift resources created by a Dev Deployment must have a few labels and annotations so that BAMOE Canvas can list and manage these resources.

For a successful deployment, this is the required information each resource needs:

metadata:
  name: \${{ devDeployment.uniqueName }}
  namespace: \${{ devDeployment.kubernetes.namespace }}
  labels:
    \${{ devDeployment.labels.createdBy }}: kie-tools
    \${{ devDeployment.labels.partOf }}: \${{ devDeployment.uniqueName }}
  annotations:
    \${{ devDeployment.annotations.workspaceId }}: \${{ devDeployment.workspace.id }}
    \${{ devDeployment.annotations.workspaceName }}: \${{ devDeployment.workspace.name }}

  • The name is how the deployment is identified across the board.

  • The namespace is where the deployment should be created in the cluster and should be the same configured in the connected account.

  • The labels (createdBy and partOf) are required so that BAMOE Canvas can filter and map all resources related to a single deployment. Important: createdBy should always have the value kie-tools.

  • The annotations (workspaceId and workspaceName) help match a deployment to a workspace.

Note
 It’s important to note that our Dev Deployment service inside BAMOE Canvas already applies these required labels and annotations by patching the resource YAMLs.

Post Deployment

Upon confirmation of the Dev Deployment, the Dev Deployments dropdown will open, displaying all the previous and current deployments and an indicator showing their status.

kubernetes waiting done
Figure 6. Dev Deployments dropdown demonstrating the deployment process of a project named "bamoe-sample-project" on BAMOE Canvas

After approximately 30 seconds, a green checkmark should appear next to the Dev Deployment. If the deployment was made with the Include DMN Form Webapp option checked, selecting an item in the dropdown will allow you to navigate to the webapp form for decisions. Otherwise, it will navigate to the Swagger UI for your application.

Note
 Dev Deployments are immutable; therefore, if an error occurs or a change is required, a new Dev Deployment must be created. They can easily be deleted from the Dev Deployments dropdown.

How Dev Deployments work?

The "magic" that drives Dev Deployments depends on various parts working together in sync: BAMOE Canvas, your Kubernetes/OpenShift cluster, the container images, the upload service, etc.

Before any Dev Deployment can be made, a new Kubernetes or OpenShift cluster connection to BAMOE Canvas must be created. While doing so, it will automatically fetch all possible API endpoints and map them to their corresponding Kubernetes resource names; this way, it knows how to apply and manage different resources (such as Deployments, Ingresses, Routes, Services, etc.).

When you click Deploy, a lot has to happen behind the scenes so that a Dev Deployment happens. Here’s a basic step-by-step:

  1. BAMOE Canvas will zip all the files in the workspace being deployed (ignoring .git directories);

  2. Then it will load the chosen deployment option (Custom Image or Kogito Quarkus Blank app) YAML files and modify them dynamically:

    • Applying the required patches to set BAMOE Canvas labels, annotations, and resource names;

    • Applying patches related to the parameters set in the deployment modal (each parameter corresponds to a set of patches and tokens);

    • Interpolate all tokens with their corresponding values, including parameters;

    • Split the YAML files into multiple YAMLs, making one per resource kind.

  3. Using the Kubernetes resource name and the list of API endpoints saved, requests are made to the cluster to apply each resource YAML, saving the returned resource ID locally to be referenced later.

  4. The cluster will initiate Pods, Services, and other resources. At the same time BAMOE Canvas will keep polling the cluster to find out whether the Deployment is healthy and ready, first by fetching the Deployment resource status, then, when healthy, polling the Dev Deployment Upload Service status to check if it’s ready to receive the upload.

    • If the Deployment resource is not healthy, BAMOE Canvas will keep polling its status whenever it tries to list Kubernetes resources and will show an error icon if the Deployment errors out or a loading icon if the Deployment is pending;

    • If the Deployment is healthy, BAMOE Canvas will start polling the Dev Deployment Upload Service running inside the deployed containers to check if it’s ready to receive an upload;

    • If the Dev Deployment Upload Service fails to respond after a pre-defined timeout, the Dev Deployment fails and is updated with an error icon.

  5. After reaching the "READY" status on the Dev Deployment Upload Service, BAMOE Canvas uploads the .zip file generated in Step 1 to the upload service;

  6. The Dev Deployment Upload Service receives the .zip file and extracts it to the defined path (this path is set using the configured environment variables on the container). After the extraction is over, the service ends with a status code 0 and calls the following defined command (usually mvn quarkus:dev or whatever is defined in the Custom Image option parameter);

  7. A quarkus application starts loading inside the container, while BAMOE Canvas starts polling the container to check if the quarkus app is ready;

  8. When quarkus finishes loading, and the polling succeeds, BAMOE Canvas updates the Dev Deployment icon to a success icon and provides a link to the Dev Deployment endpoint, which can be either:

    • The Quarkus Swagger UI, if deployed via Custom Image or Kogito Quarkus Blank App options, without the DMN Form Webapp parameter;

    • The DMN Form Webapp if the checkbox for it was checked when creating the deployment;

  9. Users can interact with the Dev Deployment and test/validate their decisions and processes; after that’s finished, it’s possible to delete a deployment by hovering over it in the Dev Deployments list and clicking the trash icon.

Limitations

  • All files within the project are included in a Dev Deployment. If an error exists in any of the files, the Dev Deployment will not succeed.