This is an automated email from the ASF dual-hosted git repository.
dhanak pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-kie-kogito-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 9517469c2 Fixes based on 10.0.x-kn-plugin-workflow review (#667)
9517469c2 is described below
commit 9517469c21b503d377f9238cb92af5f631e79205
Author: Dominik Hanák <[email protected]>
AuthorDate: Wed Aug 7 08:37:31 2024 +0200
Fixes based on 10.0.x-kn-plugin-workflow review (#667)
* 10.0.x-kn-plugin-workflow - Improve the kn workflow plugin installation
Fix the introduction text.
Fix the installation to be more clear.
* 10.0.x-kn-plugin-workflow - Bring kn-workflow output up2date
* 10.0.x-kn-plugin-workflow - bring run section up2date
* 10.0.x-kn-plugin-workflow - update the deploy section
* Update
serverlessworkflow/modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc
Co-authored-by: Ricardo Zanini
<[email protected]>
---------
Co-authored-by: Ricardo Zanini
<[email protected]>
---
.../kn-plugin-workflow-overview.adoc | 167 ++++++++++++++++-----
1 file changed, 128 insertions(+), 39 deletions(-)
diff --git
a/serverlessworkflow/modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc
b/serverlessworkflow/modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc
index 6ae6fe2ec..1c445e5af 100644
---
a/serverlessworkflow/modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc
@@ -7,9 +7,11 @@
// links
:apple_support_url: https://support.apple.com/guide/mac-help/mh40616/mac
-{product_name} 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.
+{product_name} 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-plugin-workflow`
plug-in in {product_name}.
+This document describes how you can install and use the `kn-workflow` plug-in
in {product_name}.
+
+You can also find brief introduction for some of the commands that the plugin
provides.
[[proc-install-sw-plugin-kn-cli]]
== Installing the {product_name} plug-in for Knative CLI
@@ -25,19 +27,23 @@ You can use the {product_name} plug-in to set up your local
workflow project qui
* link:{kn_cli_install_url}[Knative CLI] is installed.
.Procedure
-. Download the latest binary file from the
link:{kie_tools_releases_page_url}[KIE Tooling Releases] page.
+. Download the latest binary file, suitable for your environment, from the
link:{kie_tools_releases_page_url}[KIE Tooling Releases] page.
. Install the `kn workflow` command as a plug-in of the Knative CLI using the
following steps:
+
--
-.. Copy the `kn-workflow` binary file to a directory in your `PATH`, such as
`/usr/local/bin` and ensure that the file name is `kn-workflow`.
+.. Rename the downloaded binary as follows:
++
+mv kn-workflow-linux-amd64 kn-workflow
++
.. Make the binary file executable as follows:
+
-`chmod +x /usr/local/bin/kn-workflow`
+`chmod +x kn-workflow`
+
[WARNING]
====
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 link:{apple_support_url}[Apple support article: Open a
Mac app from an unidentified developer].
====
+.. Copy the `kn-workflow` binary file to `/usr/local/bin`.
.. Run the following command to verify that `kn-workflow` plug-in is installed
successfully:
+
`kn plugin list`
@@ -58,29 +64,48 @@ kn-workflow
.Example output
[source,text]
----
-Manage SonataFlow projects
+ 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]
+ kn workflow [command]
Aliases:
- kn workflow, kn-workflow
+ 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
- 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
+ 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
- -v, --version version for kn
+ -h, --help help for kn workflow
+ -v, --version version for kn workflow
-Use "kn [command] --help" for more information about a command.
+Use "kn workflow [command] --help" for more information about a command.
----
--
@@ -95,12 +120,9 @@ The `create` command sets up {product_name} project
containing a minimal "hello
* {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:use-cases/advanced-developer-use-cases/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:
+. You can use the following command to create a new project:
+
--
.Creates a project named `new-project`
@@ -118,12 +140,21 @@ 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
+[source,shell]
+----
+kn workflow create --name my-project --yaml-workflow
+----
+--
+
[[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.
+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 will start a {product_name} docker image and map your local folder to
this image.
+This plugin will build your project and start a {product_name} container image
that will be mapped to your local folder.
.Prerequisites
* {product_name} plug-in for Knative CLI is installed.
@@ -133,11 +164,10 @@ For more information about installing the plug-in, see
<<proc-install-sw-plugin-
* 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:
+. Enter the following command to build and run your workflow project:
+
--
.Run the project and start a local development image.
@@ -146,12 +176,63 @@ For more information about creating a workflow project,
see <<proc-create-sw-pro
kn workflow run
----
--
-. Once the project is ready, the Development UI will be opened up in a browser
automatically (on `localhost:8080/q/dev`).
+. 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`
+. 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
+[source,shell]
+----
+kn workflow run --port 8081
+----
+--
+
+[[proc-gen-manifests-sw-project-kn-cli]]
+== 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
+* {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>>.
+
+* You have set up your environment according to the
xref:getting-started/preparing-environment.adoc#proc-minimal-local-environment-setup[minimal
environment setup] guide.
+
+
+.Procedure
+. Enter the following command to generate operator manifests for your workflow
project:
++
+--
+.Generate the operator manifest files for your project.
+[source,shell]
+----
+kn workflow gen-manifest
+----
+--
+. Apply the generated operator manifest to your cluster:
++
+--
+.Apply the manifest file.
+[source,shell]
+----
+kubectl apply -f manifests/01-sonataflow_hello.yaml -n <namespace>
+----
+--
+
+For more options with `gen-manifest` command use `[-h|--help]`.
[[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.
+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
* {product_name} plug-in for Knative CLI is installed.
@@ -162,16 +243,18 @@ For more information about installing the plug-in, see
<<proc-install-sw-plugin-
+
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.
+* You have set up your environment according to the
xref:getting-started/preparing-environment.adoc#proc-minimal-local-environment-setup[minimal
environment setup] guide.
+
+* You have installed {operator_name} in your kubernetes cluster according to
xref:cloud/operator/install-serverless-operator.adoc[operator installation]
guide.
.Procedure
-. In Knative CLI, enter the following command to deploy your workflow project:
+. Enter the following command to deploy your workflow project:
+
--
-.Deploy a workflow project
+.Deploy a workflow project, you must specify a namespace
[source,shell]
----
-kn workflow deploy
+kn workflow deploy --namespace <your_namespace>
----
Also, ensure that you have access to your cluster and your cluster can access
the generated container image.
@@ -198,7 +281,7 @@ ifeval::["{kogito_version_redhat}" != ""]
endif::[]
.Procedure
-. In Knative CLI, enter the following command to create a new project:
+. Enter the following command to create a new project:
+
--
.Creates a project named `new-project`
@@ -231,6 +314,8 @@ When you run the `create` command for the first time, it
might take a while due
====
--
+For more options with `quarkus create` command use `[-h|--help]`.
+
[[proc-build-quarkus-sw-project-kn-cli]]
== Building a Quarkus workflow project using Knative CLI
@@ -248,7 +333,7 @@ For more information about installing the plug-in, see
<<proc-install-sw-plugin-
For more information about creating a workflow project, see
<<proc-create-sw-project-kn-cli, Creating workflow project using Knative CLI>>.
.Procedure
-. In Knative CLI, enter the following command to build your workflow project:
+. Enter the following command to build your workflow project:
+
--
.Build the project and generate a local image named `dev.local/my-project`
@@ -346,6 +431,8 @@ kn workflow quarkus build --image my-project --push
----
--
+For more options with `quarkus build` command use `[-h|--help]`.
+
[[proc-deploy-quarkus-sw-project-kn-cli]]
== Deploying a Quarkus workflow project using Knative CLI
@@ -364,8 +451,10 @@ For more information about created a workflow project, see
<<proc-create-sw-proj
+
For more information about building your workflow project, see
<<proc-build-sw-project-kn-cli, Building workflow project using Knative CLI>>.
+* You have set up your environment according to the
xref:getting-started/preparing-environment.adoc#proc-minimal-local-environment-setup[minimal
environment setup] guide.
+
.Procedure
-. In Knative CLI, enter the following command to deploy your workflow project:
+. Enter the following command to deploy your workflow project:
+
--
.Deploy a workflow project
@@ -376,10 +465,10 @@ 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`
+.Deploy a workflow project using `--path` with `knative.yml`
[source,shell]
----
-kn workflow quarkus 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.
@@ -394,6 +483,6 @@ 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-with-kn-cli-and-vscode.adoc[Creating
your first SonataFlow project]
-*
xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[Creating
your first Quarkus Workflow project]
+*
xref:use-cases/advanced-developer-use-cases/getting-started/create-your-first-workflow-service.adoc[Creating
your first SonataFlow project with Quarkus]
include::../../pages/_common-content/report-issue.adoc[]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
