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.
-
Java 11+ is installed.
-
Maven 3.8.6 or later is installed.
-
(Optional) Docker is installed.
-
(Optional) Podman is installed.
-
Kubernetes CLI is installed.
-
Download the latest binaries from the KIE Tooling Releases page.
-
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:-
Install the Knative CLI. For installation instructions, see Installing kn documentation.
-
Copy the
kn-workflow
binary to a directory in yourPATH
, such as/usr/local/bin
and ensure that the file name iskn-workflow
. -
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.
-
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. -
-
Use the
workflow
subcommand in Knative CLI as follows:Methods to use workflow subcommandkn workflow kn-workflow
Example outputManage 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.
-
SonataFlow plug-in for Knative CLI is installed.
For more information about installing the plug-in, see Installing the SonataFlow plug-in for Knative CLI.
-
In Knative CLI, enter the following command to create a new project:
Creates a project namednew-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 namedmy-project
kn workflow create --name my-project
-
Add more extensions to the Quarkus project during its creation by using the
[-e|--extension]
flag as follows:Create a project withquarkus-jsonp
andquarkus-smallrye-openapi
extensionskn 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.
-
SonataFlow plug-in for Knative CLI is installed.
For more information about installing the plug-in, see Installing the SonataFlow plug-in for Knative CLI.
-
A workflow project is created.
For more information about creating a workflow project, see Creating workflow project using Knative CLI.
-
In Knative CLI, enter the following command to build your workflow project:
Build the project and generate a local image nameddev.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
andtag
isquay.io
andlatest
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 namedquay.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 Jibkn 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 Jibkn 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 Jibkn 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 Dockerkn 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.
-
SonataFlow plug-in for Knative CLI is installed.
For more information about installing the plug-in, see Installing the SonataFlow plug-in for Knative CLI.
-
A workflow project is created.
For more information about created a workflow project, see Creating workflow project using Knative CLI.
-
A workflow project is built.
For more information about building your workflow project, see Building workflow project using Knative CLI.
-
In Knative CLI, enter the following command to deploy your workflow project:
Deploy a workflow projectkn workflow deploy
If the deployment files (
knative.yml
andkogito.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.
Found an issue?
If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!