mirror of https://github.com/knative/docs.git
Default channel for CRDs documentation (#1619)
* Adding bitbucket source documentation. * Adding README example for bitbucket source. * Updating example. * Missed to generate the README * removing stuff, and updating link to bitbucket source in sources.yaml * autogenerating README * removing bitbucket one here. * update * default channels * updates after ville's comments * addressing sam's comments * replacing documents for provisioner-based default channel
This commit is contained in:
Ignacio Cano
Knative Prow Robot
parent
beec8a7eeb
commit
31b5c780c1
|
|
@ -5,96 +5,28 @@ 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
|
||||
|
||||
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
|
||||
```
|
||||
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.).
|
||||
|
||||
## 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 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.
|
||||
|
||||
_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._
|
||||
_Note that default channel spec fields can also be specified._
|
||||
|
||||
The default options are specified like this:
|
||||
|
||||
|
|
@ -102,35 +34,69 @@ The default options are specified like this:
|
|||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: default-channel-webhook
|
||||
name: default-ch-webhook
|
||||
namespace: knative-eventing
|
||||
data:
|
||||
default-channel-config: |
|
||||
clusterdefault:
|
||||
apiversion: eventing.knative.dev/v1alpha1
|
||||
kind: ClusterChannelProvisioner
|
||||
name: in-memory-channel
|
||||
namespacedefaults:
|
||||
default-ch-config: |
|
||||
clusterDefault:
|
||||
apiVersion: messaging.knative.dev/v1alpha1
|
||||
kind: InMemoryChannel
|
||||
namespaceDefaults:
|
||||
some-namespace:
|
||||
apiversion: eventing.knative.dev/v1alpha1
|
||||
kind: ClusterChannelProvisioner
|
||||
name: some-other-provisioner
|
||||
apiVersion: messaging.knative.dev/v1alpha1
|
||||
kind: KafkaChannel
|
||||
spec:
|
||||
numPartitions: 2
|
||||
replicationFactor: 1
|
||||
```
|
||||
|
||||
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.
|
||||
Namespace-specific defaults take precedence over cluster defaults when matched.
|
||||
|
||||
### Caveats
|
||||
## Creating a channel with cluster or namespace defaults
|
||||
|
||||
#### Defaults only apply on channel creation
|
||||
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.
|
||||
|
||||
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.
|
||||
For example, this is a valid `Channel` object:
|
||||
|
||||
#### Default channel arguments cannot be specified
|
||||
```yaml
|
||||
apiVersion: messaging.knative.dev/v1alpha1
|
||||
kind: Channel
|
||||
metadata:
|
||||
name: my-channel
|
||||
namespace: default
|
||||
```
|
||||
|
||||
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.
|
||||
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: messaging.knative.dev/v1alpha1
|
||||
kind: Channel
|
||||
metadata:
|
||||
name: my-channel
|
||||
namespace: default
|
||||
spec:
|
||||
channelTemplate:
|
||||
apiVersion: messaging.knative.dev/v1alpha1
|
||||
 kind: InMemoryChannel
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
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).
|
||||
|
||||
## Defaults only apply on object creation
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue