SonataFlow plugin for Knative CLI

SonataFlow provides a workflow plugin for Knative CLI, which provides command line interface that helps you develop & deploy your workflow projects.

This document describes how you can work with the SonataFlow workflow plugin. You can also find brief introduction for some of the commands that the plugin provides.

Installing the SonataFlow plugin for Knative CLI

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

Prerequisites
Procedure

  1. Download the latest binary file, suitable for your environment, from the Apache KIE download page for releases.

  2. Install the kn workflow command as a plugin of the Knative CLI using the following steps:

    1. Rename the downloaded binary as follows:

      mv kn-workflow-linux-amd64 kn-workflow

    2. Make the binary file executable as follows:

      chmod +x kn-workflow

      On Mac, 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 the support article from Apple with more details.

    3. Copy the kn-workflow binary file to /usr/local/bin.

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

      kn plugin list

    5. You should see a following line kn-workflow : /usr/local/bin/kn-workflow in the output.

    After installing the plugin, you can use kn workflow to run the related subcommands.

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

    Aliases to use workflow subcommand
    kn workflow
kn-workflow
    Workflow plugin provides bulit-in documentation for each command, display it by adding --help after the command
    $ kn workflow --help
    See the documentation of run command
    $ kn workflow run --help

Creating a workflow project using Knative CLI

After installing the SonataFlow plugin, 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. You can use the following commands 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

    This will scaffold a directory named my-project with a simple workflow in JSON format. You can overwrite the format of the workflow to YAML by using the [--yaml-workflow] flag as follows:

    Create a project named my-project with default workflow in YAML format
    kn workflow create --name my-project --yaml-workflow

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. You must be in the root folder of your workflow project.

The plugin will build your project and start a SonataFlow container image in your configured container runtime, that will be mapped to your local folder. A development UI with management console is provided for your to test your workflows functionality.

Prerequisites
Procedure

  1. 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). You can disable this behavior by using the [--open-dev-ui=false] flag

  3. While running, any changes to your workflow project are detected and the image is rebuilt, allowing you so quickly develop the project.

By default, the development image is using port 8080. You can map it to a different port using the [--port <string>] flag as follows:

Run a project and start a local development image using different port
kn workflow run --port 8081

For more options with run command use [-h|--help].

Generating a list of Operator manifests using Knative CLI

After creating your workflow project, you can use the gen-manifest command with kn workflow to generate operator manifest files for your workflow project in your current directory.

This will screate a new file in ./manifests directory in your project.

Prerequisites
Procedure

  1. Enter the following command to generate operator manifests for your workflow project:

    Generate the operator manifest files for your project.
    kn workflow gen-manifest

  2. Apply the generated operator manifest to your cluster:

    Apply the manifest file.
    kubectl apply -f manifests/01-sonataflow_hello.yaml -n <namespace>

For more options with gen-manifest command use [-h|--help].

Deploying a workflow project using Knative CLI

You can use the deploy command combined with kn workflow to deploy your workflow project. You must be in the root folder of your workflow project.

Prerequisites
Procedure

  1. Enter the following command to deploy your workflow project:

    Deploy a workflow project, you must specify a namespace
    kn workflow deploy --namespace <your_namespace>

    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.

For more options with deploy command use [-h|--help].

Undeploying a workflow project using Knative CLI

You can use the undeploy command combined with kn workflow to undeploy your workflow project. You must be in the root folder of your workflow project.

Prerequisites
Procedure

  1. Enter the following command to deploy your workflow project:

    Undeploy a workflow project, you must specify a namespace
    kn workflow undeploy --namespace <your_namespace>

For more options with undeploy command use [-h|--help].

Creating a Quarkus Workflow project using Knative CLI

After installing the SonataFlow plugin, 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. 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.

For more options with quarkus create command use [-h|--help].

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. 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

For more options with quarkus build command use [-h|--help].

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. 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 with knative.yml
    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 or other command line tools if you want to use a complex deployment setup for your workflow project.

For more options with quarkus deploy command use [-h|--help].

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!