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 <>. -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 <>. -* 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 <]` 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 <>. + +* A workflow project is created. ++ +For more information about creating a workflow project, see <>. + +* 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 +---- +-- + +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 <>. -* 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 ---- 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 <>. .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 <>. +* 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 ---- 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[]