knative
/
docs
mirror of https://github.com/knative/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[mkdocs] Fully document channels.messaging.knative.dev (#3650) 

* moving Richard's Changes into MkDocs Branch

* formatting

* Update mkdocs.yml

* Update mkdocs.yml

* Update mkdocs.yml

* Fixes #3650

* Update docs/eventing/channels/create-default-channel.md

Co-authored-by: Samia Nneji <snneji@vmware.com>

* bringing back the purple

* Revert "bringing back the purple"

This reverts commit a6af055288.

* Fixes #3650

* Update docs/eventing/channels/channel-types-defaults.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/channels/channel-types-defaults.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/channels/channel-types-defaults.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/channels/channel-types-defaults.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/channels/channel-types-defaults.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/channels/channel-types-defaults.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/channels/create-default-channel.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/channels/subscriptions.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/channels/subscriptions.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/channels/subscriptions.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Update docs/eventing/channels/channel-types-defaults.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

* Fixes #3650

* Removed lines from webhook example

* Added newline

Co-authored-by: RichardJJG <rijohnson@vmware.com>
Co-authored-by: Samia Nneji <snneji@vmware.com>
Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>
This commit is contained in:
Omer B 2021-07-06 09:45:20 -04:00 committed by GitHub
parent e34db85f67
commit 3c64e9f409
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 179 additions and 148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
docs/eventing/channels/channel-types-defaults.md
View File

@ -1,21 +1,38 @@
---
title: "Channel types and defaults"
weight: 60
type: "docs"
showlandingtoc: "true"
---
# Channel types and defaults
Knative uses two types of Channels:
Knative provides the InMemoryChannel channel implementation by default. This default implementation is useful for developers who do not want to configure a specific implementation type, such as Apache Kafka or NATSS channels.
!!! info
InMemoryChannel channels should not be used in production environments.
* A generic Channel object.
* Channel implementations that each have their own custom resource definitions (CRDs), such as
InMemoryChannel and KafkaChannel.
The default channel implementation is specified in the `default-ch-webhook` ConfigMap in the `knative-eventing` namespace.
For more information about modifying ConfigMaps, see [Configuring the Eventing Operator custom resource](../../../install/operator/configuring-eventing-cr).
Custom Channel implementations each have their own event delivery mechanisms, such as in-memory
or Broker-based. Examples of Brokers include KafkaBroker and the GCP Pub/Sub Broker.
In the following example, the cluster default channel implementation is InMemoryChannel, while the namespace default channel implementation for the `example-namespace` is KafkaChannel.
Knative provides the InMemoryChannel Channel implementation by default.
This default implementation is useful for developers who do not want to configure a specific
implementation type, such as Apache Kafka or NATSS Channels.
You can use the generic Channel object if you want to create a Channel without specifying which
Channel implementation CRD is used.
This is useful if you do not care about the properties a particular Channel implementation provides,
such as ordering and persistence, and you want to use the implementation selected by the cluster
administrator.
Cluster administrators can modify the default Channel implementation settings by editing the `default-ch-webhook` ConfigMap in the `knative-eventing` namespace.
For more information about modifying ConfigMaps, see
[Configuring the Eventing Operator custom resource](/admin/install/operator/configuring-eventing-cr/#setting-a-default-channel).
Default Channels can be configured for the cluster, a namespace on the cluster, or both.
!!! note
If a default Channel implementation is configured for a namespace, this will overwrite the configuration for the cluster.
In the following example, the cluster default Channel implementation is InMemoryChannel, while the
namespace default Channel implementation for the `example-namespace` is KafkaChannel.
```yaml
apiVersion: v1
@ -37,11 +54,12 @@ data:
replicationFactor: 1
```
Default channels can be configured for the cluster, a namespace on the cluster, or both.
!!! info
If a default channel implementation is configured for a namespace, this will overwrite the configuration for the cluster.
!!! note
InMemoryChannel Channels must not be used in production environments.
## Next steps
- Create an [InMemoryChannel](../create-default-channel)

8
docs/eventing/channels/channels-crds.md
View File

@ -1,12 +1,4 @@
---
title: "Available Channels"
#linkTitle: "Channels"
weight: 100
type: "docs"
---
# Available Channels
<!--
This is a generated file and should not be changed manually. All changes should follow the
procedure:

96
docs/eventing/channels/create-default-channel.md
View File

@ -1,49 +1,67 @@
---
title: "Creating a channel using cluster or namespace defaults"
linktitle: "Creating channels"
weight: 65
type: "docs"
showlandingtoc: "true"
---
# Creating a Channel using cluster or namespace defaults
# Creating a channel using cluster or namespace defaults
Developers can create Channels of any supported implementation type by creating an instance of a
Channel object.
Developers can create channels of any supported implementation type by creating an instance of a Channel object.
To create a Channel:
1. Create a Channel object:
* Create a [Channel object](https://knative.dev/docs/reference/api/eventing/#messaging.knative.dev/v1.Channel) by running:
```yaml
apiVersion: messaging.knative.dev/v1
kind: Channel
metadata:
name: my-channel
namespace: default
```
```yaml
kubectl apply -f <<EOF
apiVersion: messaging.knative.dev/v1
kind: Channel
metadata:
name: <example-channel>
namespace: <namespace>
EOF
```
Where:
Since this object is created in the `default` namespace, according to the default ConfigMap example in the previous section, it will be an InMemoryChannel channel implementation.
<!--TODO: Add tabs for kn etc-->
* `<example-channel>` is the name of the Channel you want to create.
* `<namespace>` is the name of your target namespace.
2. After the Channel object is created, a mutating admission webhook sets the
`spec.channelTemplate` based on the default channel implementation:
If you create this object in the `default` namespace, according to the default ConfigMap
example in [Channel types and defaults](/eventing/channels/channel-types-defaults), it is an
InMemoryChannel Channel implementation.
```yaml
apiVersion: messaging.knative.dev/v1
kind: Channel
metadata:
name: my-channel
namespace: default
spec:
channelTemplate:
apiVersion: messaging.knative.dev/v1
kind: InMemoryChannel
```
!!! info
The `spec.channelTemplate` property cannot be changed after creation, since it is set by the default channel mechanism, not the user.
<!-- TODO: Add tabs for kn etc-->
3. The channel controller creates a backing channel instance
based on the `spec.channelTemplate`.
After the Channel object is created, a mutating admission webhook sets the `spec.channelTemplate`
based on the default Channel implementation:
When this mechanism is used, two objects are created, a generic Channel object, and an InMemoryChannel object. The generic object acts as a proxy for the InMemoryChannel object, by copying its subscriptions to and setting its status to that of the InMemoryChannel object.
```yaml
apiVersion: messaging.knative.dev/v1
kind: Channel
metadata:
name: <example-channel>
namespace: <namespace>
spec:
channelTemplate:
apiVersion: messaging.knative.dev/v1
kind: <channel-template-kind>
```
Where:
!!! info
Defaults only apply on object creation. Defaults are applied by the webhook only on Channel 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.
* `<example-channel>` is the name of the Channel you want to create.
* `<namespace>` is the name of your target namespace.
* `<channel-template-kind>` is the kind of Channel, such as InMemoryChannel or KafkaChannel,
based on the default ConfigMap. See an example in [Channel types and defaults](/eventing/channels/channel-types-defaults).
!!! note
The `spec.channelTemplate` property cannot be changed after creation, because it is
set by the default Channel mechanism, not the user.
The Channel controller creates a backing Channel instance based on the `spec.channelTemplate`.
When this mechanism is used two objects are created; a generic Channel object and an
InMemoryChannel object. The generic object acts as a proxy for the InMemoryChannel object
by copying its Subscriptions to, and setting its status to, that of the InMemoryChannel
object.
!!! note
Defaults are only applied by the webhook when a Channel or Sequence is initially created.
If the default settings are changed, the new defaults will only be applied to newly created
Channels, Brokers, or Sequences. Existing resources are not updated automatically to use the new
configuration.

173
docs/eventing/channels/subscriptions.md
View File

@ -1,139 +1,142 @@
---
title: "Subscriptions"
weight: 100
type: "docs"
showlandingtoc: "false"
---
# Subscriptions
After you have created a channel and a sink, you can create a subscription to enable event delivery.
After you have created a Channel and a Sink, you can create a Subscription to enable event delivery.
## Creating a subscription
The Subscription consists of a Subscription object, which specifies the Channel and the Sink (also
known as the Subscriber) to deliver events to. You can also specify some Sink-specific options, such
as how to handle failures.
For more information about Subscription objects, see
[Subscription](https://knative.dev/docs/reference/api/eventing/#messaging.knative.dev/v1.Subscription).
## Creating a Subscription
=== "kn"
Create a subscription between a channel and a sink:
Create a Subscription between a Channel and a Sink by running:
```
kn subscription create <subscription_name> \
--channel <Group:Version:Kind>:<channel_name> \
--sink <sink_prefix>:<sink_name> \
--sink-reply <sink_prefix>:<sink_name> \
--sink-dead-letter <sink_prefix>:<sink_name>
kn subscription create <subscription-name> \
--channel <Group:Version:Kind>:<channel-name> \
--sink <sink-prefix>:<sink-name> \
--sink-reply <sink-prefix>:<sink-name> \
--sink-dead-letter <sink-prefix>:<sink-name>
```
- `--channel` specifies the source for cloud events that should be processed.
You must provide the Channel name. If you are not using the default Channel that is backed by the
Channel resource, you must prefix the Channel name with the `<Group:Version:Kind>` for the
specified Channel type.
For example, this is `messaging.knative.dev:v1beta1:KafkaChannel` for a Kafka-backed Channel.
- `--channel` specifies the source for cloud events that should be processed. You must provide the channel name. If you are not using the default channel that is backed by the Channel resource, you must prefix the channel name with the `<Group:Version:Kind>` for the specified channel type. For example, this will be `messaging.knative.dev:v1beta1:KafkaChannel` for a Kafka backed channel.
- `--sink` specifies the target destination to which the event should be delivered. By default, the `<sink_name>` is interpreted as a Knative service of this name, in the same namespace as the subscription. You can specify the type of the sink by using one of the following prefixes:
- `--sink` specifies the target destination to which the event should be delivered.
By default, the `<sink-name>` is interpreted as a Knative service of this name, in the same
namespace as the Subscription.
You can specify the type of the Sink by using one of the following prefixes:
- `ksvc`: A Knative service.
- `svc`: A Kubernetes Service.
- `channel`: A channel that should be used as destination. Only default channel types can be referenced here.
- `broker`: An Eventing broker.
\
&nbsp;
- `--sink-reply` and `--sink-dead-letter` are optional arguments. They can be used to specify where the sink reply will be sent to, and where to send the cloud event in case of a failure, respectively. Both use the same naming conventions for specifying the sink as the `--sink` flag.
- `channel`: A Channel that should be used as the destination. You can only reference default
Channel types here.
- `broker`: An Eventing Broker.
- `--sink-reply` is an optional argument you can use to specify where the Sink reply is sent.
It uses the same naming conventions for specifying the Sink as the `--sink` flag.
- `--sink-dead-letter` is an optional argument you can use to specify where to send the
CloudEvent in case of a failure. It uses the same naming conventions for specifying the Sink
as the `--sink` flag.
Example command:
```
kn subscription create mysubscription --channel mychannel --sink ksvc:myservice
```
- `ksvc`: A Knative service.
- `svc`: A Kubernetes Service.
- `channel`: A Channel that should be used as destination. Only default Channel types can be referenced here.
- `broker`: An Eventing Broker.
- `--sink-reply` and `--sink-dead-letter` are optional arguments. They can be used to specify where the Sink reply is sent, and where to send the CloudEvent in case of a failure, respectively. Both use the same naming conventions for specifying the Sink as the `--sink` flag.
This example command creates a channel named `mysubscription`, that routes events from a channel named `mychannel` to a Knative service named `myservice`.
!!! info
The sink prefix is optional. It is also possible to specify the service for `--sink` as just `--sink <service_name>` and omit the `ksvc` prefix.
This example command creates a Channel named `mysubscription` that routes events from a Channel
named `mychannel` to a Knative service named `myservice`.
!!! note
The Sink prefix is optional. You can also specify the service for `--sink` as just
`--sink <service-name>` and omit the `ksvc` prefix.
=== "YAML"
Create a Subscription object in a YAML file:
1. Create a Subscription object in a YAML file:
```yaml
```yaml
kubectl apply -f <<EOF
apiVersion: messaging.knative.dev/v1
kind: Subscription
metadata:
name: <subscription-name> # Name of the Subscription.
namespace: default
spec:
channel:
apiVersion: messaging.knative.dev/v1
kind: Subscription
metadata:
name: <subscription_name> # Name of the subscription.
namespace: default
spec:
channel:
apiVersion: messaging.knative.dev/v1
kind: Channel
name: <channel_name> # Configuration settings for the channel that the subscription connects to.
delivery:
deadLetterSink:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: <service_name>
# Configuration settings for event delivery.
# This tells the subscription what happens to events that cannot be delivered to the subscriber.
# When this is configured, events that failed to be consumed are sent to the deadLetterSink.
# The event is dropped, no re-delivery of the event is attempted, and an error is logged in the system.
# The deadLetterSink value must be a Destination.
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: <service_name> # Configuration settings for the subscriber. This is the event sink that events are delivered to from the channel.
```
1. Apply the YAML file:
```
kubectl apply -f <filename>
```
kind: Channel
name: <channel-name> # Configuration settings for the Channel that the Subscription connects to.
delivery:
deadLetterSink:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: <service-name>
# Configuration settings for event delivery.
# This tells the Subscription what happens to events that cannot be delivered to the Subscriber.
# When this is configured, events that failed to be consumed are sent to the deadLetterSink.
# The event is dropped, no re-delivery of the event is attempted, and an error is logged in the system.
# The deadLetterSink value must be a Destination.
subscriber:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: <service-name> # Configuration settings for the Subscriber. This is the event Sink that events are delivered to from the Channel.
EOF
```
## Listing Subscriptions
You can list all existing Subscriptions by using the `kn` CLI tool.
## Listing subscriptions
You can list all existing subscriptions by using the `kn` CLI tool.
- List all subscriptions:
- List all Subscriptions:
```
kn subscription list
```
- List subscriptions in YAML format:
- List Subscriptions in YAML format:
```
kn subscription list -o yaml
```
## Describing a subscription
## Describing a Subscription
You can print details about a subscription by using the `kn` CLI tool:
You can print details about a Subscription by using the `kn` CLI tool:
```
kn subscription describe <subscription_name>
kn subscription describe <subscription-name>
```
<!--TODO: Add an example command and output-->
<!--TODO: Add details for kn subscription update - existing generated docs weren't clear enough, need better explained examples-->
<!--TODO: Add details for kn Subscription update - existing generated docs weren't clear enough, need better explained examples-->
## Deleting subscriptions
You can delete a subscription by using the `kn` or `kubectl` CLI tools.
## Deleting Subscriptions
You can delete a Subscription by using the `kn` or `kubectl` CLI tools.
=== "kn"
```
kn subscription delete <subscription_name>
kn subscription delete <subscription-name>
```
=== "kubectl"
```
kubectl subscription delete <subscription_name>
kubectl subscription delete <subscription-name>
```
## Next steps
- [Creating a Channel using cluster or namespace defaults](/eventing/channels/create-default-channel)