Serverless Logic

手順

1. 次のコマンドを実行して、新しい OpenShift Serverless Logic ワークフロープロジェクトを作成します。

   $ kn workflow create

   Copy to Clipboard Toggle word wrap

   デフォルトでは、生成されるプロジェクト名は new-project です。次のように [-n|--name] フラグを使用してプロジェクト名を変更できます。

   コマンドの例

   $ kn workflow create --name my-project

   Copy to Clipboard Toggle word wrap

手順

1. 次のコマンドを実行して、OpenShift Serverless Logic ワークフロープロジェクトをビルドして実行します。

   $ kn workflow run

   Copy to Clipboard Toggle word wrap

   プロジェクトの準備が整うと、開発 UI がブラウザーの localhost:8080/q/dev-ui で自動的に開き、Serverless Workflow Tools タイルが利用可能になります。または、http://localhost:8080/q/dev-ui/org.apache.kie.sonataflow.sonataflow-quarkus-devui/workflows を使用してツールに直接アクセスすることもできます。

手順

1. ワークフロー設定 YAML ファイルを作成します。

   workflow-dev.yaml ファイルの例

   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

   Copy to Clipboard Toggle word wrap

   1

   workflow_name です。

   2

   ワークフローを開発モードでデプロイする必要があることを示します。

2. アプリケーションをデプロイするには、次のコマンドを入力して YAML ファイルを適用します。

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

   Copy to Clipboard Toggle word wrap

3. 次のコマンドを入力して、デプロイメントを確認し、デプロイされたワークフローのステータスを確認します。

   $ oc get workflow -n <your_namespace> -w

   Copy to Clipboard Toggle word wrap

   ワークフローがリストされており、ステータスが Running または Completed であることを確認します。

4. 次のコマンドを入力して、クラスター内でワークフローを直接編集します。

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

   Copy to Clipboard Toggle word wrap
5. 編集後、変更を保存します。OpenShift Serverless Logic Operator は変更を検出し、それに応じてワークフローを更新します。

検証

1. 変更が正しく適用されていることを確認するには、次のコマンドを入力してワークフローのステータスとログを確認します。

   1. 次のコマンドを実行して、ワークフローのステータスを表示します。

      $ oc get sonataflows -n <your_namespace>

      Copy to Clipboard Toggle word wrap

   2. 次のコマンドを実行してワークフローログを表示します。

      $ oc logs <workflow_pod_name> -n <your_namespace>

      Copy to Clipboard Toggle word wrap

次のステップ

1. テストが完了したら、次のコマンドを実行してリソースを削除し、必要のないリソースの使用を回避します。

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

   Copy to Clipboard Toggle word wrap

手順

1. 以下のコマンドを実行して ConfigMap を開き、編集します。

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

   Copy to Clipboard Toggle word wrap

   <workflow_name> はワークフローの名前に、<namespace> はワークフローがデプロイされている namespace に置き換えます。

2. application.properties セクションにプロパティーを追加します。

   ConfigMap 内に保存されるワークフロープロパティーの例:

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

   Copy to Clipboard Toggle word wrap

   Operator が設定をデフォルトの設定に置き換えないように、プロパティーが正しくフォーマットされていることを確認してください。

3. 必要な変更を行った後、ファイルを保存してエディターを終了します。

手順

1. 次のコマンドを実行して、namespace 内の指定されたサービスへのルートを作成します。

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

   Copy to Clipboard Toggle word wrap

2. 新しく公開されたサービスの URL を取得するには、次のコマンドを実行します。

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

   Copy to Clipboard Toggle word wrap

3. 次のコマンドを実行して、テスト HTTP 呼び出しを実行し、POST リクエストを送信します。

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

   Copy to Clipboard Toggle word wrap
4. 応答を検証して、ワークフローが期待どおりに機能していることを確認します。

手順

1. 次のコマンドを実行してワークフローのステータスを確認します。

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

   Copy to Clipboard Toggle word wrap

2. ワークフローのデプロイメントからログを取得して分析するには、次のコマンドを実行します。

   $ oc logs deployment/<workflow_name> -f

   Copy to Clipboard Toggle word wrap

手順

1. 削除するワークフローを定義する正しいファイルがあることを確認します。たとえば、workflow.yaml などです。

2. oc delete コマンドを実行して、指定した namespace からワークフローを削除します。

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

   Copy to Clipboard Toggle word wrap

   <your_file> は、ワークフローファイルの名前に、<your_namespace> を namespace に置き換えます。

手順

1. OpenAPI 関数を定義するには、以下を行います。

   1. 呼び出す予定のサービスの OpenAPI 仕様ファイルを識別してアクセスします。

   2. OpenAPI 仕様ファイルを、<project_application_dir>/specs などのワークフローサービスディレクトリーにコピーします。

      次の例は、乗算 REST サービスの OpenAPI 仕様を示しています。

      乗算 REST サービス OpenAPI 仕様の例

      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

      Copy to Clipboard Toggle word wrap

   3. ワークフローで関数を定義するには、OpenAPI 仕様の operationId を使用して、関数定義内の目的の操作を参照します。

      温度変換アプリケーションにおける関数定義の例

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

      Copy to Clipboard Toggle word wrap

   4. 関数定義が、<project_application_dir>/specs ディレクトリーに保存されている OpenAPI ファイルへの正しいパスを参照していることを確認します。

2. ワークフロー状態で定義された関数にアクセスします。

   1. 追加した関数定義を呼び出すワークフローアクションを定義します。各アクションが以前に定義された関数を参照していることを確認します。

   2. 特定の関数を名前で参照するには、functionRef 属性を使用します。OpenAPI 仕様で定義されたパラメーターを使用して、functionRef 内の引数をマップします。

      次の例は、リクエスト本文ではなくリクエストパス内のパラメーターのマッピングを示しています。次の PetStore API の例を参照できます。

      ワークフローで関数引数をマッピングする例

      {
         "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
            }
          }
        ]
      }

      Copy to Clipboard Toggle word wrap

   3. リクエスト内のパラメーターの構造化方法を理解するには、OpenAPI 仕様の Operation Object のセクションを確認してください。
   4. jq 式を使用してペイロードからデータを抽出し、必要なパラメーターにマップします。エンジンが OpenAPI 仕様に従ってパラメーター名をマッピングしていることを確認します。

   5. 本文ではなくリクエストパス内のパラメーターを必要とする操作については、OpenAPI 仕様のパラメーター定義を参照してください。

      リクエスト本文ではなくリクエストパスでパラメーターをマッピングする方法の詳細は、次の PetStore API の例を参照してください。

      パスパラメーターのマッピングの例

      {
        "/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"
                }
              }
            ]
          }
        }
      }

      Copy to Clipboard Toggle word wrap

      以下は関数の呼び出し例です。リクエストパスに petId という名前のパラメーターが 1 つだけ追加されています。

      PetStore 関数の呼び出し例

      {
        "name": "CallPetStore", 

      1

      
        "actionMode": "sequential",
        "type": "operation",
        "actions": [
          {
            "name": "getPet",
            "functionRef": {
              "refName": "getPetById", 

      2

      
              "arguments": { 

      3

      
                "petId": ".petId"
              }
            }
          }
        ]
      }

      Copy to Clipboard Toggle word wrap

      1

      CallPetStore などの状態定義。

      2

      関数定義リファレンス。前述の例では、関数定義 getPetById は PetStore OpenAPI 仕様用です。

      3

      引数の定義。OpenShift Serverless Logic は、リクエストを送信する前に、petId 引数をリクエストパスに追加します。

手順

1. 設定する OpenAPI 仕様ファイルを見つけます。例: substraction.yaml
2. . などの特殊文字をアンダースコアに置き換え、文字を小文字に変換して、ファイル名を有効な設定キーに変換します。たとえば、substraction.yaml を substraction_yaml に変更します。

3. 設定キーを定義するには、変換されたファイル名を REST クライアント設定キーとして使用します。次の例に示すように、このキーを環境変数として設定します。

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

   Copy to Clipboard Toggle word wrap

4. application.properties ファイルで URL がハードコーディングされるのを防ぐには、次の例に示すように、環境変数の置換を使用します。

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

   Copy to Clipboard Toggle word wrap

   この例では、以下が適用されます。

   • Configuration Key: quarkus.rest-client.subtraction_yaml.url
   • 環境変数: SUBTRACTION_URL
   • フォールバック URL: http://myserver.com
5. システムまたはデプロイメント環境で (SUBTRACTION_URL) 環境変数が設定されていることを確認します。変数が見つからない場合、アプリケーションはフォールバック URL (http://myserver.com) を使用します。

6. 設定キーと URL 置換を application.properties ファイルに追加します。

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

   Copy to Clipboard Toggle word wrap
7. アプリケーションをデプロイまたは再起動して、新しい設定を適用します。

手順

1. workflow-uri-definitions 拡張をワークフローに追加します。このエクステンション内で、URI のエイリアスを作成します。

   ワークフローの例

   {
     "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"
       }
     ]
   }

   Copy to Clipboard Toggle word wrap

手順

1. HTTP リクエストとレスポンスをトレースするために、OpenShift Serverless Logic は次のプロパティーを設定して Apache HTTP クライアントを使用します。

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

   Copy to Clipboard Toggle word wrap

2. Apache HTTP クライアントのデバッグを有効にするには、アプリケーションの application.properties ファイルに次の設定を追加します。

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

   Copy to Clipboard Toggle word wrap
3. ログ設定の変更を反映するには、アプリケーションを再起動します。

4. 再起動後、ログで HTTP リクエストトレースを確認します。

   トレースされた HTTP リクエストのログの例

   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

   Copy to Clipboard Toggle word wrap

5. リクエストログに続く HTTP レスポンストレースのログを確認します。

   トレースされた HTTP レスポンスのログの例

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

   Copy to Clipboard Toggle word wrap