OpenShift Serverless Logic plug-in for Knative CLI

OpenShift Serverless Logic 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 OpenShift Serverless Logic.

Installing the OpenShift Serverless Logic plug-in for Knative CLI

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

Prerequisites
Procedure

  1. Follow the procedure Installing Knative CLI

  2. Run the kn workflow command.

    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.

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

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

Methods to use workflow subcommand
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., Open API 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 OpenShift Serverless Logic plug-in, you can use the create command with kn workflow to scaffold a new OpenShift Serverless Logic project in your current directory.

The create command sets up OpenShift Serverless Logic 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 OpenShift Serverless Logic 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 OpenShift Serverless Logic 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 OpenShift Serverless Logic 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 OpenShift Serverless Logic 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!