Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify that only a Channel is subscribable #4

Closed
wants to merge 5 commits into from
Closed

Clarify that only a Channel is subscribable #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8746992
Clarify that only a Channel is subscribeable
scothis Oct 11, 2018
bda77a0
remove reference that Source has subscriptions
matzew Oct 15, 2018
e4922e6
Merge pull request #1 from matzew/rm-subscribeable
scothis Oct 15, 2018
befda6f
Adding some clarification 1:1 Source/Channel, and adding fanout examp…
matzew Oct 15, 2018
f502206
Merge pull request #2 from matzew/one_channel_per_source_clarification
scothis Oct 15, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 0 additions & 21 deletions docs/spec/interfaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,27 +6,6 @@

---

## Subscribable

A **Subscribable** resource will emit events that one or more _Subscription_
can direct to their configured destination.

### Control Plane

A **Subscribable** resource may be referenced in the _from_ field of a
_Subscription_. The _Subscribable_ resource MUST expose a
_status.subscribable.channelable_ field (an _ObjectReference_). The resource
referenced in the _status.subscribable.channelable_ field MUST be a
_Channelable_ resource; the field MAY refer back to this _Subscribable_ as a
self referenced resource.

### Data Plane

A **Subscribable** resource produces or forwards events via its
_status.subscribable.channelable_ resource.

---

## Channelable

A **Channelable** resource contains a list of subscribers and is responsible
Expand Down
28 changes: 14 additions & 14 deletions docs/spec/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,7 @@ backing implementations (much like the Kubernetes Ingress resource).
- A **Subscription** describes the transformation of an event and optional
forwarding of a returned event.

- A **Source** allows an incoming events from an external system to be
_Subscribable_. A _Subscription_ is used to connect these events to
subsequent processing steps.
- A **Source** emits incoming events to a _Channel_.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is fine as in source always puts things into a channel. However, I think it would be nice if a user wouldn't have to go digging into objects and then cut&paste these Channels around when creating pipelines. Hence the ability to deref, just like with Targetable, we could require a user to go in and at the lowest level just say it's a DNS name, same kind of applies here as in it's not ideal, if we think Targetable is a good concept, this is the same but in reverse.


- A **Channel** provides event persistance and fanout of events from a
well-known input address to multiple outputs described by _Subscriptions_.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think with this change, the drawing in https://docs.google.com/drawings/d/10mmXzDb8S_4_ZG_hcBr7s4HPISyBqcqeJLTXLwkilRc/edit needs update too

Expand All @@ -33,7 +31,6 @@ eventing API defines several resources that can be reduced down to a well
understood contracts. These eventing resource interfaces may be fulfilled by
other Kubernetes objects and then composed in the same way as the concreate
objects. The interfaces are ([Sinkable](interfaces.md#sinkable),
[Subscribable](interfaces.md#subscribable),
[Channelable](interfaces.md#channelable),
[Targetable](interfaces.md#targetable)). For more details, see
[Interface Contracts](interfaces.md).
Expand All @@ -46,9 +43,9 @@ _Channel_) through transformations (such as a Knative Service which processes
CloudEvents over HTTP). A _Subscription_ controller resolves the addresses of
transformations (`call`) and destination storage (`result`) through the
_Targetable_ and _Sinkable_ interface contracts, and writes the resolved
addresses to the _Subscribable_ `from` resource. _Subscriptions_ do not need to
specify both a transformation and a storage destination, but at least one must
be provided.
addresses to the _Channel_ in the `from` reference. _Subscriptions_ do not
need to specify both a transformation and a storage destination, but at least
one must be provided.

All event delivery linkage from a **Subscription** is 1:1 – only a single
`from`, `call`, and `result` may be provided.
Expand All @@ -60,14 +57,17 @@ For more details, see [Kind: Subscription](spec.md#kind-subscription).
**Source** represents incoming events from an external system, such as object
creation events in a specific storage bucket, database updates in a particular
table, or Kubernetes resource state changes. Because a _Source_ represents an
external system, it only produces events (and is therefore _Subscribable_ by
_Subscriptions_). _Source_ may include parameters such as specific resource
names, event types, or credentials which should be used to establish the
connection to the external system. The set of allowed configuration parameters
is described by the _Provisioner_ which is referenced by the _Source_.
external system, it only emits events to a _Channel_. A _Source_ may include `arguments`
such as specific resource names, event types, or credentials which should be used to
establish the connection to the external system. The set of allowed
configuration parameters is described by the _Provisioner_ which is referenced
by the _Source_.

Event selection on a _Source_ is 1:N – a single _Source_ may fan out to
multiple _Subscriptions_.
Every _Source_ has exactly one _Channel_, ensuring that each _Source_ is responsible for a _single_ event delivery.

### Fanout Example

If we take Cloud PubSub as an example, the _Source_ resource would reference the topic name it wants to bind to. The _Provisioner_ for the _Source_ would create a PubSub subscription for it and the _Source_ starts receiving messages. If we also want to bind the **same** PubSub topic to multiple destinations, we will create a new _Source_ for **each** destination. In this model each new _Source_ will create an **independent** PubSub subscription to the **same** topic, ensuring that each Source is responsible for a single event delivery. The actual fanout is now pushed into the Cloud PubSub, yet still is resilient to failed deliveries.

For more details, see [Kind: Source](spec.md#kind-source).

Expand Down
12 changes: 2 additions & 10 deletions docs/spec/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,14 @@ cannot receive events._
| ------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| provisioner\* | ProvisionerReference | The provisioner used to create any backing resources and configuration. | Immutable. |
| arguments | runtime.RawExtension (JSON object) | Arguments passed to the provisioner for this specific source. | Arguments must validate against provisioner's parameters. |
| channel | ObjectRef | Specify an existing channel to use to emit events. If empty, create a new Channel using the cluster/namespace default. | Source will not emit events until channel exists. |
| channel\* | ObjectRef | Specify a Channel to target. | Source will not emit events until channel exists. |

\*: Required

#### Status

| Field | Type | Description | Limitations |
| ------------ | ------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| subscribable | Subscribable | Pointer to a channel which can be subscribed to in order to receive events from this source. | |
| provisioned | []ProvisionedObjectStatus | Creation status of each Channel and errors therein. | It is expected that a Source list all produced Channels. |
| conditions | Conditions | Source conditions. | |

Expand Down Expand Up @@ -98,7 +97,6 @@ Subscription's call parameter._
| Field | Type | Description | Limitations |
| ------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------- |
| sinkable | Sinkable | Address to the endpoint as top-level domain that will distribute traffic over the provided targets from inside the cluster. | |
| subscribable | Subscribable | | |
| conditions | Conditions | Standard Subscriptions | |

##### Conditions
Expand All @@ -125,7 +123,7 @@ Subscription's call parameter._

### group: eventing.knative.dev/v1alpha1

_Describes a linkage between a Subscribable and a Targetable and/or Sinkable._
_Describes a linkage between a Channel and a Targetable and/or Sinkable._

### Object Schema

Expand Down Expand Up @@ -296,12 +294,6 @@ non-controlling OwnerReference on the EventType resources it knows about.

\*: Required

### Subscribable

| Field | Type | Description | Limitations |
| ----------- | --------------- | -------------------------------- | ----------- |
| channelable | ObjectReference | The channel used to emit events. | |

### Channelable

| Field | Type | Description | Limitations |
Expand Down