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]>
apache · Aug 7, 2024 · 9517469 · 9517469
1 parent 0681c04
commit 9517469
Showing 1 changed file with 128 additions and 39 deletions.
diff --git a/...modules/ROOT/pages/testing-and-troubleshooting/kn-plugin-workflow-overview.adoc b/...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[]