Skip to content

Commit 67f0c94

Browse files
abrennan89abrennan89
authored
Merge pull request #37479 from abrennan89/SRVKE-837
SRVKE-837: BYO event source docs
2 parents d6587e5 + 4962673 commit 67f0c94

11 files changed

+377
-62
lines changed

‎_topic_map.yml‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3270,12 +3270,10 @@ Topics:
32703270
File: serverless-apiserversource
32713271
- Name: Using a ping source
32723272
File: serverless-pingsource
3273-
- Name: Using sink binding
3274-
File: serverless-sinkbinding
3275-
- Name: Using container sources
3276-
File: serverless-containersource
32773273
- Name: Using a Kafka source
32783274
File: serverless-kafka-source
3275+
- File: serverless-custom-event-sources
3276+
Name: Custom event sources
32793277
# Channels
32803278
- Name: Channels
32813279
Dir: channels

modules/serverless-containersource-custom-sources.adoc renamed to modules/serverless-containersource-guidelines.adoc

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,11 @@
1-
[id="serverless-containersource-custom-sources_{context}"]
2-
= Creating custom event sources by using a container source
3-
4-
You can use a container source to create and manage a container for your custom event source image.
5-
6-
To implement a custom event source by using a container source, you must first create a container image of your event source, and then create a container source that specifies the correct configuration, including the container image URI.
7-
8-
== Guidelines for creating a container image
9-
10-
* A container image can be developed using any language, and can be built and published with any tool that you prefer.
11-
12-
* The main process of the container image must accept parameters from arguments and environment variables.
1+
[id="serverless-containersource-guidelines_{context}"]
2+
= Guidelines for creating a container image
133

144
* Two environment variables are injected by the container source controller: `K_SINK` and `K_CE_OVERRIDES`. These variables are resolved from the `sink` and `ceOverrides` spec, respectively.
155

166
* Event messages are sent to the sink URI specified in the `K_SINK` environment variable. The event message can be in any format; however, using the link:https://cloudevents.io/[`CloudEvent`] spec is recommended.
177

8+
[id="serverless-containersource-guidelines-examples_{context}"]
189
== Example container images
1910

2011
The following is an example of a heartbeats container image:

‎modules/serverless-containersource-reference.adoc‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
[id="serverless-containersource-reference_{context}"]
2+
= Container source reference
3+
4+
This topic provides reference information about the configurable fields for the
5+
`ContainerSource` object.
6+
7+
`ContainerSource` objects support the following fields:
8+
9+
[cols=3*,options="header"]
10+
|===
11+
|Field
12+
|Description
13+
|Required or optional
14+
15+
|`apiVersion`
16+
|Specifies the API version, for example `sources.knative.dev/v1`.
17+
|Required
18+
19+
|`kind`
20+
|Identifies this resource object as a `ContainerSource` object.
21+
|Required
22+
23+
|`metadata`
24+
|Specifies metadata that uniquely identifies the `ContainerSource` object. For example, a `name`.
25+
|Required
26+
27+
|`spec`
28+
|Specifies the configuration information for this `ContainerSource` object.
29+
|Required
30+
31+
|`spec.sink`
32+
|A reference to an object that resolves to a URI to use as the sink.
33+
|Required
34+
35+
|`spec.template`
36+
|A `template` spec for the `ContainerSource` object.
37+
|Required
38+
39+
|`spec.ceOverrides`
40+
|Defines overrides to control the output format and modifications to the event sent to the sink.
41+
|Optional
42+
43+
|===
44+
45+
[id="serverless-containersource-reference-template-parameter-example_{context}"]
46+
== Template parameter example
47+
48+
[source,yaml]
49+
----
50+
apiVersion: sources.knative.dev/v1
51+
kind: ContainerSource
52+
metadata:
53+
name: test-heartbeats
54+
spec:
55+
template:
56+
spec:
57+
containers:
58+
- image: quay.io/openshift-knative/heartbeats:latest
59+
name: heartbeats
60+
args:
61+
- --period=1
62+
env:
63+
- name: POD_NAME
64+
value: "mypod"
65+
- name: POD_NAMESPACE
66+
value: "event-test"
67+
...
68+
----
69+
70+
[id="serverless-containersource-reference-cloudevent-overrides_{context}"]
71+
== CloudEvent overrides
72+
73+
A `ceOverrides` definition provides overrides that control the CloudEvent's output format and modifications sent to the sink
74+
75+
A `ceOverrides` definition supports the following fields:
76+
77+
[cols=3*,options="header"]
78+
|===
79+
|Field
80+
|Description
81+
|Required or optional
82+
83+
|`extensions`
84+
|Specifies which attributes are added or overridden on the outbound event. Each `extensions` key-value pair is set independently on the event as an attribute extension.
85+
|Optional
86+
87+
|===
88+
89+
[NOTE]
90+
====
91+
Only valid `CloudEvent` attribute names are allowed as extensions. You cannot set the spec defined attributes from the extensions override configuration. For example, you can not modify the `type` attribute.
92+
====
93+
94+
.CloudEvent Overrides example
95+
[source,yaml]
96+
----
97+
apiVersion: sources.knative.dev/v1
98+
kind: ContainerSource
99+
metadata:
100+
name: test-heartbeats
101+
spec:
102+
...
103+
ceOverrides:
104+
extensions:
105+
extra: this is an extra attribute
106+
additional: 42
107+
----
108+
109+
This sets the `K_CE_OVERRIDES` environment variable on the `subject`:
110+
111+
.Example output
112+
[source,terminal]
113+
----
114+
{ "extensions": { "extra": "this is an extra attribute", "additional": "42" } }
115+
----

‎modules/serverless-sinkbinding-intro.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[id="serverless-sinkbinding-intro_context"]
2+
= Using a sink binding
3+
4+
The `SinkBinding` object supports decoupling event production from delivery addressing. Sink binding is used to connect _event producers_ to an event consumer, or _sink_. An event producer is a Kubernetes resource that embeds a `PodSpec` template and produces events. A sink is an addressable Kubernetes object that can receive events.
5+
6+
The `SinkBinding` object injects environment variables into the `PodTemplateSpec` of the sink, which means that the application code does not need to interact directly with the Kubernetes API to locate the event destination. These environment variables are as follows:
7+
8+
`K_SINK`:: The URL of the resolved sink.
9+
`K_CE_OVERRIDES`:: A JSON object that specifies overrides to the outbound event.

‎modules/serverless-sinkbinding-odc.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[id="serverless-sinkbinding-odc_{context}"]
2-
= Creating a sink binding using the Developer perspective
2+
= Creating a sink binding using the web console
33

44
You can create and verify a basic sink binding from the {product-title} web console.
55

‎modules/serverless-sinkbinding-reference.adoc‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
[id="serverless-sinkbinding-reference_{context}"]
2+
= Sink binding reference
3+
4+
This topic provides reference information about the configurable parameters for `SinkBinding` objects.
5+
6+
`SinkBinding` objects support the following parameters:
7+
8+
[cols=3*,options="header"]
9+
|===
10+
|Field
11+
|Description
12+
|Required or optional
13+
14+
|`apiVersion`
15+
|Specifies the API version, for example `sources.knative.dev/v1`.
16+
|Required
17+
18+
|`kind`
19+
|Identifies this resource object as a `SinkBinding` object.
20+
|Required
21+
22+
|`metadata`
23+
|Specifies metadata that uniquely identifies the `SinkBinding` object. For example, a `name`.
24+
|Required
25+
26+
|`spec`
27+
|Specifies the configuration information for this `SinkBinding` object.
28+
|Required
29+
30+
|`spec.sink`
31+
|A reference to an object that resolves to a URI to use as the sink.
32+
|Required
33+
34+
|`spec.subject`
35+
|References the resources for which the runtime contract is augmented by binding implementations.
36+
|Required
37+
38+
|`spec.ceOverrides`
39+
|Defines overrides to control the output format and modifications to the event sent to the sink.
40+
|Optional
41+
42+
|===
43+
44+
[id="serverless-sinkbinding-reference-subject-parameters_{context}"]
45+
== Subject parameter
46+
47+
The `Subject` parameter references the resources for which the runtime contract is augmented by binding implementations.
48+
49+
The `Subject` definition supports the following fields:
50+
51+
[cols=3*,options="header"]
52+
|===
53+
|Field
54+
|Description
55+
|Required or optional
56+
57+
|`apiVersion`
58+
|API version of the referent.
59+
|Required
60+
61+
|`kind`
62+
|Kind of the referent.
63+
|Required
64+
65+
|`namespace`
66+
|Namespace of the referent. If omitted, this defaults to the namespace of the object.
67+
|Optional
68+
69+
|`name`
70+
|Name of the referent.
71+
|Do not use if you configure `selector`.
72+
73+
|`selector`
74+
|Selector of the referents.
75+
|Do not use if you configure `name`.
76+
77+
|`selector.matchExpressions`
78+
|A list of label selector requirements.
79+
|Only use one of either `matchExpressions` or `matchLabels`.
80+
81+
|`selector.matchExpressions.key`
82+
|The label key that the selector applies to.
83+
|Required if using `matchExpressions`.
84+
85+
|`selector.matchExpressions.operator`
86+
|Represents a key's relationship to a set of values. Valid operators are `In`, `NotIn`, `Exists` and `DoesNotExist`.
87+
|Required if using `matchExpressions`.
88+
89+
|`selector.matchExpressions.values`
90+
|An array of string values. If the `operator` parameter value is `In` or `NotIn`, the values array must be non-empty. If the `operator` parameter value is `Exists` or `DoesNotExist`, the values array must be empty. This array is replaced during a strategic merge patch.
91+
|Required if using `matchExpressions`.
92+
93+
|`selector.matchLabels`
94+
|A map of key-value pairs. Each key-value pair in the `matchLabels` map is equivalent to an element of `matchExpressions`, where the key field is `matchLabels.<key>`, the `operator` is `In`, and the `values` array contains only `matchLabels.<value>`.
95+
|Only use one of either `matchExpressions` or `matchLabels`.
96+
97+
|===
98+
99+
[id="serverless-sinkbinding-reference-subject-parameter-examples_{context}"]
100+
=== Subject parameter examples
101+
102+
Given the following YAML, the `Deployment` object named `mysubject` in the `default` namespace is selected:
103+
104+
[source,yaml]
105+
----
106+
apiVersion: sources.knative.dev/v1
107+
kind: SinkBinding
108+
metadata:
109+
name: bind-heartbeat
110+
spec:
111+
subject:
112+
apiVersion: apps/v1
113+
kind: Deployment
114+
namespace: default
115+
name: mysubject
116+
...
117+
----
118+
119+
Given the following YAML, any `Job` object with the label `working=example` in the `default` namespace is selected:
120+
121+
[source,yaml]
122+
----
123+
apiVersion: sources.knative.dev/v1
124+
kind: SinkBinding
125+
metadata:
126+
name: bind-heartbeat
127+
spec:
128+
subject:
129+
apiVersion: batch/v1
130+
kind: Job
131+
namespace: default
132+
selector:
133+
matchLabels:
134+
working: example
135+
...
136+
----
137+
138+
Given the following YAML, any `Pod` object with the label `working=example` or `working=sample` in the `default` namespace is selected:
139+
140+
[source,yaml]
141+
----
142+
apiVersion: sources.knative.dev/v1
143+
kind: SinkBinding
144+
metadata:
145+
name: bind-heartbeat
146+
spec:
147+
subject:
148+
apiVersion: v1
149+
kind: Pod
150+
namespace: default
151+
selector:
152+
- matchExpression:
153+
key: working
154+
operator: In
155+
values:
156+
- example
157+
- sample
158+
...
159+
----
160+
161+
[id="serverless-sinkbinding-reference-cloudevent-overrides_{context}"]
162+
== CloudEvent overrides
163+
164+
A `ceOverrides` definition provides overrides that control the CloudEvent's output format and modifications sent to the sink
165+
166+
A `ceOverrides` definition supports the following fields:
167+
168+
[cols=3*,options="header"]
169+
|===
170+
|Field
171+
|Description
172+
|Required or optional
173+
174+
|`extensions`
175+
|Specifies which attributes are added or overridden on the outbound event. Each `extensions` key-value pair is set independently on the event as an attribute extension.
176+
|Optional
177+
178+
|===
179+
180+
[NOTE]
181+
====
182+
Only valid `CloudEvent` attribute names are allowed as extensions. You cannot set the spec defined attributes from the extensions override configuration. For example, you can not modify the `type` attribute.
183+
====
184+
185+
.CloudEvent Overrides example
186+
[source,yaml]
187+
----
188+
apiVersion: sources.knative.dev/v1
189+
kind: SinkBinding
190+
metadata:
191+
name: bind-heartbeat
192+
spec:
193+
...
194+
ceOverrides:
195+
extensions:
196+
extra: this is an extra attribute
197+
additional: 42
198+
----
199+
200+
This sets the `K_CE_OVERRIDES` environment variable on the `subject`:
201+
202+
.Example output
203+
[source,terminal]
204+
----
205+
{ "extensions": { "extra": "this is an extra attribute", "additional": "42" } }
206+
----

‎modules/serverless-sinkbinding-yaml.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// Module included in the following assemblies:
22
//
3-
// * serverless/event_sources/serverless-sinkbinding.adoc
3+
// * serverless/event_sources/custom-event-sources.adoc
44

55
[id="serverless-sinkbinding-yaml_{context}"]
66
= Using sink binding with the YAML method

‎serverless/event_sources/knative-event-sources.adoc‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,6 @@ xref:../../serverless/event_sources/serverless-apiserversource.adoc#serverless-a
1616

1717
xref:../../serverless/event_sources/serverless-pingsource.adoc#serverless-pingsource[Ping source]:: Produces events with a fixed payload on a specified cron schedule.
1818

19-
xref:../../serverless/event_sources/serverless-sinkbinding.adoc#serverless-sinkbinding[Sink binding]:: Connects core Kubernetes resource objects, such as `Deployment`, `Job`, or `StatefulSet` objects, with a sink.
20-
21-
xref:../../serverless/event_sources/serverless-containersource.adoc#serverless-containersource[Container source]:: Starts a container image that generates cloud events and sends them to a sink. Container sources can also be used to support your own custom event sources in Knative.
22-
2319
xref:../../serverless/event_sources/serverless-kafka-source.adoc#serverless-kafka-source[Kafka source]:: Connects a Kafka cluster to a sink as an event source.
20+
21+
You can also create a xref:../../serverless/event_sources/serverless-custom-event-sources.adoc#serverless-custom-event-sources[custom event source].

0 commit comments

Comments
 (0)