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 Kogito Serverless Workflow projects

Usage:
  kn workflow [command]

Available Commands:
  build       Build a Kogito Serverless Workflow project and generate a container image
  completion  Generate the autocompletion script for the specified shell
  create      Create a Kogito Serverless Workflow project
  deploy      Deploy a Kogito Serverless Workflow project
  help        Help about any command

Flags:
  -h, --help      help for kn-workflow
  -v, --verbose   Print verbose logs

Use "kn workflow [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 workflow project in your current directory.

The create command sets up 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 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

  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 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 workflow project using Knative CLI

After creating your workflow project, you can use the 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 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 build command, you need to provide either --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 build --image my-user/my-project:1.0.0 --image-repository other-user --image-tag 1.0.1

Strategy for building a 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 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 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 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 build --image my-project --push

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