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

#4017: Editing for Kafka ResetOffset example (#4019) 

* #4017: Editing for Kafka ResetOffset example

* remove comment

* Update docs/eventing/samples/kafka/resetoffset/README.md

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

* Update docs/eventing/samples/kafka/resetoffset/README.md

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

* Update docs/eventing/samples/kafka/resetoffset/README.md

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

* Update docs/eventing/samples/kafka/resetoffset/README.md

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

* Update docs/eventing/samples/kafka/resetoffset/README.md

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

* Update docs/eventing/samples/kafka/resetoffset/README.md

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

Co-authored-by: Samia Nneji <snneji@vmware.com>
This commit is contained in:
Ashleigh Brennan 2021-07-23 06:07:44 -05:00 committed by GitHub
parent ba628b1a90
commit 4c38a5eea4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 45 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
config/nav.yml
View File

@ -213,6 +213,7 @@ nav:
- Overview: eventing/samples/kafka/README.md - Overview: eventing/samples/kafka/README.md
- Binding Example: eventing/samples/kafka/binding/README.md - Binding Example: eventing/samples/kafka/binding/README.md
- Channel Example: eventing/samples/kafka/channel/README.md - Channel Example: eventing/samples/kafka/channel/README.md
- ResetOffset Example: eventing/samples/kafka/resetoffset/README.md
- Parallel: - Parallel:
- Overview: eventing/samples/parallel/README.md - Overview: eventing/samples/parallel/README.md
- Multiple Cases: eventing/samples/parallel/multiple-branches/README.md - Multiple Cases: eventing/samples/parallel/multiple-branches/README.md

97
docs/eventing/samples/kafka/resetoffset/README.md
View File

@ -1,91 +1,82 @@
--- # ResetOffset Example
title: "Apache Kafka ResetOffset Example"
linkTitle: "ResetOffset Example"
weight: 20
type: "docs"
---
Kafka backed Channels are potentially different from other implementations in Kafka-backed Channels differ from other Channel implementations because they provide temporal persistence of events.
that they provide temporal persistence of events. This capability allows for
certain advanced use cases to be supported, including the ability to "replay"
prior events via repositioning the current location in the event-stream. This
capability can be extremely useful when attempting to recover from unexpected
Subscriber downtime.
The Event persistence enables certain advanced use cases to be supported, such as the ability to replay prior events by repositioning their current location in the event stream. This feature is useful when attempting to recover from unexpected Subscriber downtime.
[ResetOffset CRD](https://github.com/knative-sandbox/eventing-kafka/tree/main/config/command/resetoffset)
exposes the ability to manipulate the location of the ConsumerGroup Offsets in
the event stream of a given Knative Subscription. Without the ResetOffset CRD
you would be responsible for manually stopping ConsumerGroups and manipulating
Offsets.
!!! note The [ResetOffset custom resource definition (CRD)](https://github.com/knative-sandbox/eventing-kafka/tree/main/config/command/resetoffset) exposes the ability to manipulate the location of the ConsumerGroup Offsets in the event stream of a given Knative Subscription. Without the ResetOffset CRD, you must manually stop ConsumerGroups and manipulate the Offsets.
Repositioning the ConsumerGroup Offsets will impact the event ordering and
is intended for failure recovery scenarios. This capability needs to be used
with caution only after reviewing the CRD documentation linked above.
!!! note !!! note
ResetOffsets are currently only supported by the Distributed KafkaChannel ResetOffsets are currently only supported by the Distributed KafkaChannel
implementation. It is expected that the Consolidated KafkaChannel implementation.
implementation will support them in the near future.
!!! warning
Repositioning the ConsumerGroup Offsets impacts the event ordering and
is intended for failure recovery scenarios. This capability needs to be used
with caution only after reviewing the [CRD documentation](https://github.com/knative-sandbox/eventing-kafka/tree/main/config/command/resetoffset).
## Prerequisites ## Prerequisites
- A Kubernetes cluster with a Knative - A Kubernetes cluster with the [Kafka Channel implementation](https://knative.dev/docs/eventing/channels/channels-crds/) installed.
[Kafka Channel](https://knative.dev/docs/eventing/channels/channels-crds/) - A valid KafkaChannel resource and Subscription exist.
installed.
- A valid KafkaChannel and Subscription exist.
## Examples !!! note
The ResetOffset CRD is a single-use operation, and should be
deleted from the cluster once it has been executed.
The following examples assume a Kubernetes Namespace called `my-namespace` ## Repositioning offsets to the oldest available event
containing a KafkaChannel Subscription named `my-subscription` and should be
updated according to your use case.
### Repositioning the Offsets to the oldest available event The following ResetOffset instance moves the offsets back to the oldest
available event in the Kafka Topic retention window:
The following ResetOffset instance will move the offsets back to the oldest
available event in the Kafka Topic retention window.
```yaml ```yaml
apiVersion: kafka.eventing.knative.dev/v1alpha1 apiVersion: kafka.eventing.knative.dev/v1alpha1
kind: ResetOffset kind: ResetOffset
metadata: metadata:
name: my-resetoffset name: <resetoffset-name>
namespace: my-namespace namespace: <namespace>
spec: spec:
offset: offset:
time: earliest time: earliest
ref: ref:
apiVersion: messaging.knative.dev/v1 apiVersion: messaging.knative.dev/v1
kind: Subscription kind: Subscription
namespace: my-namespace namespace: <subscription-namespace>
name: my-subscription name: <subscription-name>
``` ```
### Repositioning the Offsets to a specific point in the event stream Where:
The following ResetOffset instance will move the offsets back to the specified - `<resetoffset-name>` is the name of the ResetOffset CRD.
point in the Kafka Topic retention window. You will need to set an appropriate - `<namespace>` is the namespace where you want to create the ResetOffset CRD.
[RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp relative to - `<subscription-namespace>` is the namespace where your Subscription exists.
your use case. - `<subscription-name>` is the name of the Subscription.
## Repositioning offsets to a specific point in the event stream
The following ResetOffset instance moves the offsets back to the specified
point in the Kafka Topic retention window.
```yaml ```yaml
apiVersion: kafka.eventing.knative.dev/v1alpha1 apiVersion: kafka.eventing.knative.dev/v1alpha1
kind: ResetOffset kind: ResetOffset
metadata: metadata:
name: my-resetoffset name: <resetoffset-name>
namespace: my-namespace namespace: <namespace>
spec: spec:
offset: offset:
time: "2021-06-17T17:30:00Z" time: <offset-time>
ref: ref:
apiVersion: messaging.knative.dev/v1 apiVersion: messaging.knative.dev/v1
kind: Subscription kind: Subscription
namespace: my-namespace namespace: <subscription-namespace>
name: my-subscription name: <subscription-name>
``` ```
!!! note Where:
The ResetOffset CRD is a single use operation or "command", and should be
deleted from the cluster once it has completed execution. - `<resetoffset-name>` is the name of the ResetOffset CRD.
- `<offset-time>` is the specified offset time. You will need to set an [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp relative to your use case, for example `"2021-06-17T17:30:00Z"`.
- `<namespace>` is the namespace where you want to create the ResetOffset CRD.
- `<subscription-namespace>` is the namespace where your Subscription exists.
- `<subscription-name>` is the name of the Subscription.