From 4f66f78fdef005cfb29f2e1271b6875425c40de7 Mon Sep 17 00:00:00 2001 From: Lukas Berk Date: Thu, 25 Jul 2019 11:18:57 -0400 Subject: [PATCH 1/3] Update Channel Spec to reference cloudevents v0.3 --- docs/spec/channel.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/spec/channel.md b/docs/spec/channel.md index a5806cc87b4..ce681841632 100644 --- a/docs/spec/channel.md +++ b/docs/spec/channel.md @@ -124,7 +124,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 @@ -143,9 +143,9 @@ Broker ingress verification, which is being 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,14 +174,14 @@ 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 From 83d860e3d78c7c2b90f74f1ab45435dac3d25dbd Mon Sep 17 00:00:00 2001 From: Lukas Berk Date: Thu, 25 Jul 2019 12:13:48 -0400 Subject: [PATCH 2/3] Channel Spec, small updates from suggestions on first iteration --- docs/spec/channel.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/spec/channel.md b/docs/spec/channel.md index ce681841632..5b31b1d6baf 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 @@ -139,7 +140,8 @@ 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 From 2076ec159be70d30440dd737e6369e5fb420716a Mon Sep 17 00:00:00 2001 From: Lukas Berk Date: Thu, 25 Jul 2019 12:33:43 -0400 Subject: [PATCH 3/3] Channels, first attempt at metrics spec --- docs/spec/channel.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/spec/channel.md b/docs/spec/channel.md index 5b31b1d6baf..77aa9925b00 100644 --- a/docs/spec/channel.md +++ b/docs/spec/channel.md @@ -189,3 +189,14 @@ 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.