SonataFlow plug-in for Knative CLI

SonataFlow provides a plug-in named kn-plugin-workflow for Knative CLI, which enables you to set up a local workflow project quickly using the command line.

This document describes how you can install and use the kn-plugin-workflow plug-in in SonataFlow.

Installing the SonataFlow plug-in for Knative CLI

You can use the SonataFlow plug-in to set up your local workflow project quickly using Knative CLI.

Prerequisites
Procedure

  1. Download the latest binaries from the KIE Tooling Releases page.

  2. Run the kn workflow command using one of the following methods:

    • Add kn workflow command in your system path and ensure that it is executable.

    • Install kn workflow command as a plug-in of the Knative CLI using the following steps:

      1. Install the Knative CLI. For installation instructions, see Installing kn documentation.

      2. Copy the kn-workflow binary to a directory in your PATH, such as /usr/local/bin and ensure that the file name is kn-workflow.

      3. On Mac, add execution permission as follows:

        chmod +x /usr/local/bin/kn-workflow

        Some systems might block the application to run due to Apple enforcing policies. To fix this problem, check the Security & Privacy section in the System Preferences → General tab to approve the application to run. For more information, see Apple support article: Open a Mac app from an unidentified developer.

      4. Run the following command to verify that kn-workflow plug-in is installed successfully:

        kn plugin list

    After installing the plug-in, you can use kn workflow to run the related subcommands.

  3. Use the workflow subcommand in Knative CLI as follows:

    Methods to use workflow subcommand
    kn workflow
kn-workflow
    Example output
    Manage SonataFlow projects

Usage:
  kn workflow [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  create      Creates a new SonataFlow project
  deploy      Deploy a SonataFlow project on Kubernetes via SonataFlow Operator
  help        Help about any command
  quarkus     Manage SonataFlow projects built in Quarkus
  run         Run a SonataFlow project in development mode
  undeploy    Undeploy a SonataFlow project on Kubernetes via SonataFlow Operator
  version     Show the version

Flags:
  -h, --help      help for kn
  -v, --version   version for kn

Use "kn [command] --help" for more information about a command.

Creating a workflow project using Knative CLI

After installing the SonataFlow plug-in, you can use the create command with kn workflow to scaffold a new SonataFlow project in your current directory.

The create command sets up SonataFlow project containing a minimal "hello world" workflow.sw.json file in your ./<project-name> directory.

Prerequisites
Procedure

  1. In Knative CLI, enter the following command to create a new project:

    Creates a project named new-project
    kn workflow create

    By default, the generated project is named as new-project. You can overwrite the project name by using the [-n|--name] flag as follows:

    Create a project named my-project
    kn workflow create --name my-project

Running a workflow project using Knative CLI

After creating your workflow project, you can use the run command with kn workflow to build & run your workflow project in your current directory.

This will start a SonataFlow docker image and map your local folder to this image.

Prerequisites
Procedure

  1. In Knative CLI, enter the following command to build and run your workflow project:

    Run the project and start a local development image.
    kn workflow run

  2. Once the project is ready, the Development UI will be opened up in a browser automatically (on localhost:8080/q/dev).

Deploying a workflow project using Knative CLI

You can use the deploy command combined with kn workflow to deploy your workflow project in your current directory.

Prerequisites
Procedure

  1. In Knative CLI, enter the following command to deploy your workflow project:

    Deploy a workflow project
    kn workflow deploy

    Also, ensure that you have access to your cluster and your cluster can access the generated container image. For more options with deploy command use [-h|--help].

    You can use the kubectl command line if you want to use a complex deployment setup for your workflow project.

Creating a Quarkus Workflow project using Knative CLI

After installing the SonataFlow plug-in, you can use the quarkus create command with kn workflow to scaffold a new Quarkus Workflow project in your current directory.

The quarkus create command sets up a SonataFlow Quarkus project containing minimal extensions to build a workflow project. Also, the generated workflow project contains a "hello world" workflow.sw.json file in your ./<project-name>/src/main/resources directory.

Prerequisites
Procedure

  1. In Knative CLI, enter the following command to create a new project:

    Creates a project named new-project
    kn workflow quarkus create

    By default, the generated project is named as new-project. You can overwrite the project name by using the [-n|--name] flag as follows:

    Create a project named my-project
    kn workflow quarkus create --name my-project

  2. Add more extensions to the Quarkus project during its creation by using the [-e|--extension] flag as follows:

    Create a project with quarkus-jsonp and quarkus-smallrye-openapi extensions
    kn workflow quarkus create --extension quarkus-jsonp,quarkus-smallrye-openapi

    You can add multiple extensions using the comma-separated names of the extensions in the previous command.

    When you run the create command for the first time, it might take a while due to the necessity of downloading the required dependencies for the Quarkus project.

Building a Quarkus workflow project using Knative CLI

After creating your workflow project, you can use the quarkus build command with kn workflow to build your workflow project in your current directory and to generate a container image.

The process of building your workflow project produces a knative.yml file in the ./target/kubernetes folder. If your workflow contains events, then the building process also generates a kogito.yml file.

Prerequisites
Procedure

  1. In Knative CLI, enter the following command to build your workflow project:

    Build the project and generate a local image named dev.local/my-project
    kn workflow quarkus build --image dev.local/my-project

    By using dev.local as repository, you can deploy your SonataFlow project in a local environment without having to push the image to a container registry.

    To use the quarkus build command, you need to provide either the --image or --image-name flag. In the previous command, you can use the [-i|--image] in several ways, such as:

    • --image=[name]

    • --image=[name]:[tag]

    • --image=[repository]/[name]

    • --image=[repository]/[name]:[tag]

    • --image=[registry]/[repository]/[name]

    • --image=[registry]/[repository]/[name]:[tag]

    The default value for registry and tag is quay.io and latest respectively.

    Also, you can use specific flags to compose the full name of the image as follows:

    • --image-registry

    • --image-repository

    • --image-name

    • --image-tag

    In case the --image flag is composed with specific flags as shown in the following command, then the specific value overrides the --image flag:

    Build the project and generate a local image named quay.io/other-user/my-project:1.0.1
    kn workflow quarkus build --image my-user/my-project:1.0.0 --image-repository other-user --image-tag 1.0.1

Strategy for building a Quarkus workflow project

You can use the following strategies to build a workflow project and to generate the container image:

Using Jib

Jib is an extension that builds a container image without the necessity of a container runtime. When using the Jib extension, the rebuilds are fast and the resultant container image is optimized.

You can use the following commands to build a workflow project and to generate a local image using Jib:

Build a project and generate a local image using Jib
kn workflow quarkus build --image dev.local/my-project --jib

The generated container image can be saved in the Docker runtime.

Build a project and generate a local image using Jib
kn workflow quarkus build --image dev.local/my-project --jib-podman

Using the previous command, the generated container image can be saved in the Podman runtime.

If you do not want to use any container runtime, then use --push to push the generated container image to the respective registry as shown in the following command:

Build a project and push the image using Jib
kn workflow quarkus build --image my-project --jib --push

Before using the --push option, ensure that you have access to your registry. You can get the access using Docker or Podman login.
Using Docker

The process of building your workflow project using Docker is straightforward and also a default approach.

When using Docker, you can automatically push the container image to the respective registry by using the --push option as shown in the following command:

Build a project and push the image using Docker
kn workflow quarkus build --image my-project --push

Deploying a Quarkus workflow project using Knative CLI

You can use the quarkus deploy command combined with kn workflow to deploy your workflow project in your current directory. However, before deploying the project, you must build your workflow project as the build process produces deployment files, such as knative.yml and kogito.yml (In case of events) in the ./target/kubernetes folder.

Prerequisites
Procedure

  1. In Knative CLI, enter the following command to deploy your workflow project:

    Deploy a workflow project
    kn workflow quarkus deploy

    If the deployment files (knative.yml and kogito.yml) are saved in any other folder instead of ./target/kubernetes, then you can override the path using the --path flag with deployment command as follows:

    Deploy a workflow project using --path
    kn workflow quarkus deploy --path other-path

    Also, ensure that you have access to your cluster and your cluster can access the generated container image.

    You can use the kubectl command line if you want to use a complex deployment setup for your workflow project.

Additional resources

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!