Serverless Logic

Procedure

1. Create a new OpenShift Serverless Logic workflow project by running the following command:

   $ kn workflow create

   By default, the generated project name is new-project. You can change the project name by using the [-n|--name] flag as follows:

   Example command

   $ kn workflow create --name my-project

Procedure

1. Run the following command to build and run your OpenShift Serverless Logic workflow project:

   $ kn workflow run

   When the project is ready, the Development UI automatically opens in your browser on localhost:8080/q/dev-ui and you will find the Serverless Workflow Tools tile available. Alternatively, you can access the tool directly using http://localhost:8080/q/dev-ui/org.apache.kie.sonataflow.sonataflow-quarkus-devui/workflows.

Procedure

1. Create the workflow configuration YAML file.

   Example workflow-dev.yaml file

   apiVersion: sonataflow.org/v1alpha08
   kind: SonataFlow
   metadata:
     name: greeting 1
     annotations:
       sonataflow.org/description: Greeting example on k8s!
       sonataflow.org/version: 0.0.1
       sonataflow.org/profile: dev 2
   spec:
     flow:
       start: ChooseOnLanguage
       functions:
         - name: greetFunction
           type: custom
           operation: sysout
       states:
         - name: ChooseOnLanguage
           type: switch
           dataConditions:
             - condition: "${ .language == \"English\" }"
               transition: GreetInEnglish
             - condition: "${ .language == \"Spanish\" }"
               transition: GreetInSpanish
           defaultCondition: GreetInEnglish
         - name: GreetInEnglish
           type: inject
           data:
             greeting: "Hello from JSON Workflow, "
           transition: GreetPerson
         - name: GreetInSpanish
           type: inject
           data:
             greeting: "Saludos desde JSON Workflow, "
           transition: GreetPerson
         - name: GreetPerson
           type: operation
           actions:
             - name: greetAction
               functionRef:
                 refName: greetFunction
                 arguments:
                   message:  ".greeting + .name"
           end: true

   1

   is a workflow_name

   2

   indicates that you must deploy the workflow in Dev mode

2. To deploy the application, apply the YAML file by entering the following command:

   $ oc apply -f <filename> -n <your_namespace>

3. Verify the deployment and check the status of the deployed workflow by entering the following command:

   $ oc get workflow -n <your_namespace> -w

   Ensure that your workflow is listed and the status is Running or Completed.

4. Edit the workflow directly in the cluster by entering the following command:

   $ oc edit sonataflow <workflow_name> -n <your_namespace>

5. After editing, save the changes. The OpenShift Serverless Logic Operator detects the changes and updates the workflow accordingly.

Verification

1. To ensure the changes are applied correctly, verify the status and logs of the workflow by entering the following commands:

   1. View the status of the workflow by running the following command:

      $ oc get sonataflows -n <your_namespace>

   2. View the workflow logs by running the following command:

      $ oc logs <workflow_pod_name> -n <your_namespace>

Next steps

1. After completing the testing, delete the resources to avoid unnecessary usage by running the following command:

   $ oc delete sonataflow <workflow_name> -n <your_namespace>

Procedure

1. Open and edit the ConfigMap by running the following command:

   $ oc edit cm <workflow_name>-props -n <namespace>

   Replace <workflow_name> with the name of your workflow and <namespace> with the namespace where your workflow is deployed.

2. Add the properties in the application.properties section.

   Example of a workflow properties stored within a ConfigMap:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     labels:
       app: greeting
     name: greeting-props
     namespace: default
   data:
     application.properties: |
       my.properties.key = any-value

   Ensure the properties are correctly formatted to prevent the Operator from replacing your configuration with the default one.

3. After making the necessary changes, save the file and exit the editor.

Procedure

1. To create a route for the specified service in your namespace by running the following command:

   $ oc expose svc <service_name> -n <namespace>

2. To fetch the URL for the newly exposed service by running the following command:

   $ WORKFLOW_SVC=$(oc get route/<service_name> --template='{{.spec.host}}')

3. Perform a test HTTP call and send a POST request by running the following command:

   $ curl -X POST -H 'Content-Type:application/json' -H 'Accept:application/json' -d '<request_body>' http://$WORKFLOW_SVC/<endpoint>

4. Verify the response to ensure the workflow is functioning as expected.

Procedure

1. Check the workflow status by running the following command:

   $ oc get workflow <name> -o jsonpath={.status.conditions} | jq .

2. To fetch and analyze the the logs from the workflow’s deployment, run the following command:

   $ oc logs deployment/<workflow_name> -f

Procedure

1. Verify that you have the correct file that defines the Workflow you want to delete. For example, workflow.yaml.

2. Run the oc delete command to remove the Workflow from your specified namespace:

   $ oc delete -f <your_file> -n <your_namespace>

   Replace <your_file> with the name of your Workflow file and <your_namespace> with your namespace.

Procedure

1. To define the OpenAPI functions:

   1. Identify and access the OpenAPI specification files for the services you intend to invoke.

   2. Copy the OpenAPI specification files into your workflow service directory, such as src/main/resources/specs.

      The following example shows the OpenAPI specification for the multiplication REST service:

      Example multiplication REST service OpenAPI specification

      openapi: 3.0.3
      info:
        title: Generated API
        version: "1.0"
      paths:
        /:
          post:
            operationId: doOperation
            parameters:
              - in: header
                name: notUsed
                schema:
                  type: string
                required: false
            requestBody:
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/MultiplicationOperation'
            responses:
              "200":
                description: OK
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        product:
                          format: float
                          type: number
      components:
        schemas:
          MultiplicationOperation:
            type: object
            properties:
              leftElement:
                format: float
                type: number
              rightElement:
                format: float
                type: number

   3. To define functions in the workflow, use the operationId from the OpenAPI specification to reference the desired operations in your function definitions.

      Example function definitions in the temperature conversion application

      {
         "functions": [
           {
             "name": "multiplication",
             "operation": "specs/multiplication.yaml#doOperation"
           },
           {
             "name": "subtraction",
             "operation": "specs/subtraction.yaml#doOperation"
           }
         ]
      }

   4. Ensure that your function definitions reference the correct paths to the OpenAPI files stored in the src/main/resources/specs directory.

2. To access the defined functions in the workflow states:

   1. Define workflow actions to call the function definitions you added. Ensure each action references a function defined earlier.

   2. Use the functionRef attribute to refer to the specific function by its name. Map the arguments in the functionRef using the parameters defined in the OpenAPI specification.

      The following example shows about mapping parameters in the request path instead of request body, you can refer to the following PetStore API example:

      Example for mapping function arguments in workflow

      {
         "states": [
          {
            "name": "SetConstants",
            "type": "inject",
            "data": {
              "subtractValue": 32.0,
              "multiplyValue": 0.5556
            },
            "transition": "Computation"
          },
          {
            "name": "Computation",
            "actionMode": "sequential",
            "type": "operation",
            "actions": [
              {
                "name": "subtract",
                "functionRef": {
                  "refName": "subtraction",
                  "arguments": {
                    "leftElement": ".fahrenheit",
                    "rightElement": ".subtractValue"
                  }
                }
              },
              {
                "name": "multiply",
                "functionRef": {
                  "refName": "multiplication",
                  "arguments": {
                     "leftElement": ".difference",
                     "rightElement": ".multiplyValue"
                  }
                }
              }
            ],
            "end": {
              "terminate": true
            }
          }
        ]
      }

   3. Check the Operation Object section of the OpenAPI specification to understand how to structure parameters in the request.
   4. Use jq expressions to extract data from the payload and map it to the required parameters. Ensure the engine maps parameter names according to the OpenAPI specification.

   5. For operations requiring parameters in the request path instead of the body, refer to the parameter definitions in the OpenAPI specification.

      For more information about mapping parameters in the request path instead of request body, you can refer to the following PetStore API example:

      Example for mapping path parameters

      {
        "/pet/{petId}": {
          "get": {
            "tags": ["pet"],
            "summary": "Find pet by ID",
            "description": "Returns a single pet",
            "operationId": "getPetById",
            "parameters": [
              {
                "name": "petId",
                "in": "path",
                "description": "ID of pet to return",
                "required": true,
                "schema": {
                  "type": "integer",
                  "format": "int64"
                }
              }
            ]
          }
        }
      }

      Following is an example invocation of a function, in which only one parameter named petId is added in the request path:

      Example of calling the PetStore function

      {
        "name": "CallPetStore", 1
        "actionMode": "sequential",
        "type": "operation",
        "actions": [
          {
            "name": "getPet",
            "functionRef": {
              "refName": "getPetById", 2
              "arguments": { 3
                "petId": ".petId"
              }
            }
          }
        ]
      }

      1

      State definition, such as CallPetStore.

      2

      Function definition reference. In the previous example, the function definition getPetById is for PetStore OpenAPI specification.

      3

      Arguments definition. OpenShift Serverless Logic adds the argument petId to the request path before sending a request.

Procedure

1. Locate the OpenAPI specification file you want to configure. For example, substraction.yaml.
2. Convert the file name into a valid configuration key by replacing special characters, such as ., with underscores and converting letters to lowercase. For example, change substraction.yaml to substraction_yaml.

3. To define the configuration key, use the converted file name as the REST client configuration key. Set this key as an environment variable, as shown in the following example:

   quarkus.rest-client.subtraction_yaml.url=http://myserver.com

4. To prevent hardcoding URLs in the application.properties file, use environment variable substitution, as shown in the following example:

   quarkus.rest-client.subtraction_yaml.url=${SUBTRACTION_URL:http://myserver.com}

   In this example:

   • Configuration Key: quarkus.rest-client.subtraction_yaml.url
   • Environment variable: SUBTRACTION_URL
   • Fallback URL: http://myserver.com
5. Ensure that the (SUBTRACTION_URL) environment variable is set in your system or deployment environment. If the variable is not found, the application uses the fallback URL (http://myserver.com).

6. Add the configuration key and URL substitution to the application.properties file:

   quarkus.rest-client.subtraction_yaml.url=${SUBTRACTION_URL:http://myserver.com}

7. Deploy or restart your application to apply the new configuration settings.

Procedure

1. Add the workflow-uri-definitions extension to your workflow. Within this extension, create aliases for your URIs.

   Example workflow

   {
     "extensions": [
       {
         "extensionid": "workflow-uri-definitions", 1
         "definitions": {
           "remoteCatalog": "https://my.remote.host/apicatalog/apis/123/document" 2
         }
       }
     ],
     "functions": [ 3
       {
         "name": "operation1",
         "operation": "remoteCatalog#operation1"
       },
       {
         "name": "operation2",
         "operation": "remoteCatalog#operation2"
       }
     ]
   }

Procedure

1. To trace HTTP requests and responses, OpenShift Serverless Logic uses the Apache HTTP client by setting the following property:

   # Turning HTTP tracing on
   quarkus.log.category."org.apache.http".level=DEBUG

2. Add the following configuration to your application’s application.properties file to turn on debugging for the Apache HTTP Client:

   quarkus.log.category."org.apache.http".level=DEBUG

3. Restart your application to propagate the log configuration changes.

4. After restarting, check the logs for HTTP request traces.

   Example logs of a traced HTTP request

   2023-09-25 19:00:55,242 DEBUG Executing request POST /v2/models/yolo-model/infer HTTP/1.1
   2023-09-25 19:00:55,243 DEBUG http-outgoing-0 >> POST /v2/models/yolo-model/infer HTTP/1.1
   2023-09-25 19:00:55,243 DEBUG http-outgoing-0 >> Accept: application/json
   2023-09-25 19:00:55,243 DEBUG http-outgoing-0 >> Content-Type: application/json
   2023-09-25 19:00:55,243 DEBUG http-outgoing-0 >> kogitoprocid: inferencepipeline
   2023-09-25 19:00:55,243 DEBUG http-outgoing-0 >> kogitoprocinstanceid: 85114b2d-9f64-496a-bf1d-d3a0760cde8e
   2023-09-25 19:00:55,243 DEBUG http-outgoing-0 >> kogitoprocist: Active
   2023-09-25 19:00:55,243 DEBUG http-outgoing-0 >> kogitoproctype: SW
   2023-09-25 19:00:55,243 DEBUG http-outgoing-0 >> kogitoprocversion: 1.0
   2023-09-25 19:00:55,243 DEBUG http-outgoing-0 >> Content-Length: 23177723
   2023-09-25 19:00:55,244 DEBUG http-outgoing-0 >> Host: yolo-model-opendatahub-model.apps.trustyai.dzzt.p1.openshiftapps.com

5. Check the logs for HTTP response traces following the request logs.

   Example logs of a traced HTTP response

   2023-09-25 19:01:00,738 DEBUG http-outgoing-0 << "HTTP/1.1 500 Internal Server Error[\r][\n]"
   2023-09-25 19:01:00,738 DEBUG http-outgoing-0 << "content-type: application/json[\r][\n]"
   2023-09-25 19:01:00,738 DEBUG http-outgoing-0 << "date: Mon, 25 Sep 2023 19:01:00 GMT[\r][\n]"
   2023-09-25 19:01:00,738 DEBUG http-outgoing-0 << "content-length: 186[\r][\n]"
   2023-09-25 19:01:00,738 DEBUG http-outgoing-0 << "set-cookie: 276e4597d7fcb3b2cba7b5f037eeacf5=5427fafade21f8e7a4ee1fa6c221cf40; path=/; HttpOnly; Secure; SameSite=None[\r][\n]"
   2023-09-25 19:01:00,738 DEBUG http-outgoing-0 << "[\r][\n]"
   2023-09-25 19:01:00,738 DEBUG http-outgoing-0 << "{"code":13, "message":"Failed to load Model due to adapter error: Error calling stat on model file: stat /models/yolo-model__isvc-1295fd6ba9/yolov5s-seg.onnx: no such file or directory"}"