diff --git a/docs/spec/channel.md b/docs/spec/channel.md index a5806cc87b4..77aa9925b00 100644 --- a/docs/spec/channel.md +++ b/docs/spec/channel.md @@ -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 @@ -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 @@ -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 @@ -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.