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. From the directory where you created your OpenShift Serverless Logic project, move to your project directory by running the following command:

   $ cd ./<your-project-name>

2. 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 at

   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 using the Dev profile.

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. Specify your container image in your SonataFlow CR:

   Example SonataFlow CR with set GitOps profile

   apiVersion: sonataflow.org/v1alpha08
   kind: SonataFlow
   metadata:
     annotations:
       sonataflow.org/profile: gitops
     name: workflow_name
   spec:
     flow: 

   1

   
   #...
     podTemplate:
       container:
         image: your-registry/workflow_name:tag
   #...

   1

   The flow definition must match the workflow definition used during the build process. When you deploy your workflow using the GitOps profile, the Operator compares this definition with the workflow files embedded in the container image. If the definition and files do not match, the deployment fails.

2. Apply your CR to deploy the workflow:

   $ oc apply -f <filename>

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.

1. The

   SonataFlowPlatform

   configuration in the current context.
2. The global configuration entry in the

   ConfigMap

   resource.
3. The

   FROM

   clause in the Dockerfile within the OpenShift Serverless Logic Operator namespace, defined in the

   logic-operator-rhel8-builder-config

   config map.

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

      <project_application_dir>/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

      <project_application_dir>/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"}"