mirror of https://github.com/knative/docs.git
Update documentation for 0.2 release. (#527)
This commit is contained in:
Evan Anderson
Knative Prow Robot
parent
ab99b9b18e
commit
5bf95ba8ef
|
|
@ -1,7 +1,7 @@
|
||||||
# Knative Events
|
# Knative Eventing
|
||||||
|
|
||||||
Knative Events is a system which is designed to address a common need for cloud
|
Knative Eventing is a system which is designed to address a common need for
|
||||||
native development:
|
cloud native development:
|
||||||
|
|
||||||
1. Services are loosely coupled during development and deployed independently
|
1. Services are loosely coupled during development and deployed independently
|
||||||
on a variety of platforms (Kubernetes, VMs, SaaS or FaaS).
|
on a variety of platforms (Kubernetes, VMs, SaaS or FaaS).
|
||||||
|
|
@ -18,143 +18,171 @@ The above concerns are consistent with the
|
||||||
a common specification for cross-service interoperability being developed by the
|
a common specification for cross-service interoperability being developed by the
|
||||||
CNCF Serverless WG.
|
CNCF Serverless WG.
|
||||||
|
|
||||||
> **Note**: The Eventing repo is very much a work-in-progress. See the
|
To enable delivery to multiple types of Services, Knative Eventing defines two
|
||||||
> [list of Known Issues](https://github.com/knative/eventing/issues?q=is%3Aissue+is%3Aopen+label%3A%22Known+Issue%22)
|
generic interfaces which multiple Kubernetes resources can implement:
|
||||||
> with the current state, but feel free to report additional issues. Expect to
|
|
||||||
> see changes in all of the following areas in the next months:
|
|
||||||
>
|
|
||||||
> 1. The API model and terminology is still evolving.
|
|
||||||
> 1. The controller model for Buses and Sources are still being refined.
|
|
||||||
> 1. Test coverage is not up to snuff.
|
|
||||||
> 1. The release packaging is still being determined.
|
|
||||||
|
|
||||||
Once these concerns are resolved, we expect to work on creating a wider array of
|
1. **Addressable** objects are able to receive and acknowledge an event
|
||||||
EventSources.
|
delivered over HTTP to an address defined in their `status.address.hostname`
|
||||||
|
field. As a special case, the core
|
||||||
|
[Kubernetes Service object](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#service-v1-core)
|
||||||
|
also fulfils the Addressable interface.
|
||||||
|
2. **Callable** objects are able to receive an event delivered over HTTP and
|
||||||
|
transform the event, returning 0 or 1 new events in the HTTP response. These
|
||||||
|
returned events may be further processed in the same way that events from an
|
||||||
|
external event source are processed.
|
||||||
|
|
||||||
|
Knative Eventing also defines a single event forwarding and persistence layer,
|
||||||
|
called a **Channel**. Messaging implementations may provide implementations of
|
||||||
|
Channels via the ClusterChannelProvisioner object. This allows message delivery
|
||||||
|
in a cluster to vary based on requirements, so that some events might be handled
|
||||||
|
by an in-memory implementation while others would be persisted using Kafka or
|
||||||
|
NATS Streaming.
|
||||||
|
|
||||||
|
The focus for the next Eventing release will be to enable easy implementation of
|
||||||
|
event sources. Sources manage registration and delivery of events from external
|
||||||
|
systems using Kubernetes
|
||||||
|
[Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
You can install Knative Eventing with the following command:
|
You can install the core Knative Eventing (which provides an in-memory
|
||||||
|
ChannelProvisioner) and the core sources (which provides the Kubernetes Events
|
||||||
|
and "Container" Sources) with the following commands:
|
||||||
|
|
||||||
|
<!-- TODO(evankanderson): Switch to a numbered release when available. -->
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release.yaml
|
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release.yaml
|
||||||
|
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing-sources/latest/release.yaml
|
||||||
```
|
```
|
||||||
|
|
||||||
In addition to the core definitions, you'll need to install at least one
|
In addition to the core sources, you can also use GCP PubSub as a source with
|
||||||
EventSource and one Bus to have a useful cluster. See below for more information
|
the following yaml:
|
||||||
on how to install different versions of these components.
|
|
||||||
|
|
||||||
> A note on naming: We track the
|
```bash
|
||||||
> [CloudEvents nomenclature](https://github.com/cloudevents/spec/blob/master/spec.md)
|
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing-sources/latest/release-with-gcppubsub.yaml.yaml
|
||||||
> where possible. Much of the naming in this area is in flux, however and many
|
```
|
||||||
> of the needed terms are outside of the current scope of the specification.
|
|
||||||
|
This document will be updated as additional sources (which are custom resource
|
||||||
|
definitions and an associated controller) and channels
|
||||||
|
(ClusterChannelProvisioners and controllers) become available.
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
In order to subdivide the problem, we have split the server-side components into
|
The eventing infrastructure supports two forms of event delivery at the moment:
|
||||||
three abstractions:
|
|
||||||
|
|
||||||
|
1. Direct delivery from a source to a single Service. In this case, the Source
|
||||||
|
is responsible for retrying or queueing events if the destination Service is
|
||||||
|
not available.
|
||||||
|
2. Fan-out delivery from a source or Service response to multiple endpoints
|
||||||
|
using Channels and Subscriptions. In this case, the Channel implementation
|
||||||
|
ensures that messages are delivered to the requested destinations and should
|
||||||
|
buffer the events if the destination Service is unavailable.
|
||||||
|
|
||||||
### Buses
|
|
||||||
|
|
||||||
Buses provide a k8s-native abstraction over message buses like
|
The actual message forwarding is implemented by multiple data plane components
|
||||||
[NATS](https://nats.io) or [Kafka](https://kafka.apache.org/). At this level,
|
which provide observability, persistence, and translation between different
|
||||||
the abstraction is basically publish-subscribe; events are published to a
|
messaging protocols.
|
||||||
Channel, and Subscriptions route that Channel to interested parties.
|
|
||||||
|
|
||||||
- **Channel** is a network endpoint which receives (and optionally persists)
|
|
||||||
events using a Bus-specific implementation.
|
|
||||||
- **Subscription** connects events received on a Channel to an interested
|
|
||||||
`target`, represented as a DNS name. There may be multiple Subscriptions on a
|
|
||||||
single channel.
|
|
||||||
- **Bus** defines the adaptation layers needed to implement channels and
|
|
||||||
subscriptions using a specific persistence strategy (such as delivery of
|
|
||||||
events to a Kafka topic).
|
|
||||||
|
|
||||||
We currently have 3 buses implemented:
|
<!-- TODO(evankanderson): add documentation for Kafka bus once it is available. -->
|
||||||
|
|
||||||
- [Stub](https://github.com/knative/eventing/tree/master/pkg/buses/stub)
|
## Sources
|
||||||
provides a zero-dependency in-memory transport.
|
|
||||||
```bash
|
|
||||||
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release-bus-stub.yaml
|
|
||||||
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release-clusterbus-stub.yaml
|
|
||||||
```
|
|
||||||
- [Kafka](https://github.com/knative/eventing/tree/master/pkg/buses/kafka) uses
|
|
||||||
an existing (user-provided) Kafka cluster for persistence.
|
|
||||||
```bash
|
|
||||||
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release-bus-kafka.yaml
|
|
||||||
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release-clusterbus-kafka.yaml
|
|
||||||
```
|
|
||||||
- [GCP PubSub](https://github.com/knative/eventing/tree/master/pkg/buses/gcppubsub)
|
|
||||||
uses Google Cloud PubSub for message persistence.
|
|
||||||
```bash
|
|
||||||
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release-bus-gcppubsub.yaml
|
|
||||||
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release-clusterbus-gcppubsub.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sources
|
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.
|
||||||
|
Knative Eventing defines the following Sources in the
|
||||||
|
`sources.eventing.knative.dev` API group. Types below are declared in golang
|
||||||
|
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`.
|
||||||
|
|
||||||
Sources provide a similar abstraction layer for provisioning data sources from
|
### KubernetesEventSource
|
||||||
outside Kubernetes and routing them to the cluster, expressed as a Feed
|
|
||||||
(typically, to a Channel on a Bus, but could also be directly to another
|
|
||||||
endpoint). Right now, we only have a few generic Sources, but we plan to add
|
|
||||||
more interesting and specific Sources over time.
|
|
||||||
|
|
||||||
- **Feed** is a primitive object defining a connection between an EventType and
|
The KubernetesEventSource fires a new event each time a
|
||||||
the action (as an
|
[Kubernetes Event](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#event-v1-core)
|
||||||
[CloudEvents compatible HTTP endpoint](https://github.com/cloudevents/spec/blob/master/http-transport-binding.md)).
|
is created or updated.
|
||||||
- **EventType** and **ClusterEventType** describe a specific set of events with a
|
|
||||||
common schema which are emitted by an EventSource. EventType is
|
|
||||||
namespace-scoped, while ClusterEventTypes are installed by an administrator
|
|
||||||
and available in all namespaces in your cluster.
|
|
||||||
- **EventSource** and **ClusterEventSource** describe an external system which
|
|
||||||
may produce one or more EventTypes.
|
|
||||||
|
|
||||||
We currently have 3 sources implemented:
|
**Spec fields**:
|
||||||
|
|
||||||
- [K8sevents](https://github.com/knative/eventing/tree/master/pkg/sources/k8sevents)
|
- `namespace`: `string` The namespace to watch for events.
|
||||||
collects
|
- `serviceAccountname`: `string` The name of the ServiceAccount used to connect
|
||||||
[Kubernetes Events](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/#event-v1-core)
|
to the Kubernetes apiserver.
|
||||||
and presents them as CloudEvents.
|
- `sink`:
|
||||||
```bash
|
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
|
||||||
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release-source-k8sevents.yaml
|
A reference to the object that should receive events.
|
||||||
```
|
|
||||||
- [GitHub](https://github.com/knative/eventing/tree/master/pkg/sources/github)
|
|
||||||
collects pull request notifications and presents them as CloudEvents.
|
|
||||||
```bash
|
|
||||||
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release-source-github.yaml
|
|
||||||
```
|
|
||||||
- [GCP PubSub](https://github.com/knative/eventing/tree/master/pkg/sources/gcppubsub)
|
|
||||||
collects events published to a GCP PubSub topic and presents them as
|
|
||||||
CloudEvents.
|
|
||||||
```bash
|
|
||||||
kubectl apply --filename https://storage.googleapis.com/knative-releases/eventing/latest/release-source-gcppubsub.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
### Flows
|
### GitHubSource
|
||||||
|
|
||||||
Lastly, we have a higher-level abstraction called a Flow which bundles up the
|
The GitHubSource fires a new event for selected
|
||||||
specification from the Source to the endpoint, optionally allowing you to choose
|
[GitHub event types](https://developer.github.com/v3/activity/events/types/).
|
||||||
the Channel and Bus which the event is routed over. (Otherwise, there is a
|
|
||||||
default Bus used to provision a Channel.)
|
|
||||||
|
|
||||||
- **Flow** is the top-level user-facing concept in Eventing; it describes the
|
**Spec fields**:
|
||||||
desired path from an external Source of events to a destination that will
|
|
||||||
react to the events. There is only a single type of Flow, which is installed
|
|
||||||
by the core Knative Eventing install.
|
|
||||||
|
|
||||||
## Supporting Libraries
|
- `ownerAndRepository`: `string` The GitHub owner/org and repository to receive
|
||||||
|
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 used to access
|
||||||
|
the `gcpCredsSecret`.
|
||||||
|
- `sink`:
|
||||||
|
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
|
||||||
|
A reference to the object that should receive events.
|
||||||
|
|
||||||
In addition to the above, there is a golang library at
|
### GcpPubSubSource
|
||||||
[`pkg/event`](https://github.com/knative/eventing/tree/master/pkg/event) for
|
|
||||||
handling CloudEvents and easily creating a container which processes CloudEvents
|
The GcpPubSubSource fires a new event each time a message is published on a
|
||||||
delivered over HTTP. You can look at several of the samples for usage examples.
|
[Google Cloud Platform PubSub topic](https://cloud.google.com/pubsub/).
|
||||||
|
|
||||||
|
**Spec fields**:
|
||||||
|
|
||||||
|
- `googleCloudProject`: `string` The GCP project ID that owns the topic.
|
||||||
|
- `topic`: `string` The name of the PubSub topic.
|
||||||
|
- `serviceAccountName`: `string` The name of the ServiceAccount used to access
|
||||||
|
the `gcpCredsSecret`.
|
||||||
|
- `gcpCredsSecret`:
|
||||||
|
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
|
||||||
|
A reference to a Secret which contains a GCP refresh token for talking to
|
||||||
|
PubSub.
|
||||||
|
- `sink`:
|
||||||
|
[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#objectreference-v1-core)
|
||||||
|
A reference to the object that should receive events.
|
||||||
|
|
||||||
|
### 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. Any `--sink=` argument will be
|
||||||
|
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.
|
||||||
|
|
||||||
## Getting Started
|
## Getting Started
|
||||||
|
|
||||||
- [Setup Knative Serving](../install/README.md)
|
- [Setup Knative Serving](../install/README.md)
|
||||||
- [Install Eventing components](#installation)
|
- [Install Eventing components](#installation)
|
||||||
- [Run samples](samples)
|
- [Run samples](samples/)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
Loading…
Reference in New Issue