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-examples.git
The following commit(s) were added to refs/heads/main by this push:
new 62db0ba8d [kie-kogito-examples-2041] [sonataflow] Implement a getting
started example for operator use case (#2042)
62db0ba8d is described below
commit 62db0ba8df8c3d5fba9791aa44066d7cd839cb0d
Author: Dominik Hanák <[email protected]>
AuthorDate: Thu Feb 13 16:46:12 2025 +0100
[kie-kogito-examples-2041] [sonataflow] Implement a getting started example
for operator use case (#2042)
* kie-kogito-examples-2041: Implement a getting started example for
operator use case
Adds example to serverless-operator-examples, that explains basic use cases
of workflow plugin CLI and showcases how to run, deploy and deploy with
custom configuration
on local environment or remote cluster env.
* Update serverless-operator-examples/README.md
Co-authored-by: Gonzalo Muñoz <[email protected]>
* Update
serverless-operator-examples/serverless-workflow-get-random-catfact/README.md
Co-authored-by: Gonzalo Muñoz <[email protected]>
* Update
serverless-operator-examples/serverless-workflow-get-random-catfact/README.md
* kogito-example-2041: Add note about retrieval URL on different clusters
* kogito-examples-2041: Improve steps and NOTE for routes
* kogito-examples-2041: Improve steps and example profiles better
* kogito-examples-2041: Remove timeouts
---------
Co-authored-by: Gonzalo Muñoz <[email protected]>
---
serverless-operator-examples/README.md | 13 ++
.../README.md | 75 ++++++++
.../application.properties | 1 +
.../specs/catfacts.json | 204 +++++++++++++++++++++
.../workflow.sw.json | 71 +++++++
5 files changed, 364 insertions(+)
diff --git a/serverless-operator-examples/README.md
b/serverless-operator-examples/README.md
new file mode 100644
index 000000000..fc1918fcd
--- /dev/null
+++ b/serverless-operator-examples/README.md
@@ -0,0 +1,13 @@
+ Serverless Operator Examples
+
+## Description
+
+In this folder, you can find examples showcasing SonataFlow applications and
their development on Cloud environment. These examples are suitable if you
would like to work with SonataFlow without the need to work with Java and
Quarkus.
+
+
+## Requirements
+
+* Docker or Podman, required for local development scenarios.
+* Access to a Kubernetes cluster.
+* Worklow plugin for KN CLI installed.
+* Visual Studio Code with serverless workflow editor extension installed.
diff --git
a/serverless-operator-examples/serverless-workflow-get-random-catfact/README.md
b/serverless-operator-examples/serverless-workflow-get-random-catfact/README.md
new file mode 100644
index 000000000..95048f731
--- /dev/null
+++
b/serverless-operator-examples/serverless-workflow-get-random-catfact/README.md
@@ -0,0 +1,75 @@
+# {product_name} Operator - Get Random Cat Fact Example
+
+## Description
+
+The goal of this example is to showcase use of [{product_name} plugin for
Knative
CLI](https://sonataflow.org/serverlessworkflow/main/testing-and-troubleshooting/kn-plugin-workflow-overview.html)
for local development and subsequent deployment of finished {product_name}
application.
+
+### Use Case
+
+This example is doing basic decision based on input provided to the workflow.
If the input matches a string, workflow will query a specific endpoint and
store the result, otherwise it uses a static string.
+The example contains workflow definition, necessary application.properties and
an openAPI spec file to be able to query external service.
+
+### Prerequisites
+
+1. Install [{product_name} plugin for Knative
CLI](https://sonataflow.org/serverlessworkflow/main/testing-and-troubleshooting/kn-plugin-workflow-overview.html)
+2. Install the [{product_name}
Operator](https://kiegroup.github.io/kogito-docs/serverlessworkflow/latest/cloud/operator/install-serverless-operator.html)
+3. Checkout this example locally
+
+### Run the example in local environment
+
+In order to ensure the developed workflows does what it is meant to do, `run`
command allows users to spin up a container in development mode on localhost. A
[management
console](https://sonataflow.org/serverlessworkflow/main/testing-and-troubleshooting/quarkus-dev-ui-extension/quarkus-dev-ui-overview.html)
is available for users to play with the workflows.
+
+1. Navigate to the root directory of the example
+2. Execute `kn workflow run`
+3. Navigate to
`http://localhost:8080/q/dev-ui/org.apache.kie.sonataflow.sonataflow-quarkus-devui/workflows`
to access the management console
+4. You can modify the project, any changes will be detected and the container
will update
+
+### Deploy the example to cluster
+
+Once the workflow is doing what it is expected to do, the `deploy` command
allows users to create deployments of the workflow on the targeted cluster. To
deploy a workflow application, [{product_name} plugin for Knative
CLI](https://sonataflow.org/serverlessworkflow/main/testing-and-troubleshooting/kn-plugin-workflow-overview.html)
relies on configuration in `<home_directory>/.kube/config`. If you cluster has
managed access, users need to login prior to the use of CLI.
+
+Please note that by default, the `deploy` command deploys the workflow in
`dev` mode. This mode allows you to examine the deployment in actual k8s
cluster environment, with same development features as `run` command does
locally. Follow the guide to understand how to deploy the workflow in different
modes, suitable for post-development scenarios.
+
+1. Create a namespace for your deployment `oc create namespace catfactexample`
+2. Navigate to the root directory of the example
+3. Execute `kn workflow deploy -n catfactexample`
+4. Access your cluster, you should see new deployment in `catfactexample`
namespace. Note the Route associated with the deployment. For example
`<WORKFLOW_GENERATED_ROUTE_URL>`
+5. Management console can be accessed on the
`<WORKFLOW_GENERATED_ROUTE_URL>/q/dev-ui/org.apache.kie.sonataflow.sonataflow-quarkus-devui/workflows`
+
+[NOTE]
+====
+To retrieve the `<WORKFLOW_GENERATED_ROUTE_URL>` in different environments,
please follow the guides provided for the environment. Here are examples from
[Minikube](https://minikube.sigs.k8s.io/docs/handbook/accessing/) and
[Kind](https://kind.sigs.k8s.io/docs/user/ingress/).
+====
+
+### Undeploy the example from cluster
+
+In order to get rid of the deployment, `undeploy` command allows user to
cleanup the deployed resources.
+
+1. Navigate to the root directory of the example.
+2. Execute `kn workflow undeploy -n catfactexample`
+3. The namespace is now clean and without any resources.
+
+### Deploy the example to cluster with different configuration
+
+By default, `deploy` command generates the Kubernetes definitions during the
deployment. In order to customize these files, use
`--custom-generated-manifests-dir=./manifests` parameter to store the generated
Kubernetes manifests. Once modified, use `--custom-manifests-dir=./manifests`
to use the already generated manifests.
+
+In this example we will make necesarry adjustments to deploy the workflow in
`preview` mode. This mode offers deployment setup closer to production and
allows user to check and validate different custom configuration and supporting
services setup.
+Please note that in `preview` mode the management console is no longer
available.
+
+1. Navigate to the root directory of the example.
+2. Execute `kn workflow deploy -n catfactexample
--custom-generated-manifests-dir=./manifests`. This command will generate
Kubernetes YAML definitions based on your workflow in this location.
+3. Undeploy the `kn workflow deploy -n catfactexample
--custom-generated-manifests-dir=./manifests`
+4. Navigate to the `/.manifests` folder and modify the files. For example, add
`sonataflow.org/profile: preview` under `annotations`.
+5. Navigate to root directory of the example.
+6. Execute `kn workflow deploy -n catfactexample
--custom-manifests-dir=./manifests`
+7. The workflow is now deployed with `sonataflow.org/profile: preview`
annotation.
+
+Another option is to use `gen-manifest` to create the Kubernetes manifests,
run `kn workflow gen-manifest --help` to see the documentation for this
command. The procedure to deploy is as follows:
+
+1. Navigate to the root directory of the example.
+2. Execute `kn workflow gen-manifest -n catfactexample --profile=preview
--custom-generated-manifests-dir=./manifests`
+3. Execute `kn workflow deploy -n catfactexample
--custom-manifests-dir=./manifests`
+4. The workflow is now deployed with `sonataflow.org/profile: preview`
annotation.
+
+If the application deployment uses the `preview` profile, the route is no
longer generated for you. It is up to the user to generate, whether the
workflow should be exposed to public or not.
+In order to trigger the workflows try sending a HTTP POST request to the
endpoint of your workflow application. For example `curl -X POST -H
'Content-Type: application/json' -H 'Accept: application/json' -d
'{"fact":"random"}' http://<URL_TO_HOST>/getcatfactinformation` where
`URL_TO_HOST` depends on the environment you are in.
\ No newline at end of file
diff --git
a/serverless-operator-examples/serverless-workflow-get-random-catfact/application.properties
b/serverless-operator-examples/serverless-workflow-get-random-catfact/application.properties
new file mode 100644
index 000000000..624e5eaa2
--- /dev/null
+++
b/serverless-operator-examples/serverless-workflow-get-random-catfact/application.properties
@@ -0,0 +1 @@
+quarkus.rest-client.catfacts_json.url=https://catfact.ninja
\ No newline at end of file
diff --git
a/serverless-operator-examples/serverless-workflow-get-random-catfact/specs/catfacts.json
b/serverless-operator-examples/serverless-workflow-get-random-catfact/specs/catfacts.json
new file mode 100644
index 000000000..4255585c3
--- /dev/null
+++
b/serverless-operator-examples/serverless-workflow-get-random-catfact/specs/catfacts.json
@@ -0,0 +1,204 @@
+{
+ "openapi": "3.0.0",
+ "info": {
+ "title": "Cat Fact API",
+ "description": "An API for facts about cats",
+ "contact": {
+ "email": "[email protected]"
+ },
+ "version": "1.0.0"
+ },
+ "paths": {
+ "/breeds": {
+ "get": {
+ "tags": [
+ "Breeds"
+ ],
+ "summary": "Get a list of breeds",
+ "description": "Returns a a list of breeds",
+ "operationId": "getBreeds",
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "limit the amount of results returned",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "successful operation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/Breed"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/fact": {
+ "get": {
+ "tags": [
+ "Facts"
+ ],
+ "summary": "Get Random Fact",
+ "description": "Returns a random fact",
+ "operationId": "getRandomFact",
+ "parameters": [
+ {
+ "name": "max_length",
+ "in": "query",
+ "description": "maximum length of returned fact",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "successful operation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CatFact"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Fact not found"
+ }
+ }
+ }
+ },
+ "/facts": {
+ "get": {
+ "tags": [
+ "Facts"
+ ],
+ "summary": "Get a list of facts",
+ "description": "Returns a a list of facts",
+ "operationId": "getFacts",
+ "parameters": [
+ {
+ "name": "max_length",
+ "in": "query",
+ "description": "maximum length of returned fact",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "limit the amount of results returned",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "successful operation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/CatFact"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "Breed": {
+ "title": "Breed model",
+ "description": "Breed",
+ "properties": {
+ "breed": {
+ "title": "Breed",
+ "description": "Breed",
+ "type": "string",
+ "format": "string"
+ },
+ "country": {
+ "title": "Country",
+ "description": "Country",
+ "type": "string",
+ "format": "string"
+ },
+ "origin": {
+ "title": "Origin",
+ "description": "Origin",
+ "type": "string",
+ "format": "string"
+ },
+ "coat": {
+ "title": "Coat",
+ "description": "Coat",
+ "type": "string",
+ "format": "string"
+ },
+ "pattern": {
+ "title": "Pattern",
+ "description": "Pattern",
+ "type": "string",
+ "format": "string"
+ }
+ },
+ "type": "object"
+ },
+ "CatFact": {
+ "title": "CatFact model",
+ "description": "CatFact",
+ "properties": {
+ "fact": {
+ "title": "Fact",
+ "description": "Fact",
+ "type": "string",
+ "format": "string"
+ },
+ "length": {
+ "title": "Length",
+ "description": "Length",
+ "type": "integer",
+ "format": "int32"
+ }
+ },
+ "type": "object"
+ }
+ }
+ },
+ "tags": [
+ {
+ "name": "Facts",
+ "description": "Cat Facts"
+ },
+ {
+ "name": "Breeds",
+ "description": "Breeds"
+ }
+ ]
+}
\ No newline at end of file
diff --git
a/serverless-operator-examples/serverless-workflow-get-random-catfact/workflow.sw.json
b/serverless-operator-examples/serverless-workflow-get-random-catfact/workflow.sw.json
new file mode 100644
index 000000000..70723ef1b
--- /dev/null
+++
b/serverless-operator-examples/serverless-workflow-get-random-catfact/workflow.sw.json
@@ -0,0 +1,71 @@
+{
+ "id": "getCatFactInformation",
+ "version": "1.0",
+ "specVersion": "0.8.0",
+ "name": "Get cat fact",
+ "description": "Description",
+ "start": "GreetOrCatFact",
+ "functions": [
+ {
+ "name": "getCatFact",
+ "operation": "specs/catfacts.json#getRandomFact"
+ },
+ {
+ "name": "sysOutFunction",
+ "type": "custom",
+ "operation": "sysout"
+ }
+ ],
+ "states": [
+ {
+ "name": "GreetOrCatFact",
+ "type": "switch",
+ "dataConditions": [
+ {
+ "condition": "${ .fact == \"random\"}",
+ "transition": "GetRandomFact"
+ }
+ ],
+ "defaultCondition": {
+ "transition": "GetOneStaticFact"
+ }
+ },
+ {
+ "name": "GetOneStaticFact",
+ "type": "inject",
+ "data": {
+ "message": "Cats are very cute"
+ },
+ "transition": "PrintTheFact"
+ },
+ {
+ "name": "GetRandomFact",
+ "type": "operation",
+ "actions": [
+ {
+ "name": "getRandomFact",
+ "functionRef": {
+ "refName": "getCatFact"
+ }
+ }
+ ],
+ "transition": "PrintTheFact"
+ },
+ {
+ "name": "PrintTheFact",
+ "type": "operation",
+ "actions": [
+ {
+ "name": "greetAction",
+ "functionRef": {
+ "refName": "sysOutFunction",
+ "arguments": {
+ "message": "${\"Fact is that: \" + .message + .fact }"
+ }
+ }
+ }
+ ],
+ "end": true
+ }
+ ]
+}
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
