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

Add Subscription docs with kn commands (#3306) 

* Add Subscription docs with kn commands

* cleaned up fluff, fixed links

* peer review update

* SME review updates
This commit is contained in:
Ashleigh Brennan 2021-03-09 11:58:25 -06:00 committed by GitHub
parent d548b54f42
commit 14d9079635
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 349 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
docs/eventing/_index.md
View File

@ -3,6 +3,138 @@ title: "Knative Eventing"
linkTitle: "Eventing Component"
weight: 60
type: "docs"
aliases:
- /eventing/README
---
{{% readfile file="README.md" %}}
Knative Eventing is a system that is designed to address a common need for cloud
native development and provides composable primitives to enable late-binding
event sources and event consumers.
## Getting Started
- [Install Knative](../install)
- [Run samples](./samples/)
- [Default Channels](./channels/default-channels) provide a way to choose the
persistence strategy for Channels across the cluster.
## Functionality
Knative Eventing supports multiple modes of usage. The following scenarios are
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) 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
published.** Use a [trigger](./triggers) to consume events from a Broker based
on CloudEvents attributes. Your application will receive the events as an
HTTP POST.
1. **I want to transform events through a series of steps.** Use [channels and
subscriptions](./channels) to define complex message-passing topologies. For
simple pipelines, the [Sequence](./flows/sequence) automates construction of
channels and subscriptions between each stage.
Knative also supports some additional patterns such as
[Parallel](./flows/parallel) fanout of events, and routing response events from
both Channels and Brokers.
## Design overview
Knative Eventing is designed around the following goals:
1. The Knative Eventing resources are loosely coupled. These resources can be
developed and deployed independently on, and across a variety of platforms
(for example Kubernetes, VMs, SaaS or FaaS).
1. Event producers and event consumers are independent. Any producer (or
source), can generate events before there are active event consumers that are
listening. Any event consumer can express interest in an event or class of
events, before there are producers that are creating those events.
1. Other services can be connected to the Eventing system. These services can
perform the following functions:
- Create new applications without modifying the event producer or event
consumer.
- Select and target specific subsets of the events from their producers.
1. Ensure cross-service interoperability. Knative Eventing is consistent with
the
[CloudEvents](https://github.com/cloudevents/spec/blob/master/spec.md#design-goals)
specification that is developed by the
[CNCF Serverless WG](https://lists.cncf.io/g/cncf-wg-serverless).
### Event consumers
To enable delivery to multiple types of Services, Knative Eventing defines two
generic interfaces that can be implemented by multiple Kubernetes resources:
1. **Addressable** objects are able to receive and acknowledge an event
delivered over HTTP to an address defined in their `status.address.url`
field. As a special case, the core
[Kubernetes Service object](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#service-v1-core)
also fulfils the Addressable interface.
1. **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.
### Event sources
To learn about using event sources, see the [event sources](./sources) documentation.
### Event brokers and triggers
Broker and Trigger objects make it easy to filter events based on event
attributes.
A Broker provides a bucket of events which can be selected by attribute. It
receives events and forwards them to subscribers defined by one or more matching
Triggers. Since a Broker implements Addressable, event senders can submit events
to the Broker by POSTing the event to the Broker's `status.address.url`.
A Trigger describes a filter on event attributes which should be delivered to an
Addressable. You can create as many Triggers as necessary.
For most use cases, a single bucket (Broker) per namespace is sufficient, but
there are serveral use cases where multiple buckets (Brokers) can simplify
architecture. For example, separate Brokers for events containing Personally
Identifiable Information (PII) and non-PII events can simplify audit and access
control rules.
![Broker Trigger Diagram](./images/broker-trigger-overview.svg)
### Event registry
Knative Eventing defines an EventType object to make it easier for consumers to
discover the types of events they can consume from Brokers.
The registry consists of a collection of event types. The event types stored in
the registry contain (all) the required information for a consumer to create a
Trigger without resorting to some other out-of-band mechanism.
To learn how to use the registry, see the
[Event Registry documentation](./event-registry).
### Event channels and subscriptions
Knative Eventing also defines an event forwarding and persistence layer, called
a [channel](./channels/).
Each channel is a separate Kubernetes [custom resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
Events are delivered to services or forwarded to other channels
(possibly of a different type) using
[subscriptions](./channels/subscriptions).
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 Apache Kafka or NATS Streaming.
See the [List of Channel implementations](./channels/channels-crds).
### Higher Level eventing constructs
There are cases where you may want to utilize a set of co-operating functions
together and for those use cases, Knative Eventing provides two additional
resources:
1. **[Sequence](./flows/sequence)** provides a way to define an in-order list of functions.
1. **[Parallel](./flows/parallel)** provides a way to define a list of branches for events.

8
docs/eventing/channels/_index.md
View File

@ -7,8 +7,14 @@ aliases:
- /docs/eventing/channels/default-channels
---
Channels are Kubernetes [custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) (CRs) that define a single event forwarding and persistence layer.
Channels are Kubernetes [custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) that define a single event forwarding and persistence layer.
A channel provides an event delivery mechanism that can fan-out received events, through subscriptions, to multiple destinations, or sinks. Examples of sinks include brokers and Knative services.
<img src="images/channel-workflow.png" width="80%">
## Next steps
- Learn about [default available channel types](channel-types-defaults)
- Create a [channel](./create-default-channel)
- Create a [subscription](./subscriptions)

134
docs/eventing/channels/subscriptions.md Normal file
View File

@ -0,0 +1,134 @@
---
title: "Subscriptions"
weight: 100
type: "docs"
showlandingtoc: "false"
---
After you have created a channel and a sink, you can create a subscription to enable event delivery.
## Creating a subscription
{{< tabs name="Creating a subscription" default="kn" >}}
{{% tab name="kn" %}}
Create a subscription between a channel and a sink:
```
kn subscription create <subscription_name> \
--channel <Group:Version:Kind>:<channel_name> \
--sink <sink_prefix>:<sink_name> \
--sink-reply <sink_prefix>:<sink_name> \
--sink-dead-letter <sink_prefix>:<sink_name>
```
- `--channel` specifies the source for cloud events that should be processed. You must provide the channel name. If you are not using the default channel that is backed by the Channel resource, you must prefix the channel name with the `<Group:Version:Kind>` for the specified channel type. For example, this will be `messaging.knative.dev:v1beta1:KafkaChannel` for a Kafka backed channel.
- `--sink` specifies the target destination to which the event should be delivered. By default, the `<sink_name>` is interpreted as a Knative service of this name, in the same namespace as the subscription. You can specify the type of the sink by using one of the following prefixes:
- `ksvc`: A Knative service.
- `svc`: A Kubernetes Service.
- `channel`: A channel that should be used as destination. Only default channel types can be referenced here.
- `broker`: An Eventing broker.
\
&nbsp;
- `--sink-reply` and `--sink-dead-letter` are optional arguments. They can be used to specify where the sink reply will be sent to, and where to send the cloud event in case of a failure, respectively. Both use the same naming conventions for specifying the sink as the `--sink` flag.
Example command:
```
kn subscription create mysubscription --channel mychannel --sink ksvc:myservice
```
This example command creates a channel named `mysubscription`, that routes events from a channel named `mychannel` to a Knative service named `myservice`.
**NOTE:** The sink prefix is optional. It is also possible to specify the service for `--sink` as just `--sink <service_name>` and omit the `ksvc` prefix.
{{< /tab >}}
{{% tab name="YAML" %}}
1. Create a Subscription object in a YAML file:
```yaml
apiVersion: messaging.knative.dev/v1beta1
kind: Subscription
metadata:
name: <subscription_name> # Name of the subscription.
namespace: default
spec:
channel:
apiVersion: messaging.knative.dev/v1
kind: Channel
name: <channel_name> # Configuration settings for the channel that the subscription connects to.
delivery:
deadLetterSink:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: <service_name>
# Configuration settings for event delivery.
# This tells the subscription what happens to events that cannot be delivered to the subscriber.
# When this is configured, events that failed to be consumed are sent to the deadLetterSink.
# The event is dropped, no re-delivery of the event is attempted, and an error is logged in the system.
# The deadLetterSink value must be a Destination.
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: <service_name> # Configuration settings for the subscriber. This is the event sink that events are delivered to from the channel.
```
1. Apply the YAML file:
```
kubectl apply -f <filename>
```
{{< /tab >}} {{< /tabs >}}
## Listing subscriptions
You can list all existing subscriptions by using the `kn` CLI tool.
- List all subscriptions:
```
kn subscription list
```
- List subscriptions in YAML format:
```
kn subscription list -o yaml
```
## Describing a subscription
You can print details about a subscription by using the `kn` CLI tool:
```
kn subscription describe <subscription_name>
```
<!--TODO: Add an example command and output-->
<!--TODO: Add details for kn subscription update - existing generated docs weren't clear enough, need better explained examples-->
## Deleting subscriptions
You can delete a subscription by using the `kn` or `kubectl` CLI tools.
{{< tabs name="Deleting a subscription" default="kn" >}}
{{% tab name="kn" %}}
```
kn subscription delete <subscription_name>
```
{{< /tab >}}
{{% tab name="kubectl" %}}
```
kubectl subscription delete <subscription_name>
```
{{< /tab >}} {{< /tabs >}}

75
docs/eventing/triggers/README.md
View File

@ -1,75 +0,0 @@
A Trigger represents a desire to subscribe to events from a specific Broker.
The `subscriber` value must be a [Destination](https://pkg.go.dev/knative.dev/pkg/apis/duck/v1#Destination).
Simple example which will receive all the events from the given (`default`) broker and
deliver them to Knative Serving service `my-service`:
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
name: my-service-trigger
spec:
broker: default
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: my-service
EOF
```
Simple example which will receive all the events from the given (`default`) broker and
deliver them to the custom path `/my-custom-path` for the Kubernetes service `my-service`:
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
name: my-service-trigger
spec:
broker: default
subscriber:
ref:
apiVersion: v1
kind: Service
name: my-service
uri: /my-custom-path
EOF
```
### Trigger Filtering
Exact match filtering on any number of CloudEvents attributes as well as
extensions are supported. If your filter sets multiple attributes, an event must
have all of the attributes for the Trigger to filter it. Note that we only
support exact matching on string values.
Example:
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
name: my-service-trigger
spec:
broker: default
filter:
attributes:
type: dev.knative.foo.bar
myextension: my-extension-value
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: my-service
EOF
```
The example above filters events from the `default` Broker that are of type
`dev.knative.foo.bar` AND have the extension `myextension` with the value
`my-extension-value`.

76
docs/eventing/triggers/_index.md
View File

@ -4,4 +4,78 @@ weight: 70
type: "docs"
---
{{% readfile file="README.md" %}}
A Trigger represents a desire to subscribe to events from a specific Broker.
The `subscriber` value must be a [Destination](https://pkg.go.dev/knative.dev/pkg/apis/duck/v1#Destination).
Simple example which will receive all the events from the given (`default`) broker and
deliver them to Knative Serving service `my-service`:
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
name: my-service-trigger
spec:
broker: default
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: my-service
EOF
```
Simple example which will receive all the events from the given (`default`) broker and
deliver them to the custom path `/my-custom-path` for the Kubernetes service `my-service`:
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
name: my-service-trigger
spec:
broker: default
subscriber:
ref:
apiVersion: v1
kind: Service
name: my-service
uri: /my-custom-path
EOF
```
### Trigger Filtering
Exact match filtering on any number of CloudEvents attributes as well as
extensions are supported. If your filter sets multiple attributes, an event must
have all of the attributes for the Trigger to filter it. Note that we only
support exact matching on string values.
Example:
```shell
kubectl create -f - <<EOF
apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
name: my-service-trigger
spec:
broker: default
filter:
attributes:
type: dev.knative.foo.bar
myextension: my-extension-value
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: my-service
EOF
```
The example above filters events from the `default` Broker that are of type
`dev.knative.foo.bar` AND have the extension `myextension` with the value
`my-extension-value`.