Skip to content

Channel spec revisions iterations #1572

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

Merged
knative-prow-robot merged 3 commits into from
Jul 26, 2019
Merged

Channel spec revisions iterations #1572

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4f66f78
Update Channel Spec to reference cloudevents v0.3
lberk Jul 25, 2019
83d860e
Channel Spec, small updates from suggestions on first iteration
lberk Jul 25, 2019
2076ec1
Channels, first attempt at metrics spec
lberk Jul 25, 2019
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
33 changes: 23 additions & 10 deletions docs/spec/channel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,13 @@ Each _Channel Controller_ ensures the required tasks on the backing technology
are applied. In this case a Kafka topic with the desired configuration is being
created, backing all messages from the channel.

#### Aggregated Channelable ClusterRole
#### Aggregated Channelable Manipulator ClusterRole

Every CRD must create a corresponding ClusterRole, that will be aggregated into
the `channelable-manipulator` ClusterRole. This ClusterRole must include
permissions to create, read, patch, and update the CRD's custom objects. Below
is an example for the `KafkaChannel`:
the `channelable-manipulator` ClusterRole. This ClusterRole must
include permissions to create, list, watch, patch, and update the
CRD's custom objects and their status. Below is an example for the
`KafkaChannel`:

```
apiVersion: rbac.authorization.k8s.io/v1
Expand Down Expand Up @@ -124,7 +125,7 @@ exclusively communicate using CloudEvents.

Every Channel must expose either an HTTP or HTTPS endpoint. It MAY expose both.
The endpoint(s) MUST conform to
[HTTP Transport Binding for CloudEvents - Version 0.2](https://github.com/cloudevents/spec/blob/v0.2/http-transport-binding.md).
[HTTP Transport Binding for CloudEvents - Version 0.3](https://github.com/cloudevents/spec/blob/v0.3/http-transport-binding.md).
It MUST support both Binary Content mode and Structured Content mode. The
HTTP(S) endpoint MAY be on any port, not just the standard 80 and 443. Channels
MAY expose other, non-HTTP endpoints in addition to HTTP at their discretion
Expand All @@ -139,13 +140,14 @@ Every event queueing request to the Channel will come with a bearer token,
likely a JWT. The bearer token MUST be validated before any other work is done
on the request. The specifics of how and what to validate will be identical to
Broker ingress verification, which is being
[defined](https://github.com/knative/eventing/issues/705#issuecomment-496722527).
[defined](https://github.com/knative/eventing/issues/705#issuecomment-496722527)
and planned for be formalized as of `v0.8`.

The Channel MUST pass through all tracing information as CloudEvents attributes.
In particular, it MUST translate any incoming OpenTracing or B3 headers to the
[Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v0.2/extensions/distributed-tracing.md).
[Distributed Tracing Extension](https://github.com/cloudevents/spec/blob/v0.3/extensions/distributed-tracing.md).
The Channel SHOULD sample and write traces to the location specified in
[`config-tracing`](https://github.com/cloudevents/spec/blob/v0.2/extensions/distributed-tracing.md).
[`config-tracing`](https://github.com/cloudevents/spec/blob/v0.3/extensions/distributed-tracing.md).

##### HTTP

Expand Down Expand Up @@ -174,16 +176,27 @@ provided bearer token fails to validate, then the Channel must respond with

Channels MUST output CloudEvents. The output MUST be via a binding specified in
the
[CloudEvents specification](https://github.com/cloudevents/spec/tree/v0.2#cloudevents-documents).
[CloudEvents specification](https://github.com/cloudevents/spec/tree/v0.3#cloudevents-documents).
Every Channel MUST support sending events via Structured Content Mode HTTP
Transport Binding.

Channels MUST NOT alter an event that goes through them. All CloudEvent
attributes, including the data attribute, MUST be received at the subscriber
identical to how they were received by the Channel. The only exception is the
[Distributed Tracing Extension Attribute](https://github.com/cloudevents/spec/blob/v0.2/extensions/distributed-tracing.md),
[Distributed Tracing Extension Attribute](https://github.com/cloudevents/spec/blob/v0.3/extensions/distributed-tracing.md),
which is expected to change as the span id will be altered at every network hop.

Channels MUST attach a bearer token to all outgoing requests, likely in the form
of a JWT. This bearer token MUST use an identity associated with the Channel,
not the individual Subscription.

#### Metrics

Channels SHOULD expose a variety of metrics, including, but not limited to:
- Number of malformed incoming event queueing events (`400 Bad Requests` responses)
- Number of unauthorized or malformed bearer token requests (`403 Forbidden` responses)
- Number of accepted incoming event queuing events (`202 Accpeted` responses)
- Number of egress cloudevent produced (with the former metric, used to derive channel queue size)

Metrics SHOULD be enabled by default, but a configuration parameter included to
disable if desired.