This is an automated email from the ASF dual-hosted git repository.
mjsax pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new c2743747438 KAFKA-19380: Update
streams/developer-guide/app-reset-tool.html (#20946)
c2743747438 is described below
commit c274374743808545e239984cc49dce1bf7fc3e5f
Author: Alieh Saeedi <[email protected]>
AuthorDate: Thu Nov 27 03:39:00 2025 +0100
KAFKA-19380: Update streams/developer-guide/app-reset-tool.html (#20946)
- created `docs/streams/developer-guide/kafka-streams-group-sh.html`
that lists all available cli commands .
- refered to `docs/streams/developer-guide/kafka-streams-group-sh.html`
from `app-reset-tool.html`
Reviewers: Matthias J. Sax <[email protected]>, Lucas Brutschy
<[email protected]>
---
.../developer-guide/kafka-streams-group-sh.html | 19 ++
docs/streams/developer-guide/app-reset-tool.html | 2 +
docs/streams/developer-guide/index.html | 5 +-
.../developer-guide/kafka-streams-group-sh.html | 278 +++++++++++++++++++++
4 files changed, 300 insertions(+), 4 deletions(-)
diff --git
a/docs/documentation/streams/developer-guide/kafka-streams-group-sh.html
b/docs/documentation/streams/developer-guide/kafka-streams-group-sh.html
new file mode 100644
index 00000000000..e9f8ef73da0
--- /dev/null
+++ b/docs/documentation/streams/developer-guide/kafka-streams-group-sh.html
@@ -0,0 +1,19 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<!-- should always link the latest release's documentation -->
+<!--#include
virtual="../../../streams/developer-guide/kafka-streams-group-sh.html" -->
diff --git a/docs/streams/developer-guide/app-reset-tool.html
b/docs/streams/developer-guide/app-reset-tool.html
index e80f53940a5..63723681735 100644
--- a/docs/streams/developer-guide/app-reset-tool.html
+++ b/docs/streams/developer-guide/app-reset-tool.html
@@ -65,6 +65,8 @@
</dl>
<div class="section" id="step-1-run-the-application-reset-tool">
<h2>Step 1: Run the application reset tool<a class="headerlink"
href="#step-1-run-the-application-reset-tool" title="Permalink to this
headline"></a></h2>
+ <p>If you are using <strong>streams rebalance protocol</strong>
(available since AK 4.2), use the <a href =
"kafka-streams-group-sh.html#reset-offsets">Streams groups CLI</a>.</p>
+ <p>If you are using <strong>classic rebalance protocol</strong>,
run the classic application reset tool as described below.</p>
<p>Invoke the application reset tool from the command line</p>
<p>Warning! This tool makes irreversible changes to your
application. It is strongly recommended that you run this once with <code
class="docutils literal"><span class="pre">--dry-run</span></code> to preview
your changes before making them.</p>
<pre><code class="language-bash">$
bin/kafka-streams-application-reset.sh</code></pre>
diff --git a/docs/streams/developer-guide/index.html
b/docs/streams/developer-guide/index.html
index 19f638ece0d..136dbbfc064 100644
--- a/docs/streams/developer-guide/index.html
+++ b/docs/streams/developer-guide/index.html
@@ -52,14 +52,11 @@
<li class="toctree-l1"><a class="reference internal"
href="manage-topics.html">Managing Streams Application Topics</a></li>
<li class="toctree-l1"><a class="reference internal"
href="security.html">Streams Security</a></li>
<li class="toctree-l1"><a class="reference internal"
href="app-reset-tool.html">Application Reset Tool</a></li>
+<li class="toctree-l1"><a class="reference internal"
href="kafka-streams-group-sh.html">Kafka Streams Groups CLI</a></li>
</ul>
</div>
</div>
-
- </div>
- </div>
-
<div class="pagination">
<a href="/{{version}}/documentation/streams/architecture"
class="pagination__btn pagination__btn__prev">Previous</a>
<a
href="/{{version}}/documentation/streams/developer-guide/write-streams"
class="pagination__btn pagination__btn__next">Next</a>
diff --git a/docs/streams/developer-guide/kafka-streams-group-sh.html
b/docs/streams/developer-guide/kafka-streams-group-sh.html
new file mode 100644
index 00000000000..81496eca672
--- /dev/null
+++ b/docs/streams/developer-guide/kafka-streams-group-sh.html
@@ -0,0 +1,278 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<script><!--#include virtual="../../js/templateData.js" --></script>
+
+<script id="content-template" type="text/x-handlebars-template">
+ <!-- h1>Developer Guide for Kafka Streams</h1 -->
+ <div class="sub-nav-sticky">
+ <div class="sticky-top">
+ <!-- div style="height:35px">
+ <a href="/{{version}}/documentation/streams/">Introduction</a>
+ <a class="active-menu-item"
href="/{{version}}/documentation/streams/developer-guide">Developer Guide</a>
+ <a
href="/{{version}}/documentation/streams/core-concepts">Concepts</a>
+ <a href="/{{version}}/documentation/streams/quickstart">Run Demo
App</a>
+ <a href="/{{version}}/documentation/streams/tutorial">Tutorial:
Write App</a>
+ </div -->
+ </div>
+ </div>
+<div class="everything">
+
+ <div class="container">
+
+ <div id="header">
+ <div class="container">
+ <h1>Kafka Streams Groups Tool (kafka-streams-groups.sh)</h1>
+ <p>Use <code>kafka-streams-groups.sh</code> to manage
<strong>Streams groups</strong> for the Streams Rebalance Protocol (KIP‑1071):
list and describe groups, inspect members and offsets/lag, reset or delete
offsets for input topics, and delete groups (optionally including internal
topics).</p>
+ </div>
+ </div>
+
+ <div class="contents local topic" id="table-of-contents">
+ <p class="topic-title first"><b>Table of Contents</b></p>
+ <ul class="simple">
+ <li><a class="reference internal"
href="#overview">Overview</a></li>
+ <li><a class="reference internal" href="#what-it-does">What
the Streams Groups tool does</a></li>
+ <li><a class="reference internal" href="#usage">Usage</a></li>
+ <li><a class="reference internal"
href="#commands">Commands</a></li>
+ <li><a class="reference internal" href="#options">All options
and flags</a></li>
+ <li><a class="reference internal" href="#best-practices">Best
practices and safety</a></li>
+
+ </ul>
+ </div>
+
+ <div id="overview">
+ <span class="anchor" aria-hidden="true"></span>
+ <h2>Overview</h2>
+ <p>A <strong>Streams group</strong> is a broker‑coordinated group
type for Kafka Streams that uses Streams‑specific RPCs and metadata, distinct
from classic consumer groups. The CLI surfaces Streams‑specific states,
assignments, and input‑topic offsets to simplify visibility and
administration.</p>
+
+ <div class="admonition warning">
+ <strong>Use with care:</strong> Mutating operations (offset
resets/deletes, group deletion) affect how applications will reprocess data
when restarted. Always preview with <span class="kbd">--dry-run</span> before
executing and ensure application instances are stopped/inactive and the group
is empty before executing the command.
+ </div>
+ </div>
+
+ <div id="what-it-does">
+ <span class="anchor" aria-hidden="true"></span>
+ <h2>What the Streams Groups tool does</h2>
+ <ul>
+ <li><strong>List Streams groups</strong> across a cluster and
display or filter by group state (Empty, Not Ready, Assigning, Reconciling,
Stable, Dead).</li>
+
+ <li><strong>Describe a Streams group</strong> and show:
+ <ul>
+ <li>Group state, group epoch, target assignment epoch
(with <code>--state</code>, <code>--verbose</code> for additional details).</li>
+ <li>Per‑member info such as epochs, current vs target
assignments, and whether a member still uses the classic protocol (with
<code>--members</code> and <code>--verbose</code>).</li>
+ <li>Input‑topic offsets and lag (with
<code>--offsets</code>), to understand how far behind processing is.</li>
+ </ul>
+ </li>
+
+ <li><strong>Reset input‑topic offsets</strong> for a Streams
group to control reprocessing boundaries using precise specifiers (earliest,
latest, to‑offset, to‑datetime, by‑duration, shift‑by, from‑file). Requires
<code>--dry-run</code> or <code>--execute</code> and inactive instances.</li>
+
+ <li><strong>Delete offsets</strong> for input topics to force
re‑consumption on next start.</li>
+
+ <li><strong>Delete a Streams group</strong> to clean up
broker‑side Streams metadata (offsets, topology, assignments). Optionally
delete all, or a subset of, <strong>internal topics</strong> at the same time
using <code>--internal-topics</code>.</li>
+ </ul>
+ </div>
+
+ <div id="usage">
+ <span class="anchor" aria-hidden="true"></span>
+ <h2>Usage</h2>
+ <p>The script is located in
<code>bin/kafka-streams-groups.sh</code> and connects to your cluster via
<code>--bootstrap-server</code>. For secured clusters, pass AdminClient
properties using <code>--command-config</code>.</p>
+
+ <pre><code>$ kafka-streams-groups.sh --bootstrap-server
<host:port> [COMMAND] [OPTIONS]</code></pre>
+
+ <div class="admonition note">
+ <strong>Note:</strong> <code>kafka-streams-groups.sh</code>
complements the Streams Admin API for Streams groups. The CLI exposes
list/describe/delete operations and offset management similar in spirit to
consumer-group tools, but tailored to Streams groups defined in KIP‑1071.
+ </div>
+ </div>
+
+ <div id="commands">
+ <span class="anchor" aria-hidden="true"></span>
+ <h2>Commands</h2>
+
+ <div id="list">
+ <h3>List Streams groups</h3>
+ <p>Discovering groups</p>
+ <pre><code># List all Streams groups
+kafka-streams-groups.sh --bootstrap-server localhost:9092 --list
+</code></pre>
+ </div>
+
+ <div id="describe">
+ <h3>Describe Streams groups</h3>
+ <p>Inspecting group's state, members, and lag</p>
+ <pre><code># Describe a group: state + epochs
+kafka-streams-groups.sh --bootstrap-server localhost:9092 \
+ --describe --group my-streams-app --state --verbose
+
+# Describe a group: members (assignments vs target, classic/streams)
+kafka-streams-groups.sh --bootstrap-server localhost:9092 \
+ --describe --group my-streams-app --members --verbose
+
+# Describe a group: input-topic offsets and lag
+kafka-streams-groups.sh --bootstrap-server localhost:9092 \
+ --describe --group my-streams-app --offsets
+</code></pre>
+ </div>
+
+ <div id="reset-offsets">
+ <h3>Reset input-topic offsets (preview, then apply)</h3>
+ <p>Ensure all application instances are stopped/inactive.
Always preview changes with <code>--dry-run</code> before using
<code>--execute</code>.</p>
+ <pre><code># Preview resetting all input topics to a specific
timestamp
+kafka-streams-groups.sh --bootstrap-server localhost:9092 \
+ --group my-streams-app \
+ --reset-offsets --all-input-topics --to-datetime 2025-01-31T23:57:00.000 \
+ --dry-run
+
+# Apply the reset
+kafka-streams-groups.sh --bootstrap-server localhost:9092 \
+ --group my-streams-app \
+ --reset-offsets --all-input-topics --to-datetime 2025-01-31T23:57:00.000 \
+ --execute
+</code></pre>
+ </div>
+
+ <div id="delete-offsets">
+ <h3>Delete offsets to force re-consumption</h3>
+ <p>Delete offsets for all or specific input topics to have the
group re-read data on restart.</p>
+ <pre><code># Delete offsets for all input topics (execute)
+kafka-streams-groups.sh --bootstrap-server localhost:9092 \
+ --group my-streams-app \
+ --delete-offsets --all-input-topics --execute
+
+# Delete offsets for specific topics
+kafka-streams-groups.sh --bootstrap-server localhost:9092 \
+ --group my-streams-app \
+ --delete-offsets --topic input-a --topic input-b --execute
+</code></pre>
+ </div>
+
+ <div id="delete-group">
+ <h3>Delete a Streams group (cleanup)</h3>
+ <p>Delete broker-side Streams metadata for a group and
optionally remove a subset of internal topics.</p>
+ <pre><code># Delete Streams group metadata
+kafka-streams-groups.sh --bootstrap-server localhost:9092 \
+ --delete --group my-streams-app
+
+# Delete a subset of internal topics alongside the group (use with care)
+kafka-streams-groups.sh --bootstrap-server localhost:9092 \
+ --delete --group my-streams-app \
+ --internal-topics my-app-repartition-0,my-app-changelog
+</code></pre>
+ </div>
+ </div>
+
+ <div id="options">
+ <span class="anchor" aria-hidden="true"></span>
+ <h2>All options and flags</h2>
+
+ <div class="options-core">
+ <h3>Core actions</h3>
+ <ul>
+ <li><code>--list</code>: List Streams groups. Use
<code>--state</code> to display/filter by state.</li>
+ <li><code>--describe</code>: Describe a group selected by
<code>--group</code>. Combine with:
+ <ul>
+ <li><code>--state</code> (group state and epochs),
<code>--members</code> (members and assignments), <code>--offsets</code> (input
and repartition topics offsets/lag).</li>
+ <li><code>--verbose</code> for additional details
(e.g., leader epochs where applicable).</li>
+ </ul>
+ </li>
+ <li><code>--reset-offsets</code>: Reset input-topic
offsets (one group at a time; instances should be inactive). Choose exactly one
specifier:
+ <ul>
+ <li><code>--to-earliest</code>,
<code>--to-latest</code>, <code>--to-current</code>, <code>--to-offset
<n></code></li>
+ <li><code>--by-duration <PnDTnHnMnS></code>,
<code>--to-datetime <YYYY-MM-DDTHH:mm:SS.sss></code></li>
+ <li><code>--shift-by <n></code> (±),
<code>--from-file</code> (CSV)</li>
+ </ul>
+ Scope:
+ <ul>
+ <li><code>--all-input-topics</code> or one/more
<code>--topic <name></code>; some builds also support
<code>--all-topics</code> (all input topics per broker topology metadata).</li>
+ </ul>
+ Safety:
+ <ul>
+ <li>Requires <code>--dry-run</code> or
<code>--execute</code>.</li>
+ </ul>
+ </li>
+ <li><code>--delete-offsets</code>: Delete offsets for
<code>--all-input-topics</code>, specific <code>--topic</code> names, or
<code>--from-file</code>.</li>
+ <li><code>--delete</code>: Delete Streams group metadata;
optionally pass <code>--internal-topics <list></code> to delete a subset
of internal topics.</li>
+ </ul>
+ </div>
+
+ <div class="options-common">
+ <h3>Common flags</h3>
+ <ul>
+ <li><code>--group <id></code>: Target Streams group
(application.id).</li>
+ <li><code>--all-groups</code>: Operate on all groups
(allowed with <code>--delete</code>).</li>
+ <li><code>--bootstrap-server <host:port></code>:
Broker(s) to connect to (required).</li>
+ <li><code>--command-config <file></code>: Properties
for AdminClient (security, timeouts, etc.).</li>
+ <li><code>--timeout <ms></code>: Wait time for group
stabilization in some operations (default: 5000ms).</li>
+ <li><code>--dry-run</code>, <code>--execute</code>:
Preview vs apply for mutating operations.</li>
+ <li><code>--help</code>, <code>--version</code>,
<code>--verbose</code>: Usage, version, verbosity.</li>
+ </ul>
+ </div>
+ </div>
+
+ <div id="best-practices">
+ <span class="anchor" aria-hidden="true"></span>
+ <h2>Best practices and safety</h2>
+ <ul>
+ <li>Preview changes with <code>--dry-run</code> to verify
topic scope and impact before <code>--execute</code>.</li>
+ <li>Use <code>--internal-topics</code> carefully: deleting
internal topics removes state backing topics; only do this when you intend to
rebuild state from input topics.</li>
+ </ul>
+ </div>
+
+ <div class="footer">
+ <p>This page documents <code>kafka-streams-groups.sh</code>
capabilities for Streams groups as defined by KIP‑1071 and implemented in
Apache Kafka.</p>
+ </div>
+ </div>
+</div>
+</script>
+<!--#include virtual="../../../includes/_header.htm" -->
+<!--#include virtual="../../../includes/_top.htm" -->
+<div class="content documentation ">
+ <!--#include virtual="../../../includes/_nav.htm" -->
+ <div class="right">
+ <!--//#include virtual="../../../includes/_docs_banner.htm" -->
+ <ul class="breadcrumbs">
+ <li><a href="/documentation">Documentation</a></li>
+ <li><a href="/documentation/streams">Kafka Streams</a></li>
+ <li><a href="/documentation/streams/developer-guide/">Developer
Guide</a></li>
+ </ul>
+ <div class="p-content"></div>
+ </div>
+</div>
+<!--#include virtual="../../../includes/_footer.htm" -->
+<script>
+ $(function() {
+ // Show selected style on nav item
+ $('.b-nav__streams').addClass('selected');
+
+ //sticky secondary nav
+ var $navbar = $(".sub-nav-sticky"),
+ y_pos = $navbar.offset().top,
+ height = $navbar.height();
+
+ $(window).scroll(function() {
+ var scrollTop = $(window).scrollTop();
+
+ if (scrollTop > y_pos - height) {
+ $navbar.addClass("navbar-fixed")
+ } else if (scrollTop <= y_pos) {
+ $navbar.removeClass("navbar-fixed")
+ }
+ });
+
+ // Display docs subnav items
+
$('.b-nav__docs').parent().toggleClass('nav__item__with__subs--expanded');
+ });
+</script>
