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

Updating ContainerSource, Sources list, and migration example (#2342) 

* updates to sources.

* update

* Update docs/eventing/README.md

Co-Authored-By: Matt Moore <mattmoor@vmware.com>

* Update docs/eventing/README.md

Co-Authored-By: Matt Moore <mattmoor@vmware.com>

* Update docs/eventing/README.md

Co-Authored-By: Matt Moore <mattmoor@vmware.com>

* Update docs/eventing/migration/sinkbinding.md

Co-Authored-By: Matt Moore <mattmoor@vmware.com>

* Update docs/eventing/README.md

Co-Authored-By: Matt Moore <mattmoor@vmware.com>

* Update docs/eventing/README.md

Co-Authored-By: Matt Moore <mattmoor@vmware.com>

* updates

* Update docs/eventing/migration/sinkbinding.md

Co-Authored-By: Matt Moore <mattmoor@vmware.com>

* added

Co-authored-by: Matt Moore <mattmoor@vmware.com>
This commit is contained in:
Ignacio (Nacho) Cano 2020-03-27 11:59:52 -07:00 committed by GitHub
parent 6b5971327e
commit 3c5fa60c75
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 192 additions and 305 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

304
docs/eventing/README.md
View File

@ -137,17 +137,13 @@ messaging protocols.
Each source is a separate Kubernetes custom resource. This allows each type of Each source is a separate Kubernetes custom resource. This allows each type of
Source to define the arguments and parameters needed to instantiate a source. Source to define the arguments and parameters needed to instantiate a source.
Knative Eventing defines the following Sources in the All Sources should be part of the `sources` category, so you can list all existing Sources with
`sources.eventing.knative.dev` API group. Types below are declared in golang `kubectl get sources`.
format, but may be expressed as simple lists, etc in YAML. All Sources should be
part of the `sources` category, so you can list all existing Sources with
`kubectl get sources`. The currently-implemented Sources are described below.
In addition to the core sources (explained below), there are In addition to the sources explained below, there are
[other sources](./sources/README.md) that you can install. [other sources](./sources/README.md) that you can install.
If you need a Source not covered by the ones mentioned below nor by the other
If you need a Source not covered by the [available implementations](./sources/README.md), there is a
[available Source implementations](./sources/README.md), there is a
[tutorial on writing your own Source with kubebuilder](./samples/writing-a-source/README.md) as [tutorial on writing your own Source with kubebuilder](./samples/writing-a-source/README.md) as
well as an well as an
[extended tutorial on writing a Source with Receive Adapter](./samples/writing-receive-adapter-source). [extended tutorial on writing a Source with Receive Adapter](./samples/writing-receive-adapter-source).
@ -156,216 +152,67 @@ If your code needs to send events as part of its business logic and doesn't fit
the model of a Source, consider the model of a Source, consider
[feeding events directly to a Broker](https://knative.dev/docs/eventing/broker-trigger/#manual). [feeding events directly to a Broker](https://knative.dev/docs/eventing/broker-trigger/#manual).
### APIServerSource ### Core Sources
These are the core sources that come out-of-the-box when installing Knative Eventing.
#### APIServerSource
The APIServerSource fires a new event each time a Kubernetes resource is created, updated or deleted. The APIServerSource fires a new event each time a Kubernetes resource is created, updated or deleted.
See the [Kubernetes API Server Source](samples/kubernetes-event-source) example. See the [Kubernetes API Server Source](samples/kubernetes-event-source) example for more details.
### GitHubSource #### PingSource
The PingSource fires events based on given
[Cron](https://en.wikipedia.org/wiki/Cron) schedule.
See the [Ping Source](samples/ping-source) example for more details.
#### ContainerSource
The ContainerSource will instantiate container image(s) that can generate events
until the ContainerSource is deleted. This may be used (for example) to poll an
FTP server for new files or generate events at a set time interval.
Refer to the [Container Source](samples/container-source) example for more details.
#### SinkBinding
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).
See the [SinkBinding](samples/container-source) example for more details.
### Eventing Contrib Sources
This is a non-exhaustive list of Sources supported by our community and maintained
in the [Knative Eventing-Contrib](https://github.com/knative/eventing-contrib) Github repo.
#### GitHubSource
The GitHubSource fires a new event for selected The GitHubSource fires a new event for selected
[GitHub event types](https://developer.github.com/v3/activity/events/types/). [GitHub event types](https://developer.github.com/v3/activity/events/types/).
**Spec fields**: See the [GitHub Source](samples/github-source) example for more details.
- `ownerAndRepository`: `string` The GitHub owner/org and repository to receive #### AwsSqsSource
events from. The repository may be left off to receive events from an entire
organization.
- `eventTypes`: `[]string` A list of
[event types](https://developer.github.com/v3/activity/events/types/) in
"Webhook event name" format (lower_case).
- `accessToken.secretKeyRef`:
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
containing a GitHub access token for configuring a GitHub webhook. One of this
or `secretToken` must be set.
- `secretToken.secretKeyRef`:
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
containing a GitHub secret token for configuring a GitHub webhook. One of this
or `accessToken` must be set.
- `serviceAccountName`: `string` The name of the ServiceAccount to run the
container as.
- `sink`:
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
A reference to the object that should receive events.
- `githubAPIURL`: `string` Optional field to specify the base URL for API
requests. Defaults to the public GitHub API if not specified, but can be set
to a domain endpoint to use with GitHub Enterprise, for example,
`https://github.mycompany.com/api/v3/`. This base URL should always be
specified with a trailing slash.
See the [GitHub Source](samples/github-source) example.
### CloudPubSubSource
The CloudPubSubSource fires a new event each time a message is published on a
[Google Cloud Platform PubSub topic](https://cloud.google.com/pubsub/).
**Spec fields**:
- `topic`: `string` The name of the PubSub topic.
- `sink`:
[Destination](https://github.com/knative/pkg/blob/master/apis/duck/v1/destination.go)
A reference to the target that should receive events.
- `secret`:
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
Credential to use to poll the Cloud Pub/Sub Subscription. It is not used to create or delete the Subscription, only to poll it.
The value of the secret entry must be a service account key in the JSON format (see https://cloud.google.com/iam/docs/creating-managing-service-account-keys). Defaults to secret.name of 'google-cloud-key' and secret.key of 'key.json'.
- `project`: `string` ID of the Google Cloud Project that the Pub/Sub Topic exists in. If omitted uses the Project ID from the GKE cluster metadata service.
See the [CloudPubSubSource](samples/cloud-pubsub-source) example.
### CloudStorageSource
Registers for events of the specified types on the specified
[Google Cloud Storage](https://cloud.google.com/storage/) bucket and optional object prefix.
Brings those events into Knative.
**Spec fields**:
- `bucket`: `string` GCS bucket to subscribe to. For example my-test-bucket.
- `sink`:
[Destination](https://github.com/knative/pkg/blob/master/apis/duck/v1/destination.go)
A reference to the target that should receive events.
- `secret`:
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
Credential to use for managing GCS notifications.
The value of the secret entry must be a service account key in the JSON format (see https://cloud.google.com/iam/docs/creating-managing-service-account-keys). Defaults to secret.name of 'google-cloud-key' and secret.key of 'key.json'.
- `project`: `string` ID of the Google Cloud Project that the Pub/Sub Topic exists in. If omitted uses the Project ID from the GKE cluster metadata service.
See the [CloudStorageSource](samples/cloud-storage-source) example.
### CloudSchedulerSource
Create, update, and delete [Google Cloud Scheduler](https://cloud.google.com/scheduler/) Jobs.
When those jobs are triggered, receive the event inside Knative.
**Spec fields**:
- `location`: `string` Location to create the Scheduler job in.
- `data`: `string` Data to send in the payload of the Event.
- `schedule`: `string` Frequency using the unix-cron format. Or App Engine Cron format.
- `sink`:
[Destination](https://github.com/knative/pkg/blob/master/apis/duck/v1/destination.go)
A reference to the target that should receive events.
- `secret`:
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
Credential to use for managing Scheduler Jobs.
The value of the secret entry must be a service account key in the JSON format (see https://cloud.google.com/iam/docs/creating-managing-service-account-keys). Defaults to secret.name of 'google-cloud-key' and secret.key of 'key.json'.
- `project`: `string` ID of the Google Cloud Project that the Pub/Sub Topic exists in. If omitted uses the Project ID from the GKE cluster metadata service.
See the [CloudSchedulerSource](samples/cloud-scheduler-source) example.
### CloudAuditLogsSource
Registers for events of the specified types on the specified [Google Cloud Audit Logs](https://cloud.google.com/logging/docs/audit/). Brings those events into Knative.
**Spec fields**:
- `serviceName`: `string` The GCP service providing audit logs.
- `methodName`: `string` The name of the service method or operation. For API calls, this should be the name of the API method.
- `resourceName`: `string` The resource or collection that is the target of the operation. The name is a scheme-less URI, not including the API service name. If omitted, audit log events matching service and method will be pulled for all resources.
- `sink`:
[Destination](https://github.com/knative/pkg/blob/master/apis/duck/v1/destination.go)
A reference to the target that should receive events.
- `secret`:
[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
Credential used to pull Stackdriver audit log pubsub messages.
The value of the secret entry must be a service account key in the JSON format (see https://cloud.google.com/iam/docs/creating-managing-service-account-keys). Defaults to secret.name of 'google-cloud-key' and secret.key of 'key.json'.
- `project`: `string` ID of the Google Cloud Project that the Pub/Sub Topic exists in. If omitted uses the Project ID from the GKE cluster metadata service.
See the [CloudAuditLogsSource](samples/cloud-audit-logs-source) example.
### AwsSqsSource
The AwsSqsSource fires a new event each time an event is published on an The AwsSqsSource fires a new event each time an event is published on an
[AWS SQS topic](https://aws.amazon.com/sqs/). [AWS SQS topic](https://aws.amazon.com/sqs/).
**Spec fields**: #### KafkaSource
- `queueURL`: URL of the SQS queue to pull events from.
- `awsCredsSecret`: credential to use to poll the AWS SQS queue.
- `sink`:
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
A reference to the object that should receive events.
- `serviceAccountName`: `string` The name of the ServiceAccount used to access
the `awsCredsSecret`.
### ContainerSource
The ContainerSource will instantiate a container image which can generate events
until the ContainerSource is deleted. This may be used (for example) to poll an
FTP server for new files or generate events at a set time interval.
**Spec fields**:
- `image` (**required**): `string` A docker image of the container to be run.
- `args`: `[]string` Command-line arguments. If no `--sink` flag is provided,
one will be added and filled in with the DNS address of the `sink` object.
- `env`: `map[string]string` Environment variables to be set in the container.
- `serviceAccountName`: `string` The name of the ServiceAccount to run the
container as.
- `sink`:
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
A reference to the object that should receive events.
### CronJobSource
The CronJobSource fires events based on given
[Cron](https://en.wikipedia.org/wiki/Cron) schedule.
**Spec fields**:
- `schedule` (**required**): `string` A
[Cron](https://en.wikipedia.org/wiki/Cron) format string, such as `0 * * * *`
or `@hourly`.
- `data`: `string` Optional data sent to downstream receiver.
- `serviceAccountName`: `string` The name of the ServiceAccount to run the
container as.
- `sink`:
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
A reference to the object that should receive events.
See the [Cronjob Source](samples/cronjob-source) example.
### KafkaSource
The KafkaSource reads events from an Apache Kafka Cluster, and passes these to a The KafkaSource reads events from an Apache Kafka Cluster, and passes these to a
Knative Serving application so that they can be consumed. Knative Serving application so that they can be consumed.
**Spec fields**:
- `consumerGroup`: `string` Name of a Kafka consumer group.
- `bootstrapServers`: `string` Comma separated list of `hostname:port` pairs for
the Kafka Broker.
- `topics`: `string` Name of the Kafka topic to consume messages from.
- `net`: Optional network configuration.
- `sasl`: Optional SASL authentication configuration.
- `enable`: `boolean` If true, use SASL for authentication.
- `user.secretKeyRef`:
[`SecretKeySelector`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
containing the SASL username to use.
- `password.secretKeyRef`:
[`SecretKeySelector`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
containing the SASL password to use.
- `tls`: Optional TLS configuration.
- `enable`: `boolean` If true, use TLS when connecting.
- `cert.secretKeyRef`:
[`SecretKeySelector`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
containing the client certificate to use.
- `key.secretKeyRef`:
[`SecretKeySelector`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
containing the client key to use.
- `caCert.secretKeyRef`:
[`SecretKeySelector`](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#secretkeyselector-v1-core)
containing a server CA certificate to use when verifying the server
certificate.
See the See the
[Kafka Source](https://github.com/knative/eventing-contrib/tree/master/kafka/source) [Kafka Source](https://github.com/knative/eventing-contrib/tree/master/kafka/source)
example. example for more details.
### CamelSource #### CamelSource
A CamelSource is an event source that can represent any existing A CamelSource is an event source that can represent any existing
[Apache Camel component](https://github.com/apache/camel/tree/master/components) [Apache Camel component](https://github.com/apache/camel/tree/master/components)
@ -374,34 +221,49 @@ endpoint. Each Camel endpoint has the form of a URI where the scheme is the ID
of the component to use. of the component to use.
CamelSource requires [Camel-K](https://github.com/apache/camel-k#installation) CamelSource requires [Camel-K](https://github.com/apache/camel-k#installation)
to be installed into the current namespace. to be installed into the current namespace. See the
**Spec fields**:
- source: information on the kind of Camel source that should be created.
- component: the default kind of source, enables creating an EventSource by
configuring a single Camel component.
- uri: `string` contains the Camel URI that should be used to push events
into the target sink.
- properties: `key/value map` contains Camel global options or component
specific configuration. Options are available in the documentation of each
existing Apache Camel component.
- serviceAccountName: `string` an optional service account that can be used to
run the source pod.
- image: `string` an optional base image to use for the source pod, mainly for
development purposes.
See the
[CamelSource](https://github.com/knative/eventing-contrib/tree/master/camel/source/samples) [CamelSource](https://github.com/knative/eventing-contrib/tree/master/camel/source/samples)
example. example.
### Google Cloud Sources
In order to consume events from different GCP services, [Knative-GCP](https://github.com/google/knative-gcp) supports
different GCP Sources.
#### CloudPubSubSource
The CloudPubSubSource fires a new event each time a message is published on a
[Google Cloud Platform PubSub topic](https://cloud.google.com/pubsub/).
See the [CloudPubSubSource](samples/cloud-pubsub-source) example for more details.
#### CloudStorageSource
Registers for events of specific types on the specified
[Google Cloud Storage](https://cloud.google.com/storage/) bucket and optional object prefix.
Brings those events into Knative.
See the [CloudStorageSource](samples/cloud-storage-source) example.
#### CloudSchedulerSource
Creates, updates, and deletes [Google Cloud Scheduler](https://cloud.google.com/scheduler/) Jobs.
When those jobs are triggered, receive the event inside Knative.
See the [CloudSchedulerSource](samples/cloud-scheduler-source) example for further details.
#### CloudAuditLogsSource
Registers for events of specific types on the specified [Google Cloud Audit Logs](https://cloud.google.com/logging/docs/audit/).
Brings those events into Knative.
Refer to the [CloudAuditLogsSource](samples/cloud-audit-logs-source) example for more details.
## Getting Started ## Getting Started
- [Setup Knative Serving](../install/README.md)
- [Install the Eventing component](#installation) - [Install the Eventing component](#installation)
- [Setup Knative Serving](../install/README.md)
- [Run samples](./samples/) - [Run samples](./samples/)
## Configuration
- [Default Channels](./channels/default-channels.md) provide a way to choose the - [Default Channels](./channels/default-channels.md) provide a way to choose the
persistence strategy for Channels across the cluster. persistence strategy for Channels across the cluster.

7
docs/eventing/migration/README.md
View File

@ -1,3 +1,6 @@
Knative Eventing in version 0.13 does deprecate a few resources. This document provides a collection of migration examples: Knative Eventing in version 0.13 does deprecate a few resources and
introduces new constructs for fine-grained control
over underlying resources.
This document provides a collection of such examples:
* [PingSource](./ping.md) migration from `CronJobSource`. * [PingSource](./ping.md) migration from `CronJobSource`.
* [SinkBinding](./sinkbinding.md) migration from `ContainerSource`. * [SinkBinding](./sinkbinding.md) alternative to `ContainerSource`.

89
docs/eventing/migration/sinkbinding.md
View File

@ -1,42 +1,47 @@
--- ---
title: "Migrating from ContainerSource to SinkBinding" title: "SinkBinding alternative to ContainerSource"
weight: 20 weight: 20
type: "docs" type: "docs"
aliases: aliases:
- /docs/eventing/ping.md - /docs/eventing/sinkbinding.md
--- ---
The deprecated `ContainerSource` should be converted to a `SinkBinding`. `ContainerSource` can be seen as the combination of
`SinkBinding`+`Deployment`. In fact, that
is exactly how it's implemented!
The YAML file for a `ContainerSource` that emits events to a Knative Serving service will look similar to this: In YAML, these two options are equivalent:
```yaml 1. `ContainerSource` that emits events to a `Knative Service`:
apiVersion: sources.eventing.knative.dev/v1alpha1
kind: ContainerSource ```yaml
metadata: apiVersion: sources.knative.dev/v1alpha2
kind: ContainerSource
metadata:
name: urbanobservatory-event-source name: urbanobservatory-event-source
spec: spec:
image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest template:
spec:
containers:
- image: quay.io/openshift-knative/knative-eventing-sources-websocketsource:latest
args: args:
- '--source=wss://api.usb.urbanobservatory.ac.uk/stream' - '--source=wss://api.usb.urbanobservatory.ac.uk/stream'
- '--eventType=my.custom.event' - '--eventType=my.custom.event'
sink: sink:
ref:
apiVersion: serving.knative.dev/v1 apiVersion: serving.knative.dev/v1
kind: Service kind: Service
name: wss-event-display name: wss-event-display
``` ```
The referenced image of the `ContainerSource` needed an "sink" argument, [see](https://knative.dev/docs/eventing/#containersource) for details. 2. `SinkBinding` + `Deployment`. Something like the following:
To migrate this source to a `SinkBinding`, a few steps are required. Instead of using a `ContainerSource`, ```yaml
you need to create a `SinkBinding`, like: apiVersion: sources.knative.dev/v1alpha2
kind: SinkBinding
```yaml metadata:
apiVersion: sources.knative.dev/v1alpha2
kind: SinkBinding
metadata:
name: bind-wss name: bind-wss
spec: spec:
subject: subject:
apiVersion: apps/v1 apiVersion: apps/v1
kind: Deployment kind: Deployment
@ -48,19 +53,24 @@ spec:
apiVersion: serving.knative.dev/v1 apiVersion: serving.knative.dev/v1
kind: Service kind: Service
name: wss-event-display 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` Here the `SinkBinding`'s `subject` references to a Kubernetes
looks like: `Deployment`, that is labeled with `app: wss`. This is done with
the `subject.selector` field, which is a standard Kubernetes
Label Selector object. Note that you could explicitly set a
`Deployment` name and namespace in `subject` (i.e., `subject.name`
and `subject.namespace`) instead of using `subject.selector`.
The YAML for the `Deployment` looks like:
```yaml ```yaml
apiVersion: apps/v1 apiVersion: apps/v1
kind: Deployment kind: Deployment
metadata: metadata:
name: wss name: wss
labels: labels:
app: wss app: wss
spec: spec:
selector: selector:
matchLabels: matchLabels:
app: wss app: wss
@ -75,14 +85,17 @@ spec:
args: args:
- '--source=wss://api.usb.urbanobservatory.ac.uk/stream' - '--source=wss://api.usb.urbanobservatory.ac.uk/stream'
- '--eventType=my.custom.event' - '--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` The `Deployment` is a standard Kubernetes Deployment, like you might have used before. However, the important part
label, which is needed by the above `SinkBinding` in order to _bind_ the two components together. 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). In both cases, the `image` is required to understand
the semantics of the `K_SINK` environment variable, which holds
the destination endpoint for sending CloudEvents.
Running the above example will give a log like: Running any of the above examples will give a log similar to:
``` ```
☁️ cloudevents.Event ☁️ cloudevents.Event
@ -96,3 +109,13 @@ Context Attributes,
Data, 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} {"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}
``` ```
## When to use SinkBinding?
From the above options, `ContainerSource` is probably the less
verbose.
However, the true power of `SinkBinding` comes from the fact that
it can work not just with `Deployments`
but with **any** PodSpecable (e.g., `StatefulSet`, `ReplicateSet`,
`DaemonSet`, `Knative Service`, etc.).
If you do need that flexibility, we highly recommend you to use `SinkBinding`.

14
docs/eventing/samples/container-source/README.md
View File

@ -82,7 +82,7 @@ file. Note that arguments and environment variables are set and will be passed
to the container. to the container.
```yaml ```yaml
apiVersion: sources.eventing.knative.dev/v1alpha1 apiVersion: sources.knative.dev/v1alpha2
kind: ContainerSource kind: ContainerSource
metadata: metadata:
name: test-heartbeats name: test-heartbeats
@ -129,7 +129,7 @@ message sent by the heartbeats source to the display function:
☁️ cloudevents.Event ☁️ cloudevents.Event
Validation: valid Validation: valid
Context Attributes, Context Attributes,
specversion: 0.3 specversion: 1.0
type: dev.knative.eventing.samples.heartbeat type: dev.knative.eventing.samples.heartbeat
source: https://knative.dev/eventing-contrib/cmd/heartbeats/#event-test/mypod source: https://knative.dev/eventing-contrib/cmd/heartbeats/#event-test/mypod
id: 2b72d7bf-c38f-4a98-a433-608fbcdd2596 id: 2b72d7bf-c38f-4a98-a433-608fbcdd2596
@ -160,11 +160,9 @@ any tools you like. Here are some basic guidelines:
- The container image must have a `main` method to start with. - The container image must have a `main` method to start with.
- The `main` method will accept parameters from arguments and environment - The `main` method will accept parameters from arguments and environment
variables. variables.
- The arguments may include a `sink` if a flag `--sink` is set or a Sink object - Two environments variables will be injected by the `ContainerSource` controller,
is provided in the ContainerSource YAML file. `K_SINK` and `K_CE_OVERRIDES`, resolved from `spec.sink` and `spec.ceOverrides` respectively.
- The environment variables may include a `SINK` if a `SINK` variable is set in - The event messages shall be sent to the sink URI specified in `K_SINK`. The message can be any
the `env` or a Sink object is provided in the ContainerSource YAML file.
- The event messages shall be sent to the sink uri. The message can be any
format. format.
[CloudEvents](https://github.com/cloudevents/spec/blob/master/spec.md#design-goals) [CloudEvents](https://github.com/cloudevents/spec/blob/master/spec.md#design-goals)
format is recommended. format is recommended.
@ -175,6 +173,6 @@ event source is a sample for your reference.
### Create the ContainerSource using this container image ### Create the ContainerSource using this container image
When the container image is ready, a YAML file will be used to create a concrete When the container image is ready, a YAML file will be used to create a concrete
ContainerSource. Use [heartbeats-source.yaml](./heartbeats-source.yaml) as a `ContainerSource`. Use [heartbeats-source.yaml](./heartbeats-source.yaml) as a
sample for reference. [Learn more about the ContainerSource sample for reference. [Learn more about the ContainerSource
specification](../../../eventing#containersource). specification](../../../eventing#containersource).

2
docs/eventing/samples/container-source/heartbeats-source.yaml
View File

@ -1,4 +1,4 @@
apiVersion: sources.eventing.knative.dev/v1alpha1 apiVersion: sources.knative.dev/v1alpha2
kind: ContainerSource kind: ContainerSource
metadata: metadata:
name: test-heartbeats name: test-heartbeats

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

@ -122,7 +122,6 @@ apiVersion: batch/v1beta1
kind: CronJob kind: CronJob
metadata: metadata:
name: heartbeat-cron name: heartbeat-cron
spec:
spec: spec:
# Run every minute # Run every minute
schedule: "* * * * *" schedule: "* * * * *"

6
docs/eventing/sources/README.md
View File

@ -1,7 +1,7 @@
--- ---
title: "Knative Eventing sources" title: "Knative Eventing sources"
linkTitle: "Eventing sources" linkTitle: "Eventing sources"
weight: 30 weight: 20
type: "docs" type: "docs"
--- ---
@ -58,10 +58,10 @@ These are not directly usable, but make writing a Source much easier.
Name | Status | Support | Description Name | Status | Support | Description
--- | --- | --- | --- --- | --- | --- | ---
[Auto Container Source](https://github.com/Harwayne/auto-container-source) | Proof of Concept | None | AutoContainerSource is a controller that allows the Source CRDs _without_ needing a controller. It notices CRDs with a specific label and starts controlling resources of that type. It utilizes Container Source as underlying infrastructure. [Auto Container Source](https://github.com/Harwayne/auto-container-source) | Proof of Concept | None | AutoContainerSource is a controller that allows the Source CRDs _without_ needing a controller. It notices CRDs with a specific label and starts controlling resources of that type. It utilizes Container Source as underlying infrastructure.
[Container Source](https://knative.dev/docs/eventing/migration/sinkbinding) | Deprecated, replaced by SinkBinding | Knative | ContainerSource was an earlier version of SinkBinding which controlled the lifetime of a single Pod which acted as an event source. SinkBinding is more flexible and is preferred. [Container Source](https://knative.dev/docs/eventing/migration/sinkbinding) | Active Development | Knative | Given a `spec.template` with at least a container image specified, ContainerSource will keep a `Pod` running with the specified image(s). `K_SINK` (destination address) and `KE_CE_OVERRIDES` (JSON CloudEvents attributes) environment variables are injected into the running image(s). It is used by multiple other Sources as underlying infrastructure.
[Kubebuilder Sample Source](https://github.com/grantr/sample-source) | Proof of Concept | None | Kubebuilder SampleSource is a kubebuilder based implementation supporting the [Writing an Event Source the Hard Way tutorial](../samples/writing-a-source). [Kubebuilder Sample Source](https://github.com/grantr/sample-source) | Proof of Concept | None | Kubebuilder SampleSource is a kubebuilder based implementation supporting the [Writing an Event Source the Hard Way tutorial](../samples/writing-a-source).
[Sample Source](https://github.com/knative/sample-source) | Active Development | Knative | Used as reference implementation supporting [Writing an Event Source from Scratch tutorial](../samples/writing-receive-adapter-source). [Sample Source](https://github.com/knative/sample-source) | Active Development | Knative | Used as reference implementation supporting [Writing an Event Source from Scratch tutorial](../samples/writing-receive-adapter-source).
[SinkBinding](https://knative.dev/docs/eventing/samples/sinkbinding/) | Active Development | Knative | 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 PodSpeccable). [SinkBinding](https://knative.dev/docs/eventing/samples/sinkbinding/) | Active Development | Knative | 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).

10
docs/eventing/sources/sources.yaml
View File

@ -8,14 +8,16 @@ metaSources:
description: > description: >
SinkBinding provides a framework for injecting `K_SINK` (destination address) and SinkBinding provides a framework for injecting `K_SINK` (destination address) and
`K_CE_OVERRIDES` (JSON cloudevents attributes) environment variables into any Kubernetes `K_CE_OVERRIDES` (JSON cloudevents attributes) environment variables into any Kubernetes
resource which has a `spec.template` that looks like a Pod (aka PodSpeccable). resource which has a `spec.template` that looks like a Pod (aka PodSpecable).
- name: Container Source - name: Container Source
url: https://knative.dev/docs/eventing/migration/sinkbinding url: https://knative.dev/docs/eventing/migration/sinkbinding
status: Deprecated, replaced by SinkBinding status: Active Development
support: Knative support: Knative
description: > description: >
ContainerSource was an earlier version of SinkBinding which controlled the lifetime of a single Given a `spec.template` with at least a container image specified, ContainerSource will keep a `Pod`
Pod which acted as an event source. SinkBinding is more flexible and is preferred. running with the specified image(s). `K_SINK` (destination address) and `KE_CE_OVERRIDES` (JSON
CloudEvents attributes) environment variables are injected into the running image(s). It is used by multiple
other Sources as underlying infrastructure.
- name: Auto Container Source - name: Auto Container Source
url: https://github.com/Harwayne/auto-container-source url: https://github.com/Harwayne/auto-container-source
status: Proof of Concept status: Proof of Concept