Skip to content

Commit dceed13

Browse files
jeana-redhatjeana-redhat
authored
Merge pull request #75129 from kaldesai/SRVLOGIC-209-OSL-overview
PR for SRVLOGIC-209: Add the "Openshift Serverless Logic overview" assembly.
2 parents abed6ce + 7f933fb commit dceed13

10 files changed

+715
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ Topics:
1313
File: about-knative-eventing
1414
- Name: OpenShift Serverless Functions overview
1515
File: serverless-functions-about
16+
- Name: OpenShift Serverless Logic overview
17+
File: serverless-logic-overview
1618
# Support
1719
- Name: OpenShift Serverless support
1820
File: serverless-support

‎about/serverless-logic-overview.adoc

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
:_content-type: ASSEMBLY
2+
include::_attributes/common-attributes.adoc[]
3+
[id="serverless-logic-overview"]
4+
= OpenShift Serverless Logic overview
5+
:context: serverless-logic-overview
6+
7+
toc::[]
8+
9+
OpenShift Serverless Logic enables developers to define declarative workflow models that orchestrate event-driven, serverless applications.
10+
11+
You can write the workflow models in YAML or JSON format, which are ideal for developing and deploying serverless applications in cloud or container environments.
12+
13+
To deploy the workflows in your {ocp-product-title}, you can use the OpenShift Serverless Logic Operator.
14+
15+
// Add additional resources if any
16+
17+
The following sections provide an overview of the various OpenShift Serverless Logic concepts.
18+
19+
// modules present in this assembly
20+
21+
include::modules/serverless-logic-overview-events.adoc[leveloffset=+1]
22+
include::modules/serverless-logic-overview-callbacks.adoc[leveloffset=+1]
23+
include::modules/serverless-logic-overview-jq-expressions.adoc[leveloffset=+1]
24+
include::modules/serverless-logic-overview-error-handling.adoc[leveloffset=+1]
25+
include::modules/serverless-logic-overview-input-output-schema.adoc[leveloffset=+1]
26+
include::modules/serverless-logic-overview-custom-functions.adoc[leveloffset=+1]
27+
include::modules/serverless-logic-overview-timeouts.adoc[leveloffset=+1]
28+
include::modules/serverless-logic-overview-parallelism.adoc[leveloffset=+1]

‎modules/serverless-logic-overview-callbacks.adoc

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
// Module included in the following assemblies:
2+
// * about/serverless-logic-overview.adoc
3+
4+
5+
:_content-type: CONCEPT
6+
[id="serverless-logic-overview-callbacks_{context}"]
7+
= Callbacks
8+
9+
The Callback state performs an action and waits for an event that is produced as a result of the action before resuming the workflow. The action performed by a Callback state is an asynchronous external service invocation. Therefore, the Callback state is suitable to perform `fire&wait-for-result` operations.
10+
11+
From a workflow perspective, asynchronous service indicates that the control is returned to the caller immediately without waiting for the action to be completed. After the action is completed, a `CloudEvent` is published to resume the workflow.
12+
13+
.Example of Callback state in JSON format
14+
[source,json]
15+
----
16+
{
17+
"name": "CheckCredit",
18+
"type": "callback",
19+
"action": {
20+
"functionRef": {
21+
"refName": "callCreditCheckMicroservice",
22+
"arguments": {
23+
"customer": "${ .customer }"
24+
}
25+
}
26+
},
27+
"eventRef": "CreditCheckCompletedEvent",
28+
"timeouts": {
29+
"stateExecTimeout": "PT15M"
30+
},
31+
"transition": "EvaluateDecision"
32+
}
33+
----
34+
35+
.Example of Callback state in YAML format
36+
[source,yaml]
37+
----
38+
name: CheckCredit
39+
type: callback
40+
action:
41+
functionRef:
42+
refName: callCreditCheckMicroservice
43+
arguments:
44+
customer: "${ .customer }"
45+
eventRef: CreditCheckCompletedEvent
46+
timeouts:
47+
stateExecTimeout: PT15M
48+
transition: EvaluateDecision
49+
----
50+
51+
The `action` property defines a function call that triggers an external activity or service. After the action executes, the Callback state waits for a `CloudEvent`, which indicates the completion of the manual decision by the called service.
52+
53+
After the completion callback event is received, the Callback state completes its execution and transitions to the next defined workflow state or completes workflow execution if it is an end state.

‎modules/serverless-logic-overview-custom-functions.adoc

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
// Module included in the following assemblies:
2+
// * about/serverless-logic-overview.adoc
3+
4+
5+
:_content-type: CONCEPT
6+
[id="serverless-logic-overview-custom-functions_{context}"]
7+
= Custom functions
8+
9+
OpenShift Serverless Logic supports the `custom` function type, which enables the implementation to extend the function definitions capability. By combining with the `operation` string, you can use a list of predefined function types.
10+
11+
[NOTE]
12+
====
13+
Custom function types might not be portable across other runtime implementations.
14+
====
15+
16+
[id="sysout-custom-function_{context}"]
17+
== Sysout custom function
18+
19+
You can use the `sysout` function for logging, as shown in the following example:
20+
21+
.Example of `sysout` function definition
22+
[source,json]
23+
----
24+
{
25+
"functions": [
26+
{
27+
"name": "logInfo",
28+
"type": "custom",
29+
"operation": "sysout:INFO"
30+
}
31+
]
32+
}
33+
----
34+
35+
The string after the `:` is optional and is used to indicate the log level. The possible values are `TRACE`, `DEBUG`, `INFO`, `WARN`, and `ERROR`. If the value is not present, `INFO` is the default.
36+
37+
In the `state` definition, you can call the same `sysout` function as shown in the following example:
38+
39+
.Example of a `sysout` function reference within a state
40+
[source,json]
41+
----
42+
{
43+
"states": [
44+
{
45+
"name": "myState",
46+
"type": "operation",
47+
"actions": [
48+
{
49+
"name": "printAction",
50+
"functionRef": {
51+
"refName": "logInfo",
52+
"arguments": {
53+
"message": "\"Workflow model is \\(.)\""
54+
}
55+
}
56+
}
57+
]
58+
}
59+
]
60+
}
61+
----
62+
63+
In the previous example, the `message` argument can be a jq expression or a jq string using interpolation.
64+
65+
[id="java-custom-function_{context}"]
66+
== Java custom function
67+
68+
OpenShift Serverless Logic supports the `java` functions within an Apache Maven project, in which you define your workflow service.
69+
70+
The following example shows the declaration of a `java` function:
71+
72+
.Example of a `java` function declaration
73+
[source,json]
74+
----
75+
{
76+
"functions": [
77+
{
78+
"name": "myFunction", <1>
79+
"type": "custom", <2>
80+
"operation": "service:java:com.acme.MyInterfaceOrClass::myMethod" <3>
81+
}
82+
]
83+
}
84+
----
85+
86+
<1> `myFunction` is the function name.
87+
<2> `custom` is the function type.
88+
<3> `service:java:com.acme.MyInterfaceOrClass::myMethod` is the custom operation definition. In the custom operation definition, `service` is the reserved operation keyword, followed by the `java` keyword. `com.acme.MyInterfaceOrClass` is the FQCN (Fully Qualified Class Name) of the interface or implementation class, followed by the method name `myMethod`.
89+
90+
//[id="camel-custom-function_{context}"] (I have commented out this section, as we have discussed with the Dev team to add this post-release)
91+
//== Camel custom function
92+
//OpenShift Serverless Logic supports the Camel Routes functions within an Apache Maven project, in which you define your workflow service.
93+
//The following example shows the declaration of a `Camel` function:
94+
95+
//.Example of a `Camel` function declaration
96+
//[source,json]
97+
//----
98+
//{
99+
// "functions": [
100+
// {
101+
// "name": "myCamelEndpoint", <1>
102+
// "type": "custom", <2>
103+
// "operation": "camel:direct:myendpoint" <3>
104+
// }
105+
// ]
106+
//}
107+
//----
108+
109+
//<1> `myCamelEndpoint` is the function name.
110+
//<2> `custom` is the function type.
111+
//<3> `camel:direct:myendpoint` is the custom operation definition. In this definition, `camel` is the reserved keyword followed by the direct endpoint, and `myendpoint` is the endpoint URI name found in the route within your project.
112+
113+
[id="knative-custom-function_{context}"]
114+
== Knative custom function
115+
116+
OpenShift Serverless Logic provides an implementation of a custom function through the `knative-serving` add-on to invoke Knative services. It allows you to have a static URI, defining a Knative service, that is used to perform HTTP requests. The Knative service defined in the URI is queried in the current Knative cluster and translated to a valid URL.
117+
118+
The following example uses a deployed Knative service:
119+
120+
[source,bash]
121+
----
122+
$ kn service list
123+
NAME URL LATEST AGE CONDITIONS READY REASON
124+
custom-function-knative-service http://custom-function-knative-service.default.10.109.169.193.sslip.io custom-function-knative-service-00001 3h16m 3 OK / 3 True
125+
----
126+
127+
You can declare a OpenShift Serverless Logic custom function using the Knative service name, as shown in the following example:
128+
[source,json]
129+
----
130+
"functions": [
131+
{
132+
"name": "greet", <1>
133+
"type": "custom", <2>
134+
"operation": "knative:services.v1.serving.knative.dev/custom-function-knative-service?path=/plainJsonFunction", <3>
135+
}
136+
]
137+
----
138+
139+
<1> `greet` is the function name.
140+
<2> `custom` is the function type.
141+
<3> In `operation`, you set the coordinates of the Knative service.
142+
143+
[NOTE]
144+
====
145+
This function sends a `POST` request. If you do not specify a path, OpenShift Serverless Logic uses the root path (/). You can also send `GET` requests by setting `method=GET` in the operation. In this case, the arguments are forwarded over a query string.
146+
====
147+
148+
[id="rest-custom-function_{context}"]
149+
== REST custom function
150+
151+
OpenShift Serverless Logic offers the `REST` custom type as a shortcut. When using custom rest, in the function definition, you specify the HTTP URI to be invoked and the HTTP method (get, post, patch, or put) to be used. This is done by using the `operation` string. When the function is invoked, you pass the request arguments as you do when using an OpenAPI function.
152+
153+
The following example shows the declaration of a `rest` function:
154+
155+
[source,json]
156+
----
157+
{
158+
"functions": [
159+
{
160+
"name": "multiplyAllByAndSum", <1>
161+
"type": "custom", <2>
162+
"operation": "rest:post:/numbers/{multiplier}/multiplyByAndSum" <3>
163+
}
164+
]
165+
}
166+
----
167+
168+
<1> `multiplyAllAndSum` is the function name.
169+
<2> `custom` is the function type.
170+
<3> `rest:post:/numbers/{multiplier}/multiplyByAndSum` is the custom operation definition. In the custom operation definition, `rest` is the reserved operation keyword that indicates this is a REST call, `post` is the HTTP method, and `/numbers/{multiplier}/multiplyByAndSum` is the relative endpoint.
171+
172+
When using the relative endpoints, you must specify the host as a property. The format of the host property is `kogito.sw.functions.<function_name>`.host. In this example, `kogito.sw.functions.multiplyAllByAndSum.host` is the host property key. You can override the default port (80) if needed by specifying the `kogito.sw.functions.multiplyAllAndSum.port` property.
173+
174+
This endpoint expects as body a JSON object whose field `numbers` is an array of integers, multiplies each item in the array by `multiplier` and returns the sum of all the multiplied items.

‎modules/serverless-logic-overview-error-handling.adoc

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Module included in the following assemblies:
2+
// * about/serverless-logic-overview.adoc
3+
4+
5+
:_content-type: CONCEPT
6+
[id="serverless-logic-overview-error-handling_{context}"]
7+
= Error handling
8+
9+
OpenShift Serverless Logic allows you to define `explicit` error handling. You can define inside of your workflow model what should happen if errors occur rather than some generic error handling entity. Explicit error handling enables you to handle the errors that might happen during the interactions between the workflow and external systems. When an error occurs, it changes the regular workflow sequence. In these cases, a workflow state transitions to an alternative state that can potentially handle the error, instead of transitioning to the predefined state.
10+
11+
Each workflow state can define error handling, which is related only to errors that might arise during its execution. Error handling defined in one state cannot be used to handle errors that happened during execution of another state during workflow execution.
12+
13+
Unknown errors that may arise during workflow state execution that are not explicitly handled within the workflow definition should be reported by runtime implementations and halt workflow execution.
14+
15+
[id="error-definition_{context}"]
16+
== Error definition
17+
18+
An error definition in a workflow is composed of the `name` and `code` parameters. The `name` is a short and natural language description of an error, such as `wrong parameter`. The `code` parameter helps the implementation to identify the error.
19+
20+
The `code` parameter is mandatory and the engine uses different strategies to map the provided value to an exception encountered at runtime. The available strategies include FQCN, error message, and status code.
21+
22+
During workflow execution, you must handle the the known workflow errors in the workflow top-level `errors` property. This property can be either a `string` type, meaning it can reference a reusable `JSON` or `YAML` definition file including the error definitions, or it can have an `array` type where you can define these checked errors inline in your workflow definition.
23+
24+
The following examples show definitions for both types:
25+
26+
.Example of referencing a reusable JSON error definition file
27+
[source,json]
28+
----
29+
{
30+
"errors": "file://documents/reusable/errors.json"
31+
}
32+
----
33+
34+
.Example of referencing a reusable YAML error definition file
35+
[source,yaml]
36+
----
37+
errors: file://documents/reusable/errors.json
38+
----
39+
40+
.Example of defining workflow errors inline using a JSON file
41+
[source,json]
42+
----
43+
{
44+
"errors": [
45+
{
46+
"name": "Service not found error",
47+
"code": "404",
48+
"description": "Server has not found anything matching the provided service endpoint information"
49+
}
50+
]
51+
}
52+
----
53+
54+
.Example of defining workflow errors inline using a YAML file
55+
[source,yaml]
56+
----
57+
errors:
58+
- name: Service not found error
59+
code: '404'
60+
description: Server has not found anything matching the provided service endpoint
61+
information
62+
----

0 commit comments

Comments
 (0)