From 3c71c5c779c14aee0df37eb402b5ec7ec0f61319 Mon Sep 17 00:00:00 2001 From: Matthias Wessendorf Date: Thu, 5 Mar 2020 18:24:09 +0100 Subject: [PATCH 1/5] some first migration --- docs/eventing/migration/README.md | 2 ++ docs/eventing/migration/_index.md | 8 ++++++ docs/eventing/migration/ping.md | 48 +++++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+) create mode 100644 docs/eventing/migration/README.md create mode 100644 docs/eventing/migration/_index.md create mode 100644 docs/eventing/migration/ping.md diff --git a/docs/eventing/migration/README.md b/docs/eventing/migration/README.md new file mode 100644 index 00000000000..fd397f19fad --- /dev/null +++ b/docs/eventing/migration/README.md @@ -0,0 +1,2 @@ +Knative Eventing in version 0.13 does deprecate a few resources. This document provides a collection of migration examples: +* [PingSource](./ping.md) migration from `CronJobSource`. diff --git a/docs/eventing/migration/_index.md b/docs/eventing/migration/_index.md new file mode 100644 index 00000000000..0b7e8ad2b15 --- /dev/null +++ b/docs/eventing/migration/_index.md @@ -0,0 +1,8 @@ +--- +title: "Migration" +linkTitle: "Migration" +weight: 31 +type: "docs" +--- + +{{% readfile file="README.md" %}} diff --git a/docs/eventing/migration/ping.md b/docs/eventing/migration/ping.md new file mode 100644 index 00000000000..56c57f33eb9 --- /dev/null +++ b/docs/eventing/migration/ping.md @@ -0,0 +1,48 @@ +--- +title: "Migrating to the PingSource" +weight: 20 +type: "docs" +aliases: + - /docs/eventing/ping.md +--- + +The _deprecated_ `CronJobsource` should be converted to the newer `PingSource`. + +Imagine you have a `CronJobSource` running in your cluster that emits its events to a Knative Serving Service. +The installation YAML would look like: + +```yaml +apiVersion: sources.eventing.knative.dev/v1alpha1 +kind: CronJobSource +metadata: + name: cronjob-source +spec: + schedule: "* * * * *" + data: '{"message": "Hello world!"}' + sink: + apiVersion: serving.knative.dev/v1 + kind: Service + name: event-display +``` + +If you now want to migration to the newer `PingSource`, a couple of steps are needed: + +* different GVK (see `apiVersion` and `kind` differences) +* the `PingSources` does use `jsonData` instead of `data` + +The final result would looke like: + +```yaml +apiVersion: sources.knative.dev/v1alpha2 +kind: PingSource +metadata: + name: ping-source +spec: + schedule: "* * * * *" + jsonData: '{"message": "Hello world!"}' + sink: + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: event-display +``` From c03504b56e5fe6438e569e0be996a789b78df09a Mon Sep 17 00:00:00 2001 From: Matthias Wessendorf Date: Fri, 6 Mar 2020 14:26:06 +0100 Subject: [PATCH 2/5] Addressing comment from Ashleigh's review --- docs/eventing/migration/ping.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/eventing/migration/ping.md b/docs/eventing/migration/ping.md index 56c57f33eb9..f1dba29aabe 100644 --- a/docs/eventing/migration/ping.md +++ b/docs/eventing/migration/ping.md @@ -1,15 +1,14 @@ --- -title: "Migrating to the PingSource" +title: "Migrating from CronJobSource to the PingSource" weight: 20 type: "docs" aliases: - /docs/eventing/ping.md --- -The _deprecated_ `CronJobsource` should be converted to the newer `PingSource`. +The deprecated `CronJobsource` should be converted to the `PingSource`. -Imagine you have a `CronJobSource` running in your cluster that emits its events to a Knative Serving Service. -The installation YAML would look like: +The YAML file for a `CronJobSource` that emits events to a Knative Serving service will look similar to this: ```yaml apiVersion: sources.eventing.knative.dev/v1alpha1 @@ -25,12 +24,12 @@ spec: name: event-display ``` -If you now want to migration to the newer `PingSource`, a couple of steps are needed: +To migrate this source to a `PingSource`, the following steps are required:: -* different GVK (see `apiVersion` and `kind` differences) -* the `PingSources` does use `jsonData` instead of `data` +* Different `apiVersion` and `kind` between the two +* `PingSource` uses the `jsonData` attribute instead of the `data` attribute. -The final result would looke like: +The updated YAML for `PingSource` will look similar to the following: ```yaml apiVersion: sources.knative.dev/v1alpha2 From e6424213041f04c7e304672247a164554b3e74b3 Mon Sep 17 00:00:00 2001 From: Matthias Wessendorf Date: Fri, 6 Mar 2020 14:40:02 +0100 Subject: [PATCH 3/5] Adding SinkBinding migration doc Signed-off-by: Matthias Wessendorf --- docs/eventing/migration/sinkbinding.md | 98 ++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 docs/eventing/migration/sinkbinding.md diff --git a/docs/eventing/migration/sinkbinding.md b/docs/eventing/migration/sinkbinding.md new file mode 100644 index 00000000000..7fe69cb96b7 --- /dev/null +++ b/docs/eventing/migration/sinkbinding.md @@ -0,0 +1,98 @@ +--- +title: "Migrating from ContainerSource to SinkBinding" +weight: 20 +type: "docs" +aliases: + - /docs/eventing/ping.md +--- + +The deprecated `ContainerSource` should be converted to a `SinkBinding`. + +The YAML file for a `ContainerSource` that emits events to a Knative Serving service will look similar to this: + +```yaml +apiVersion: sources.eventing.knative.dev/v1alpha1 +kind: ContainerSource +metadata: + name: urbanobservatory-event-source +spec: + image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest + args: + - '--source=wss://api.usb.urbanobservatory.ac.uk/stream' + - '--eventType=my.custom.event' + sink: + apiVersion: serving.knative.dev/v1 + kind: Service + name: wss-event-display +``` + +The referenced image of the `ContainerSource` needed an "sink" argument, [see](https://knative.dev/docs/eventing/#containersource) for details. + +To migrate this source to a `SinkBinding`, a few steps are required. Instead of using a `ContainerSource`, +you need to create a `SinkBinding`, like: + +```yaml +apiVersion: sources.knative.dev/v1alpha2 +kind: SinkBinding +metadata: + name: bind-wss +spec: + subject: + apiVersion: apps/v1 + kind: Deployment + selector: + matchLabels: + app: wss + sink: + ref: + apiVersion: serving.knative.dev/v1 + kind: Service + name: wss-event-display +``` + +Here the `SinkBinding`'s `subject` references to a Kubernetes `Deployment`, that is labeled with `app: wss`. The YAML for the `Deployment` +looks like: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: wss + labels: + app: wss +spec: + selector: + matchLabels: + app: wss + template: + metadata: + labels: + app: wss + spec: + containers: + - image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest + name: wss + args: + - '--source=wss://api.usb.urbanobservatory.ac.uk/stream' + - '--eventType=my.custom.event' +``` + +The `Deployment` is a standard Kubernetes Deployment, like you might have used before. However, the important part here is that it has the `app: wss` +label, which is needed by the above `SinkBinding` in order to _bind_ the two components together. + +The `image` that is used by the `Deployment` is required to understands the semantics of the `K_SINK` environment variable, holding the endpoint to which to send cloud events. The `K_SINK` environment variable is part of the `SinkBinding`'s runtime contract of the [referenced container image](https://knative.dev/docs/reference/eventing/#sources.knative.dev/v1alpha2.SinkBinding). + +Running the above example will give a log like: + +``` +☁️ cloudevents.Event +Validation: valid +Context Attributes, + specversion: 1.0 + type: my.custom.event + source: wss://api.usb.urbanobservatory.ac.uk/stream + id: 3029a2f2-3ce1-48c0-9ed3-37d7ad88d0ef + time: 2020-03-05T13:46:15.329595422Z +Data, + {"signal":2,"data":{"brokerage":{"broker":{"id":"BMS-USB-5-JACE","meta":{"protocol":"BACNET","building":"Urban Sciences Building","buildingFloor":"5"}},"id":"Drivers.L6_C3_Electric_Meters.C3_Mechcanical_Plant.points.C3_HP_Current_L1","meta":{}},"entity":{"name":"Urban Sciences Building: Floor 5","meta":{"building":"Urban Sciences Building","buildingFloor":"5"}},"feed":{"metric":"C3 HP Current L1","meta":{}},"timeseries":{"unit":"no units","value":{"time":"2020-03-05T13:45:51.468Z","timeAccuracy":8.754,"data":0.47110211849212646,"type":"Real"}}},"recipients":0} +``` From a859df493e6a2b4a74ff8591b6d6b4337bc34e11 Mon Sep 17 00:00:00 2001 From: Matthias Wessendorf Date: Mon, 9 Mar 2020 12:10:56 +0100 Subject: [PATCH 4/5] fix the ko:// by removing... --- docs/eventing/migration/sinkbinding.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/eventing/migration/sinkbinding.md b/docs/eventing/migration/sinkbinding.md index 7fe69cb96b7..3a6bc57ee88 100644 --- a/docs/eventing/migration/sinkbinding.md +++ b/docs/eventing/migration/sinkbinding.md @@ -16,8 +16,8 @@ kind: ContainerSource metadata: name: urbanobservatory-event-source spec: - image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest - args: + image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest + args: - '--source=wss://api.usb.urbanobservatory.ac.uk/stream' - '--eventType=my.custom.event' sink: @@ -72,7 +72,7 @@ spec: containers: - image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest name: wss - args: + args: - '--source=wss://api.usb.urbanobservatory.ac.uk/stream' - '--eventType=my.custom.event' ``` From b886d86651ec5f4efb563dc5d9534466790c517b Mon Sep 17 00:00:00 2001 From: Matthias Wessendorf Date: Mon, 9 Mar 2020 17:54:29 +0100 Subject: [PATCH 5/5] Addressing feedback Signed-off-by: Matthias Wessendorf --- docs/eventing/migration/ping.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/eventing/migration/ping.md b/docs/eventing/migration/ping.md index f1dba29aabe..f5e944a11fd 100644 --- a/docs/eventing/migration/ping.md +++ b/docs/eventing/migration/ping.md @@ -41,7 +41,7 @@ spec: jsonData: '{"message": "Hello world!"}' sink: ref: - apiVersion: serving.knative.dev/v1 - kind: Service - name: event-display + apiVersion: serving.knative.dev/v1 + kind: Service + name: event-display ```