knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sink binding docs overhaul (#2920) 

* Sink binding docs overhaul

* fix tabs formatting

* fix tabs formatting

* fix tabs formatting

* fix formatting, correct minor typo

* cleanup tabs

* cleanup tabs

* changed structure slightly
This commit is contained in:
Ashleigh Brennan 2020-12-02 15:54:08 -06:00 committed by GitHub
parent 0281c85bc7
commit c1f0d34762
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 194 additions and 535 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/eventing/README.md
View File

@ -10,8 +10,7 @@ well-supported by the existing components; since the system is modular, it's
also possible to combine the components in novel ways.
1. **I just want to publish events, I don't care who consumes them.** Send
events to a [Broker](broker/README.md) as an HTTP POST. The
[SinkBinding](samples/sinkbinding/README.md) can be useful to decouple the destination
events to a [Broker](broker/README.md) as an HTTP POST. [Sink binding](./sources/sinkbinding) can be useful to decouple the destination
configuration from your application.
1. **I just want to consume events like X, I don't care how they are
@ -102,17 +101,6 @@ Trigger without resorting to some other out-of-band mechanism.
To learn how to use the registry, see the
[Event Registry documentation](./event-registry.md).
### Simplify event delivery
The [SinkBinding](samples/sinkbinding/README.md) custom object supports decoupling event
production from delivery addressing.
When you create a SinkBinding, you reference an Addressable and a Kubernetes
object which provides a PodTemplateSpec. The SinkBinding will inject environment
variables (`$K_SINK` for the destination URL) into the PodTemplateSpec so that
the application code does not need to interact with the Kubernetes API to locate
the event destination.
### Event channels and subscriptions
Knative Eventing also defines an event forwarding and persistence layer, called

211
docs/eventing/samples/sinkbinding/README.md
View File

@ -1,211 +0,0 @@
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-contrib](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/<username>`)
- 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/knative.dev/eventing-contrib/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` and `$K_CE_OVERRIDES` into select `Jobs`:
```yaml
apiVersion: sources.knative.dev/v1
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
ceOverrides:
extensions:
sink: bound
```
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/v1
kind: CronJob
metadata:
name: heartbeat-cron
spec:
# Run every minute
schedule: "* * * * *"
jobTemplate:
metadata:
labels:
app: heartbeat-cron
spec:
template:
spec:
restartPolicy: Never
containers:
- name: single-heartbeat
image: <FILL IN YOUR IMAGE HERE>
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: 1.0
type: dev.knative.eventing.samples.heartbeat
source: https://knative.dev/eventing-contrib/cmd/heartbeats/#default/heartbeat-cron-1582120020-75qrz
id: 5f4122be-ac6f-4349-a94f-4bfc6eb3f687
time: 2020-02-19T13:47:10.41428688Z
datacontenttype: application/json
Extensions,
beats: true
heart: yes
the: 42
Data,
{
"id": 1,
"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.knative.dev/v1
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
```

47
docs/eventing/samples/sinkbinding/heartbeats-source.yaml
View File

@ -1,47 +0,0 @@
# 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:
name: heartbeat-cron
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]/knative.dev/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

8
docs/eventing/samples/sinkbinding/index.md
View File

@ -1,8 +0,0 @@
---
title: "Sink Binding Example"
linkTitle: "Sink Binding"
weight: 10
type: "docs"
---
{{% readfile file="README.md" %}}

23
docs/eventing/samples/sinkbinding/service.yaml
View File

@ -1,23 +0,0 @@
# 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/knative.dev/eventing-contrib/cmd/event_display

35
docs/eventing/samples/sinkbinding/sinkbinding.yaml
View File

@ -1,35 +0,0 @@
# 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.knative.dev/v1
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
ceOverrides:
extensions:
sink: bound

5
docs/eventing/sources/_index.md
View File

@ -13,7 +13,7 @@ The Source object defines the arguments and parameters needed to instantiate a C
All Sources are part of the `sources` category.
{{< tabs name="List event sources" default="kubectl" >}} {{% tab name="kubectl" %}}
You can list existing event sources on your cluster by entering the ommand:
You can list existing event sources on your cluster by entering the command:
```shell
kubectl get sources
@ -45,7 +45,7 @@ kn source list
| [Heartbeats](https://github.com/knative/eventing-contrib/tree/master/cmd/heartbeats) | N/A | Knative | Uses an in-memory timer to produce events at the specified interval. |
| [PingSource](./pingsource) | v1beta2 | Knative | Produces events with a fixed payload on a specified [Cron](https://en.wikipedia.org/wiki/Cron) schedule. See the [Ping Source](../samples/ping-source) example for more details. |
| [RabbitMQ](https://github.com/knative-sandbox/eventing-rabbitmq) | Active development | None | Brings [RabbitMQ](https://www.rabbitmq.com/) messages into Knative.
| [SinkBinding](https://knative.dev/docs/eventing/samples/sinkbinding/) | v1 | Knative | 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). SinkBinding provides a framework for injecting `K_SINK` (destination address) and `K_CE_OVERRIDES` (JSON cloudevents attributes) environment variables into any Kubernetes resource which has a `spec.template` that looks like a Pod (aka PodSpecable). See the [SinkBinding](../samples/container-source) example for more details. |
| [SinkBinding](./sinkbinding/) | v1 | Knative | 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). SinkBinding provides a framework for injecting `K_SINK` (destination address) and `K_CE_OVERRIDES` (JSON cloudevents attributes) environment variables into any Kubernetes resource which has a `spec.template` that looks like a Pod (aka PodSpecable). See the [SinkBinding](../samples/container-source) example for more details. |
| [WebSocket](https://github.com/knative/eventing-contrib/tree/master/cmd/websocketsource) | N/A | Knative | Opens a WebSocket to the specified source and packages each received message as a Knative event. |
## Third-Party Sources
@ -79,4 +79,3 @@ kn source list
- For information about creating your own Source type, see the [tutorial on writing a Source with a Receive Adapter](../samples/writing-event-source).
- If your code needs to send events as part of its business logic and doesn't fit the model of a Source, consider [feeding events directly to a Broker](https://knative.dev/docs/eventing/broker/).
- For more information about using `kn` Source related commands, see the [`kn source` reference documentation](https://github.com/knative/client/blob/master/docs/cmd/kn_source.md).

386
docs/eventing/sources/sinkbinding.md
View File

@ -1,134 +1,163 @@
---
title: "SinkBinding"
linkTitle: "SinkBinding"
weight: 31
title: "Sink binding"
weight: 60
type: "docs"
aliases:
- /docs/eventing/samples/sinkbinding/index
- /docs/eventing/samples/sinkbinding/README
---
![version](https://img.shields.io/badge/API_Version-v1-red?style=flat-square)
A SinkBinding provides a framework for injecting `K_SINK` (destination address) and `K_CE_OVERRIDES` (JSON cloudevents attributes)
environment variables into any Kubernetes resource which has a `spec.template` that looks like a Pod (aka PodSpecable).
The `SinkBinding` custom object supports decoupling event production from delivery addressing.
### Prerequisites
- Install [ko](https://github.com/google/ko)
- Set `KO_DOCKER_REPO`
(e.g. `gcr.io/[gcloud-project]` or `docker.io/<username>`)
- Authenticated with your `KO_DOCKER_REPO`
- Install [`docker`](https://docs.docker.com/install/)
You can use sink binding to connect Kubernetes resources that embed a `PodSpec` and want to produce events, such as an event source, to an addressable Kubernetes object that can receive events, also known as an _event sink_.
## Installation
Sink binding can be used to create new event sources using any of the familiar compute objects that Kubernetes makes available.
For example, `Deployment`, `Job`, `DaemonSet`, or `StatefulSet` objects, or Knative abstractions, such as `Service` or `Configuration` objects, can be used.
The SinkBinding type is enabled by default when you install Knative Eventing.
Sink binding injects environment variables into the `PodTemplateSpec` of the event sink, so that the application code does not need to interact directly with the Kubernetes API to locate the event destination.
## Example
## Getting started
This example shows the SinkBinding that injects`$K_SINK` and `$K_CE_OVERRIDES` into select `Jobs` and direct events to the Event Display Service.
### 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
```
The following procedures show how you can create a sink binding and connect it to a service and event source in your cluster.
### Creating a namespace
Create a new namespace called `sinkbinding-example` by entering the following
command:
Create a namespace called `sinkbinding-example`:
```shell
kubectl create namespace sinkbinding-example
```
```bash
kubectl create namespace sinkbinding-example
```
### Creating the Event Display Service
### Creating a Knative service
In this step, you create one event consumer, `event-display` to verify that
`SinkBinding` is properly working.
Create a Knative service if you do not have an existing event sink that you want to connect to the sink binding.
To deploy the `event-display` consumer to your cluster, run the following
command:
#### Prerequisites
- You must have Knative Serving installed on your cluster.
- Optional: If you want to use `kn` commands with sink binding, you must install the `kn` CLI.
```shell
kubectl -n sinkbinding-example apply -f - << EOF
apiVersion: apps/v1
kind: Deployment
metadata:
name: event-display
spec:
replicas: 1
selector:
matchLabels: &labels
app: event-display
template:
metadata:
labels: *labels
spec:
containers:
- name: event-display
image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display
#### Procedure
Create a Knative service:
---
{{< tabs name="knative_service" default="kn" >}}
{{% tab name="kn" %}}
kind: Service
apiVersion: v1
metadata:
name: event-display
spec:
selector:
app: event-display
ports:
- protocol: TCP
port: 80
targetPort: 8080
EOF
```
### Creating the SinkBinding
In order to direct events to our Event Display, we will first create a
SinkBinding that will inject `$K_SINK` and `$K_CE_OVERRIDES` into select `Jobs`:
{{< tabs name="create-source" default="YAML" >}}
{{% tab name="YAML" %}}
```shell
kubectl -n sinkbinding-example apply -f - << EOF
apiVersion: sources.knative.dev/v1
kind: SinkBinding
metadata:
name: bind-heartbeat
spec:
subject:
apiVersion: batch/v1
kind: Job
selector:
matchLabels:
app: heartbeat-cron
sink:
ref:
apiVersion: v1
kind: Service
name: event-display
ceOverrides:
extensions:
sink: bound
EOF
```bash
kn service create hello --image gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display --env RESPONSE="Hello Serverless!"
```
{{< /tab >}}
{{% tab name="yaml" %}}
1. Copy the sample YAML into a `service.yaml` file:
```yaml
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
name: event-display
spec:
template:
spec:
containers:
- image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display
```
2. Apply the file:
```bash
kubectl apply --filename service.yaml
```
{{< /tab >}}
{{< /tabs >}}
### Creating a cron job
Create a cron job if you do not have an existing event source that you want to connect to the sink binding.
<!-- TODO: Add kn command-->
Create a `CronJob` object:
1. Copy the sample YAML into a `cronjob.yaml` file:
```yaml
apiVersion: batch/v1
kind: CronJob
metadata:
name: heartbeat-cron
spec:
# Run every minute
schedule: "* * * * *"
jobTemplate:
metadata:
labels:
app: heartbeat-cron
spec:
template:
spec:
restartPolicy: Never
containers:
- name: single-heartbeat
image: <FILL IN YOUR IMAGE HERE>
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
```
2. Apply the file:
```bash
kubectl apply --filename heartbeats-source.yaml
```
#### Cloning a sample heartbeat cron job
Knative [event-contrib](https://github.com/knative/eventing-contrib) contains a
sample heartbeats event source.
##### Prerequisites
- Ensure that `ko publish` is set up correctly:
- [`KO_DOCKER_REPO`](https://github.com/knative/serving/blob/master/DEVELOPMENT.md#environment-setup)
must be set. For example, `gcr.io/[gcloud-project]` or `docker.io/<username>`.
- You must have authenticated with your `KO_DOCKER_REPO`.
##### Procedure
1. Clone the `event-contib` repository:
```bash
$ git clone -b "{{< branch >}}" https://github.com/knative/eventing-contrib.git
```
2. Build a heartbeats image, and publish the image to your image repository:
```bash
$ ko publish knative.dev/eventing-contrib/cmd/heartbeats
```
<!-- TODO: Add tabs if there are kn commands etc to do this also-->
## Creating a SinkBinding object
Create a `SinkBinding` object that directs events from your cron job to the event sink.
### Prerequisites
- You must have Knative Eventing installed on your cluster.
- Optional: If you want to use `kn` commands with sink binding, you must install the `kn` CLI.
### Procedure
Create a sink binding:
{{< tabs name="sinkbinding" default="kn" >}}
{{% tab name="kn" %}}
```shell
```bash
kn source binding create bind-heartbeat \
--namespace sinkbinding-example \
--subject "Job:batch/v1:app=heartbeat-cron" \
@ -136,102 +165,69 @@ kn source binding create bind-heartbeat \
--ce-override "sink=bound"
```
{{< /tab >}}
{{% tab name="yaml" %}}
1. Copy the sample YAML into a `cronjob.yaml` file:
```yaml
apiVersion: sources.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
```
2. Apply the file:
```bash
kubectl apply --filename heartbeats-source.yaml
```
{{< /tab >}}
{{< /tabs >}}
In this case, we will bind any `Job` with the labels `app: heartbeat-cron`.
## Verification steps
### Creating the CronJob
1. Verify that a message was sent to the Knative eventing system by looking at the `event-display` service logs:
```bash
kubectl logs -l serving.knative.dev/service=event-display -c user-container --since=10m
```
2. Observe the lines showing the request headers and body of the event message, sent by the heartbeats source to the display function:
```bash
☁️ cloudevents.Event
Validation: valid
Context Attributes,
specversion: 1.0
type: dev.knative.eventing.samples.heartbeat
source: https://knative.dev/eventing-contrib/cmd/heartbeats/#default/heartbeat-cron-1582120020-75qrz
id: 5f4122be-ac6f-4349-a94f-4bfc6eb3f687
time: 2020-02-19T13:47:10.41428688Z
datacontenttype: application/json
Extensions,
beats: true
heart: yes
the: 42
Data,
{
"id": 1,
"label": ""
}
```
Now we will use the heartbeats container to send events to `$K_SINK` every time
the CronJob runs:
```shell
kubectl -n sinkbinding-example apply -f - << EOF
apiVersion: batch/v1beta1
kind: CronJob
metadata:
name: heartbeat-cron
spec:
# Run every minute
schedule: "* * * * *"
jobTemplate:
metadata:
labels:
app: heartbeat-cron
spec:
template:
spec:
restartPolicy: Never
containers:
- name: single-heartbeat
# This corresponds to a heartbeats image uri you build and publish in the previous step
# e.g. gcr.io/[gcloud-project]/knative.dev/eventing-contrib/cmd/heartbeats
image: <heartbeats_image_uri>
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
EOF
```
### Verify
View the logs for the `event-display` event consumer by
entering the following command:
```shell
kubectl -n sinkbinding-example logs -l app=event-display --tail=200
```
You should see log lines showing the request headers and body of the event
message sent by the heartbeats source to the display function:
```shell
☁️ cloudevents.Event
Validation: valid
Context Attributes,
specversion: 1.0
type: dev.knative.eventing.samples.heartbeat
source: https://knative.dev/eventing-contrib/cmd/heartbeats/#default/heartbeat-cron-1582120020-75qrz
id: 5f4122be-ac6f-4349-a94f-4bfc6eb3f687
time: 2020-02-19T13:47:10.41428688Z
datacontenttype: application/json
Extensions,
beats: true
heart: yes
the: 42
Data,
{
"id": 1,
"label": ""
}
```
### Cleanup
## Cleanup
Delete the `sinkbinding-example` namespace and all of its resources from your
cluster by entering the following command:
cluster:
```shell
kubectl delete namespace sinkbinding-example
```
## Reference Documentation
See the [PingSource specification](../../reference/api/eventing/#sources.knative.dev/v1.SinkBinding).
## Contact
For any inquiries about this source, please reach out on to the
[Knative users group](https://groups.google.com/forum/#!forum/knative-users).
```bash
kubectl delete namespace sinkbinding-example
```