Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[1.42.x] KOGITO-9460: Create a new guide describing the workflow CLI #483

Merged
merged 5 commits into from
Oct 5, 2023
Merged

[1.42.x] KOGITO-9460: Create a new guide describing the workflow CLI #483

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a6f555b
KOGITO-9460: Create a new guide describing the workflow CLI (#432)
domhanak Sep 1, 2023
5bf2e45
Update serverlessworkflow/modules/ROOT/pages/testing-and-troubleshoot…
MarianMacik Sep 4, 2023
bf75b3d
Update serverlessworkflow/modules/ROOT/pages/testing-and-troubleshoot…
MarianMacik Sep 4, 2023
857a691
Update serverlessworkflow/modules/ROOT/pages/testing-and-troubleshoot…
MarianMacik Sep 4, 2023
5d3b2ea
Update serverlessworkflow/modules/ROOT/pages/testing-and-troubleshoot…
MarianMacik Sep 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 132 additions & 31 deletions ...modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,32 +60,35 @@ kn-workflow
.Example output
[source,text]
----
Manage Kogito Serverless Workflow projects
Manage SonataFlow 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
create Creates a new SonataFlow project
deploy Deploy a SonataFlow project on Kubernetes via SonataFlow Operator
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, --verbose Print verbose logs
-h, --help help for kn
-v, --version version for kn

Use "kn workflow [command] --help" for more information about a command.
Use "kn [command] --help" for more information about a command.
----
--

[[proc-create-sw-project-kn-cli]]
== Creating a workflow project using Knative CLI

After installing the {product_name} plug-in, you can use the `create` command with `kn workflow` to scaffold a new workflow project in your current directory.
After installing the {product_name} plug-in, you can use the `create` command with `kn workflow` to scaffold a new {product_name} 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.
The `create` command sets up {product_name} project containing a minimal "hello world" `workflow.sw.json` file in your `./<project-name>` directory.

.Prerequisites
* {product_name} plug-in for Knative CLI is installed.
Expand Down Expand Up @@ -114,27 +117,123 @@ kn workflow create --name my-project
----
--

. Add more extensions to the Quarkus project during its creation by using the `[-e|--extension]` flag as follows:
[[proc-build-sw-project-kn-cli]]
== 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 {product_name} docker image and map your local folder to this image.

.Prerequisites
* {product_name} plug-in for Knative CLI is installed.
+
For more information about installing the plug-in, see <<proc-install-sw-plugin-kn-cli, Installing the {product_name} plug-in for Knative CLI>>.

* A workflow project is created.
+
For more information about creating a workflow project, see <<proc-create-sw-project-kn-cli, Creating workflow project using Knative CLI>>.
* Minikube cluster is running locally.


.Procedure
. In Knative CLI, enter the following command to build and run your workflow project:
+
--
.Create a project with `quarkus-jsonp` and `quarkus-smallrye-openapi` extensions
.Run the project and start a local development image.
[source,shell]
----
kn workflow create --extension quarkus-jsonp,quarkus-smallrye-openapi
kn workflow run
----
--
. Once the project is ready, the Development UI will be opened up in a browser automatically (on `localhost:8080/q/dev`).

You can add multiple extensions using the comma-separated names of the extensions in the previous command.
[[proc-deploy-sw-project-kn-cli]]
== 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
* {product_name} plug-in for Knative CLI is installed.
+
For more information about installing the plug-in, see <<proc-install-sw-plugin-kn-cli, Installing the {product_name} plug-in for Knative CLI>>.

* A workflow project is created.
+
For more information about creating a workflow project, see <<proc-create-sw-project-kn-cli, Creating workflow project using Knative CLI>>.

* A minikube cluster is running locally.

.Procedure
. In Knative CLI, enter the following command to deploy your workflow project:
+
--
.Deploy a workflow project
[source,shell]
----
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]`.

[NOTE]
====
====
You can use the `kubectl` command line if you want to use a complex deployment setup for your workflow project.
====
--

[[proc-create-quarkus-sw-project-kn-cli]]
== Creating a Quarkus Workflow project using Knative CLI

After installing the {product_name} 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 {product_name} 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
* {product_name} plug-in for Knative CLI is installed.
For more information about installing the plug-in, see <<proc-install-sw-plugin-kn-cli, Installing the {product_name} plug-in for Knative CLI>>.
ifeval::["{kogito_version_redhat}" != ""]
* You followed the steps in xref:getting-started/create-your-first-workflow-service.adoc#proc-configuring-maven-rhbq[Configuring your Maven project to Red Hat build of Quarkus and OpenShift Serverless Logic]
endif::[]

.Procedure
. In Knative CLI, enter the following command to create a new project:
+
--
.Creates a project named `new-project`
[source,shell]
----
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`
[source,shell]
----
kn workflow quarkus 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 with `quarkus-jsonp and quarkus-smallrye-openapi` extensions
[source,shell]
----
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.
[NOTE]
====
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.
====
--

[[proc-build-sw-project-kn-cli]]
== Building a workflow project using Knative CLI
[[proc-build-quarkus-sw-project-kn-cli]]
== Building a Quarkus 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.
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.

Expand All @@ -154,15 +253,15 @@ For more information about creating a workflow project, see <<proc-create-sw-pro
.Build the project and generate a local image named `dev.local/my-project`
[source,shell]
----
kn workflow build --image dev.local/my-project
kn workflow quarkus build --image dev.local/my-project
----

[NOTE]
====
By using `dev.local` as repository, you can deploy your {product_name} 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:
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]
Expand All @@ -188,12 +287,12 @@ In case the `--image` flag is composed with specific flags as shown in the follo
.Build the project and generate a local image named `quay.io/other-user/my-project:1.0.1`
[source,shell]
----
kn workflow build --image my-user/my-project:1.0.0 --image-repository other-user --image-tag 1.0.1
kn workflow quarkus build --image my-user/my-project:1.0.0 --image-repository other-user --image-tag 1.0.1
----
--

[[con-build-strategy-kn-cli]]
=== Strategy for building a workflow project
=== Strategy for building a Quarkus workflow project

You can use the following strategies to build a workflow project and to generate the container image:

Expand All @@ -207,14 +306,14 @@ You can use the following commands to build a workflow project and to generate a
.Build a project and generate a local image using Jib
[source,shell]
----
kn workflow build --image dev.local/my-project --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
[source,shell]
----
kn workflow build --image dev.local/my-project --jib-podman
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.

Expand All @@ -223,7 +322,7 @@ If you do not want to use any container runtime, then use `--push` to push the g
.Build a project and push the image using Jib
[source,shell]
----
kn workflow build --image my-project --jib --push
kn workflow quarkus build --image my-project --jib --push
----

[IMPORTANT]
Expand All @@ -242,14 +341,14 @@ When using Docker, you can automatically push the container image to the respect
.Build a project and push the image using Docker
[source,shell]
----
kn workflow build --image my-project --push
kn workflow quarkus build --image my-project --push
----
--

[[proc-deploy-sw-project-kn-cli]]
== Deploying a workflow project using Knative CLI
[[proc-deploy-quarkus-sw-project-kn-cli]]
== Deploying a Quarkus 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.
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
* {product_name} plug-in for Knative CLI is installed.
Expand All @@ -271,15 +370,15 @@ For more information about building your workflow project, see <<proc-build-sw-p
.Deploy a workflow project
[source,shell]
----
kn workflow deploy
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`
[source,shell]
----
kn workflow deploy --path other-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.
Expand All @@ -290,8 +389,10 @@ You can use the `kubectl` command line if you want to use a complex deployment s
====
--


== Additional resources

* xref:getting-started/create-your-first-workflow-service.adoc[Creating your first workflow service]
* xref:getting-started/create-your-first-workflow-service.adoc[Creating your first Quarkus Workflow project]
* xref:getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc[Creating your first SonataFlow project]

include::../../pages/_common-content/report-issue.adoc[]