Document default channels for users and operators (#723)

* Document default channels for users and operators

Features described were added in
https://github.com/knative/eventing/pull/580.

* Link to default-channels.md in eventing README

Adds a Configuration heading for topics unrelated to Getting Started.

* Briefly describe default channels in heading

Co-Authored-By: grantr <grantr@gmail.com>

* Update in response to feedback

Better README flow.
Explain why default channels can't have arguments.

eventing/README.md

@@ -90,6 +90,9 @@ This document will be updated as additional sources (which are custom resource
 definitions and an associated controller) and channels
 (ClusterChannelProvisioners and controllers) become available.
 
+Check out the [Configuration](#configuration) section to learn more about
+operating Knative Eventing.
+
 ## Architecture
 
 The eventing infrastructure supports two forms of event delivery at the moment:
@@ -229,6 +232,10 @@ FTP server for new files or generate events at a set time interval.
 - [Install Eventing components](#installation)
 - [Run samples](samples/)
 
+## Configuration
+- [Default Channels](default-channels.md) provide a way to choose the
+persistence strategy for Channels across the cluster.
+
 ---
 
 Except as otherwise noted, the content of this page is licensed under the

eventing/default-channels.md

@@ -0,0 +1,131 @@
+# Default Channels
+
+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.
+
+## Creating a default channel
+
+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._
+
+This is a valid default channel:
+
+```yaml
+apiVersion: eventing.knative.dev/v1alpha1
+kind: Channel
+metadata:
+  name: default-channel
+  namespace: default
+spec: {}
+```
+
+When the above Channel is created, a mutating admission webhook sets
+`spec.provisioner` based on the default provisioner chosen by the operator.
+
+For example, if the default provisioner is named `default-provisioner`:
+
+```yaml
+apiVersion: eventing.knative.dev/v1alpha1
+kind: Channel
+metadata:
+  name: default-channel
+  namespace: default
+spec:
+  provisioner:
+    apiversion: eventing.knative.dev/v1alpha1
+    kind: ClusterChannelProvisioner
+    name: default-provisioner
+```
+
+### Caveats
+
+#### Arguments cannot be specified by default channels
+
+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.
+
+For example:
+
+```yaml
+apiVersion: eventing.knative.dev/v1alpha1
+kind: Channel
+metadata:
+  name: default-channel
+  namespace: default
+spec:
+  arguments:
+    foo: bar
+```
+
+Creating the above channel will produce this result:
+
+```yaml
+apiVersion: eventing.knative.dev/v1alpha1
+kind: Channel
+metadata:
+  name: default-channel
+  namespace: default
+spec:
+  provisioner:
+    apiversion: eventing.knative.dev/v1alpha1
+    kind: ClusterChannelProvisioner
+    name: default-provisioner
+```
+
+## 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
+
+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.
+
+#### Default channel arguments cannot be specified
+
+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.