From 23bcbd9a932d0b0b95540a7a630c08c75851704c Mon Sep 17 00:00:00 2001 From: Matt Moore Date: Fri, 29 Nov 2019 17:01:18 -0800 Subject: [PATCH 1/3] Add a SinkBinding sample. This is largely derived from the ContainerSource docs, but using SinkBinding and a CronJob. --- docs/eventing/samples/sinkbinding/README.md | 216 ++++++++++++++++++ .../sinkbinding/heartbeats-source.yaml | 34 +++ .../eventing/samples/sinkbinding/service.yaml | 23 ++ .../samples/sinkbinding/sinkbinding.yaml | 17 ++ 4 files changed, 290 insertions(+) create mode 100644 docs/eventing/samples/sinkbinding/README.md create mode 100644 docs/eventing/samples/sinkbinding/heartbeats-source.yaml create mode 100644 docs/eventing/samples/sinkbinding/service.yaml create mode 100644 docs/eventing/samples/sinkbinding/sinkbinding.yaml diff --git a/docs/eventing/samples/sinkbinding/README.md b/docs/eventing/samples/sinkbinding/README.md new file mode 100644 index 00000000000..ba98c597472 --- /dev/null +++ b/docs/eventing/samples/sinkbinding/README.md @@ -0,0 +1,216 @@ +--- +title: "Sink Binding Example" +linkTitle: "Sink Binding" +weight: 10 +type: "docs" +--- + +A SinkBinding is responsible for linking together "addressable" Kubernetes +resources that may receive events (aka the event "sink") with Kubernetes +resources that embed a PodSpec (as `spec.template.spec`) and want to produce +events. + +The SinkBinding can be used to author new event sources using any of the +familiar compute abstractions that Kubernetes makes available (e.g. Deployment, +Job, DaemonSet, StatefulSet), or Knative abstractions (e.g. Service, +Configuration). + + +## Create a CronJob that uses SinkBinding + +### Prerequisites + +1. Setup [Knative Serving](../../../serving). +1. Setup [Knative Eventing and Sources](../../../eventing). + +### Prepare the heartbeats image + +Knative [event-sources](https://github.com/knative/eventing-contrib) has a +sample of heartbeats event source. You could clone the source codes by + +``` +git clone -b "{{< branch >}}" https://github.com/knative/eventing-contrib.git +``` + +And then build a heartbeats image and publish to your image repo with + +``` +ko publish knative.dev/eventing-contrib/cmd/heartbeats +``` + +**Note**: `ko publish` requires: + +- [`KO_DOCKER_REPO`](https://github.com/knative/serving/blob/master/DEVELOPMENT.md#environment-setup) + to be set. (e.g. `gcr.io/[gcloud-project]` or `docker.io/`) +- you to be authenticated with your `KO_DOCKER_REPO` + +### Creating our event sink + +In order to verify our `SinkBinding` is working, we will create an Event Display +Service that dumps incoming messages to its log. + +```yaml +apiVersion: serving.knative.dev/v1 +kind: Service +metadata: + name: event-display +spec: + template: + spec: + containers: + - image: gcr.io/knative-releases/github.com/knative/eventing-sources/cmd/event_display +``` + +Use following command to create the service from `service.yaml`: + +```shell +kubectl apply --filename service.yaml +``` + +The status of the created service can be seen using: + +```shell +kubectl get ksvc + +NAME URL LATESTCREATED LATESTREADY READY REASON +event-display http://event-display.default.1.2.3.4.xip.io event-display-gqjbw event-display-gqjbw True +``` + +### Create our SinkBinding + +In order to direct events to our Event Display, we will first create a +SinkBinding that will inject `$K_SINK` into select `Jobs`: + +```yaml +apiVersion: sources.eventing.knative.dev/v1alpha1 +kind: SinkBinding +metadata: + name: bind-heartbeat +spec: + subject: + apiVersion: batch/v1 + kind: Job + selector: + matchLabels: + app: heartbeat-cron + + sink: + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: event-display +``` + +In this case, we will bind any `Job` with the labels `app: heartbeat-cron`. + +Use the following command to create the event source from `sinkbinding.yaml`: + +```shell +kubectl apply --filename sinkbinding.yaml +``` + +### Create our CronJob + +Now we will use the heartbeats container to send events to `$K_SINK` every time +the CronJob runs: + +```yaml +apiVersion: batch/v1beta1 +kind: CronJob +metadata: + name: heartbeat-cron +spec: +spec: + # Run every minute + schedule: "* * * * *" + jobTemplate: + metadata: + labels: + app: heartbeat-cron + spec: + template: + spec: + restartPolicy: Never + containers: + - name: single-heartbeat + image: + args: + - --period=1 + env: + - name: ONE_SHOT + value: "true" + - name: POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + - name: POD_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace +``` + +First, edit `heartbeats-source.yaml` to include the image name from the +`ko publish` command above, then run the following to apply it: + +```shell +kubectl apply --filename heartbeats-source.yaml +``` + +### Verify + +We will verify that the message was sent to the Knative eventing system by +looking at event-display service logs. + +```shell +kubectl logs -l serving.knative.dev/service=event-display -c user-container --since=10m +``` + +You should see log lines showing the request headers and body of the event +message sent by the heartbeats source to the display function: + +``` +☁️ cloudevents.Event +Validation: valid +Context Attributes, + specversion: 0.3 + type: dev.knative.eventing.samples.heartbeat + source: https://knative.dev/eventing-contrib/cmd/heartbeats/#event-test/mypod + id: 2b72d7bf-c38f-4a98-a433-608fbcdd2596 + time: 2019-10-18T15:23:20.809775386Z + contenttype: application/json +Extensions, + beats: true + heart: yes + the: 42 +Data, + { + "id": 2, + "label": "" + } +``` + +## Using the SinkBinding with a Knative Service + +SinkBinding is also compatible with our Knative Serving Cloud Events +[samples](../../../serving/samples/cloudevents); as a next step try using those +together. For example, the [`cloudevents-go` +sample](../../../serving/samples/cloudevents/cloudevents-go) may be bound with: + +```yaml +apiVersion: sources.eventing.knative.dev/v1alpha1 +kind: SinkBinding +metadata: + name: bind-heartbeat +spec: + subject: + apiVersion: serving.knative.dev/v1 + kind: Service + name: cloudevents-go + + sink: + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: event-display +``` + diff --git a/docs/eventing/samples/sinkbinding/heartbeats-source.yaml b/docs/eventing/samples/sinkbinding/heartbeats-source.yaml new file mode 100644 index 00000000000..67fe95f8092 --- /dev/null +++ b/docs/eventing/samples/sinkbinding/heartbeats-source.yaml @@ -0,0 +1,34 @@ +apiVersion: batch/v1beta1 +kind: CronJob +metadata: + name: heartbeat-cron +spec: +spec: + # Run every minute + schedule: "* * * * *" + jobTemplate: + metadata: + labels: + app: heartbeat-cron + spec: + template: + spec: + restartPolicy: Never + containers: + # This corresponds to a heartbeats image uri you build and publish, + # e.g. gcr.io/[gcloud-project]/github.com/knative/eventing-contrib/cmd/heartbeats + - name: single-heartbeat + image: knative.dev/eventing-contrib/cmd/heartbeats + args: + - --period=1 + env: + - name: ONE_SHOT + value: "true" + - name: POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + - name: POD_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace diff --git a/docs/eventing/samples/sinkbinding/service.yaml b/docs/eventing/samples/sinkbinding/service.yaml new file mode 100644 index 00000000000..41ef37925c2 --- /dev/null +++ b/docs/eventing/samples/sinkbinding/service.yaml @@ -0,0 +1,23 @@ +# Copyright 2019 The Knative Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +apiVersion: serving.knative.dev/v1 +kind: Service +metadata: + name: event-display +spec: + template: + spec: + containers: + - image: gcr.io/knative-releases/github.com/knative/eventing-sources/cmd/event_display diff --git a/docs/eventing/samples/sinkbinding/sinkbinding.yaml b/docs/eventing/samples/sinkbinding/sinkbinding.yaml new file mode 100644 index 00000000000..ece59ea4d63 --- /dev/null +++ b/docs/eventing/samples/sinkbinding/sinkbinding.yaml @@ -0,0 +1,17 @@ +apiVersion: sources.eventing.knative.dev/v1alpha1 +kind: SinkBinding +metadata: + name: bind-heartbeat +spec: + subject: + apiVersion: batch/v1 + kind: Job + selector: + matchLabels: + app: heartbeat-cron + + sink: + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: event-display From 6341fb388a560e15697a91a6ecfa6f148c2d29d5 Mon Sep 17 00:00:00 2001 From: Matt Moore Date: Mon, 2 Dec 2019 09:38:55 -0800 Subject: [PATCH 2/3] Fix the eventing-sources reference. --- docs/eventing/samples/sinkbinding/README.md | 4 ++-- docs/eventing/samples/sinkbinding/service.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/eventing/samples/sinkbinding/README.md b/docs/eventing/samples/sinkbinding/README.md index ba98c597472..7e0c8b52f45 100644 --- a/docs/eventing/samples/sinkbinding/README.md +++ b/docs/eventing/samples/sinkbinding/README.md @@ -25,7 +25,7 @@ Configuration). ### Prepare the heartbeats image -Knative [event-sources](https://github.com/knative/eventing-contrib) has a +Knative [event-contrib](https://github.com/knative/eventing-contrib) has a sample of heartbeats event source. You could clone the source codes by ``` @@ -58,7 +58,7 @@ spec: template: spec: containers: - - image: gcr.io/knative-releases/github.com/knative/eventing-sources/cmd/event_display + - image: gcr.io/knative-releases/github.com/knative/eventing-contrib/cmd/event_display ``` Use following command to create the service from `service.yaml`: diff --git a/docs/eventing/samples/sinkbinding/service.yaml b/docs/eventing/samples/sinkbinding/service.yaml index 41ef37925c2..eda67856546 100644 --- a/docs/eventing/samples/sinkbinding/service.yaml +++ b/docs/eventing/samples/sinkbinding/service.yaml @@ -20,4 +20,4 @@ spec: template: spec: containers: - - image: gcr.io/knative-releases/github.com/knative/eventing-sources/cmd/event_display + - image: gcr.io/knative-releases/github.com/knative/eventing-contrib/cmd/event_display From 503c9638f5b11a7281dd5707c5cef4f5c87c469d Mon Sep 17 00:00:00 2001 From: Matt Moore Date: Mon, 2 Dec 2019 09:56:54 -0800 Subject: [PATCH 3/3] Add licenses --- .../samples/sinkbinding/heartbeats-source.yaml | 14 ++++++++++++++ docs/eventing/samples/sinkbinding/sinkbinding.yaml | 14 ++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/docs/eventing/samples/sinkbinding/heartbeats-source.yaml b/docs/eventing/samples/sinkbinding/heartbeats-source.yaml index 67fe95f8092..d7d25048321 100644 --- a/docs/eventing/samples/sinkbinding/heartbeats-source.yaml +++ b/docs/eventing/samples/sinkbinding/heartbeats-source.yaml @@ -1,3 +1,17 @@ +# Copyright 2019 The Knative Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + apiVersion: batch/v1beta1 kind: CronJob metadata: diff --git a/docs/eventing/samples/sinkbinding/sinkbinding.yaml b/docs/eventing/samples/sinkbinding/sinkbinding.yaml index ece59ea4d63..425e34e0940 100644 --- a/docs/eventing/samples/sinkbinding/sinkbinding.yaml +++ b/docs/eventing/samples/sinkbinding/sinkbinding.yaml @@ -1,3 +1,17 @@ +# Copyright 2019 The Knative Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + apiVersion: sources.eventing.knative.dev/v1alpha1 kind: SinkBinding metadata: