SonataFlow plug-in for Knative CLI

SonataFlow provides a plug-in named kn-workflow for Knative CLI, which provides command line features that help you develop a local workflow project quickly.

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

You can also find brief introduction for some of the commands that the plugin provides.

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 binary file, suitable for your environment, from the KIE Tooling Releases page.

  2. Install the kn workflow command as a plug-in 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 Apple support article: Open a Mac app from an unidentified developer.

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

    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:

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

	Currently, SonataFlow targets use cases with a single Serverless Workflow main
	file definition (i.e. workflow.sw.{json|yaml|yml}).

	Additionally, you can define the configurable parameters of your application in the
	"application.properties" file (inside the root project directory).
	You can also store your spec files (i.e., OpenAPI files) inside the "specs" folder,
    schemas file inside "schemas" folder and also subflows inside "subflows" folder.

	A SonataFlow project, as the following structure by default:

	Workflow project root
		/specs (optional)
		/schemas (optional)
		/subflows (optional)
		workflow.sw.{json|yaml|yml} (mandatory)



Usage:
  kn workflow [command]

Aliases:
  kn workflow, kn-workflow

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
  gen-manifest GenerateOperator manifests
  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 workflow
  -v, --version   version for kn workflow

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

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.

This plugin will build your project and start a SonataFlow container image that will be mapped to your local folder.

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

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

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

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.

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