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

Fixes based on 10.0.x-kn-plugin-workflow review #667

Merged
merged 5 commits into from
Aug 7, 2024
Merged

Fixes based on 10.0.x-kn-plugin-workflow review #667

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dc8cc8b
10.0.x-kn-plugin-workflow - Improve the kn workflow plugin installation
domhanak Jul 25, 2024
0a12188
10.0.x-kn-plugin-workflow - Bring kn-workflow output up2date
domhanak Jul 25, 2024
d0cccd1
10.0.x-kn-plugin-workflow - bring run section up2date
domhanak Jul 25, 2024
061aa9c
10.0.x-kn-plugin-workflow - update the deploy section
domhanak Jul 26, 2024
12994a2
Update serverlessworkflow/modules/ROOT/pages/testing-and-troubleshoot…
domhanak Aug 7, 2024
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
167 changes: 128 additions & 39 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 @@ -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
Expand All @@ -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`
Expand All @@ -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., Open API files) inside the "specs" folder,
domhanak marked this conversation as resolved.
Show resolved Hide resolved
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.
----
--

Expand All @@ -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`
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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`
Expand Down Expand Up @@ -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

Expand All @@ -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`
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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[]