Default channel for CRDs documentation

docs/eventing/channels/default-channels.md

@@ -5,132 +5,98 @@ weight: 2
 type: "docs"
 ---
 
+A channel provides an event delivery mechanism that can fan-out received events to multiple destinations. 
 The default channel configuration allows channels to be created without
-specifying a provisioner. This leaves the selection of channel provisioner and
-properties up to the operator. The operator controls the default settings via a
-ConfigMap.
+specifying an underlying implementation. This is useful for users that do not care about the properties a particular 
+channel provides (e.g., ordering, persistence, etc.), but are rather fine with using the  
+implementation selected by the the operator. The operator controls the default settings via a `ConfigMap`. 
+For example, when `Brokers` or `Sequences` are created, an operator can configure a default channel to use 
+for their underlying channel-based implementations.
 
-## Creating a default channel
+Even though this default channel mechanism aims to ease the usability of the system, users can still create their own 
+channels directly by instantiating one of the supported channel objects (e.g., `InMemoryChannel`, `KafkaChannel`, etc.).
 
-To create a default channel, leave the `spec.provisioner` property blank. The
-`spec` property must be provided, but should be empty.
-
-_The content of `spec.arguments` will be cleared for default channels._
+## Setting the default channel configuration
 
-This is a valid default channel:
+The default channel configuration is specified in the `ConfigMap` named
+`default-ch-webhook` in the `knative-eventing` namespace. This `ConfigMap`
+may specify a cluster-wide default channel and namespace-specific
+channel implementations.
 
-```yaml
-apiVersion: eventing.knative.dev/v1alpha1
-kind: Channel
-metadata:
-  name: default-channel
-  namespace: default
-spec: {}
-```
+_The namespace-specific defaults override the cluster default for channels
+created in the specified namespace._
 
-When the above Channel is created, a mutating admission webhook sets
-`spec.provisioner` based on the default provisioner chosen by the operator.
+_Note that default channel spec fields can also be specified._
 
-For example, if the default provisioner is named `default-provisioner`:
+The default options are specified like this:
 
 ```yaml
-apiVersion: eventing.knative.dev/v1alpha1
-kind: Channel
+apiVersion: v1
+kind: ConfigMap
 metadata:
-  name: default-channel
-  namespace: default
-spec:
-  provisioner:
-    apiversion: eventing.knative.dev/v1alpha1
-    kind: ClusterChannelProvisioner
-    name: default-provisioner
+  name: default-ch-webhook
+  namespace: knative-eventing
+data:
+  default-ch-config: |
+    clusterDefault:
+      apiVersion: messaging.knative.dev/v1alpha1
+      kind: InMemoryChannel
+    namespaceDefaults:
+      some-namespace:
+        apiVersion: messaging.knative.dev/v1alpha1
+        kind: KafkaChannel
+        spec:
+          numPartitions: 2
+          replicationFactor: 1
 ```
 
-### Caveats
+Namespace-specific defaults take precedence over cluster defaults when matched.
 
-#### Arguments cannot be specified by default channels
+## Creating a channel with cluster or namespace defaults
 
-Currently (v0.3), default channels do not support specifying arguments. If
-`spec.arguments` is set when creating a default channel, it will be cleared.
-Arguments for default channels may be supported in future versions.
+To create a channel using the cluster or namespace defaults set by the operator, create a generic `Channel` custom object. 
+This is typically useful if you do not care what kind of channel it is, and if you are comfortable using the ones that 
+the operator has selected for you.
 
-For example:
+For example, this is a valid `Channel` object:
 
 ```yaml
-apiVersion: eventing.knative.dev/v1alpha1
+apiVersion: messaging.knative.dev/v1alpha1
 kind: Channel
 metadata:
-  name: default-channel
+  name: my-channel
   namespace: default
-spec:
-  arguments:
-    foo: bar
 ```
 
-Creating the above channel will produce this result:
+When the above `Channel` is created, a mutating admission webhook sets `spec.channelTemplate` based on the default channel 
+implementation chosen by the operator. The `Channel` controller will then create the backing channel instance based on 
+that `spec.channelTemplate`. The `spec.channelTemplate` property cannot be changed after creation, and it will be normally 
+set by the default channel mechanism instead of the user.
+
+For example, this is the output when the default channel is set using the above `ConfigMap` configuration:
 
 ```yaml
-apiVersion: eventing.knative.dev/v1alpha1
+apiVersion: messaging.knative.dev/v1alpha1
 kind: Channel
 metadata:
-  name: default-channel
+  name: my-channel
   namespace: default
 spec:
-  provisioner:
-    apiversion: eventing.knative.dev/v1alpha1
-    kind: ClusterChannelProvisioner
-    name: default-provisioner
+  channelTemplate:
+    apiVersion: messaging.knative.dev/v1alpha1
+    kind: InMemoryChannel
 ```
 
-## Setting the default channel configuration
-
-The default channel configuration is specified in the ConfigMap named
-`default-channel-webhook` in the `knative-eventing` namespace. This ConfigMap
-may specify a cluster-wide default channel provisioner and namespace-specific
-channel provisioners.
-
-_The namespace-specific defaults override the cluster default for channels
-created in the specified namespace._
-
-_Currently (v0.3) default channel arguments cannot be specified, so all default
-channels will have empty arguments. Arguments may be supported in future
-versions._
-
-The default options are specified like this:
-
-```yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: default-channel-webhook
-  namespace: knative-eventing
-data:
-  default-channel-config: |
-    clusterdefault:
-      apiversion: eventing.knative.dev/v1alpha1
-      kind: ClusterChannelProvisioner
-      name: in-memory-channel
-    namespacedefaults:
-      some-namespace:
-        apiversion: eventing.knative.dev/v1alpha1
-        kind: ClusterChannelProvisioner
-        name: some-other-provisioner
-```
-
-Namespace-specific default take precedence when matched. In the above example, a
-Channel created in the `some-namespace` namespace will receive the
-`some-other-provisioner` provisioner, not the `in-memory-channel` provisioner.
-
-### Caveats
-
-#### Defaults only apply on channel creation
+When this mechanism is used, two objects are created, a generic `Channel` and an `InMemoryChannel` channel. 
+The former acts as a proxy of the latter: it copies its subscriptions to the `InMemoryChannel` one and sets its `status`
+with the backing `InMemoryChannel` `status`. 
 
-Defaults are applied by the webhook on Channel creation only. If the default
-settings change, the new defaults will apply to newly-created channels only.
-Existing channels will not change.
+Further, note that as the `Channel` was created in the `default` namespace, it uses the cluster defaults, i.e., `InMemoryChannel`. 
+If the `Channel` would have been created in the `some-namespace` namespace, it would have been backed by an underlying 
+`KafkaChannel` instead (i.e., the default for that namespace).
 
-#### Default channel arguments cannot be specified
+## Defaults only apply on object creation
 
-Because the `default-channel-webhook` ConfigMap doesn't allow for specifying
-default arguments, all default channels will have empty arguments, even if they
-were initially specified in the create request.
+Defaults are applied by the webhook only on `Channel`, `Broker`, or `Sequence` creation. If the default
+settings change, the new defaults will only apply to newly-created channels, brokers, or sequences.
+Existing ones will not change.