You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by sx...@apache.org on 2025/10/10 08:46:15 UTC
(flink-agents) branch release-0.1 updated: [doc] Add Consistency Guarantee section in deployment documentation. (#269)
This is an automated email from the ASF dual-hosted git repository.
sxnan pushed a commit to branch release-0.1
in repository https://gitbox.apache.org/repos/asf/flink-agents.git
The following commit(s) were added to refs/heads/release-0.1 by this push:
new 726a70c [doc] Add Consistency Guarantee section in deployment documentation. (#269)
726a70c is described below
commit 726a70c067b7844d54455f10f27658aa075f5b84
Author: Xuannan <su...@gmail.com>
AuthorDate: Fri Oct 10 16:42:29 2025 +0800
[doc] Add Consistency Guarantee section in deployment documentation. (#269)
---
docs/content/docs/operations/configuration.md | 6 +++---
docs/content/docs/operations/deployment.md | 26 ++++++++++++++++++++++++++
2 files changed, 29 insertions(+), 3 deletions(-)
diff --git a/docs/content/docs/operations/configuration.md b/docs/content/docs/operations/configuration.md
index 16e454d..688ed7e 100644
--- a/docs/content/docs/operations/configuration.md
+++ b/docs/content/docs/operations/configuration.md
@@ -299,11 +299,11 @@ VectorStore built-in configuration options work only with the VectorStore define
| ChromaVectorStore.collection | "flink_agents_chroma_collection" | String | Name of the ChromaDB collection to use. |
| ChromaVectorStore.create_collection_if_not_exists | true | Boolean | Whether to create the collection if it doesn't exist. |
-### State Store
+### Action State Store
-#### Kafka-based State Store
+#### Kafka-based Action State Store
-Here is the configuration options for Kafka-based State Store.
+Here are the configuration options for Kafka-based Action State Store.
| Key | Default | Type | Description |
|-------------------------------------|--------------------------|---------|-----------------------------------------------------------------------------|
diff --git a/docs/content/docs/operations/deployment.md b/docs/content/docs/operations/deployment.md
index f4a0748..76036b6 100644
--- a/docs/content/docs/operations/deployment.md
+++ b/docs/content/docs/operations/deployment.md
@@ -153,3 +153,29 @@ Currently, to resolve the classloader issue, user should place the Flink Agents
Now you should see a Flink job submitted to the Flink Cluster in Flink web UI (typically accessible at http://<jobmanagerHost>:8081).
+
+
+## Consistency Guarantees
+
+Flink Agents leverage Flink’s checkpointing to provide **exactly-once output consistency**. Exactly-once output consistency does not mean each event is processed only once; it means that every event will affect the state and output result exactly once. This is sufficient for typical data-processing use cases where the processing of data does not cause any external side effects.
+
+However, actions in Flink Agents can trigger external side effects (for example, sending an email or invoking an external API). These side effects should not be executed more than once. To address this, Flink Agents support **exactly-once action consistency** by leveraging an external action state store.
+
+### Exactly-Once Output Consistency
+
+When a job runs on a Flink cluster, Flink periodically takes checkpoints. See [Flink Checkpointing](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/ops/state/checkpoints/) for details.
+After recovery from a checkpoint, Flink Agents reprocess events that arrived after that checkpoint. As a result, any actions triggered by those events may be executed again.
+
+### Exactly-Once Action Consistency
+
+To ensure exactly-once action consistency, you must configure an external action state store. Flink Agents record action state in this store on a per-action basis. After recovering from a checkpoint, Flink Agents consult the external store and will not re-execute actions that were already completed. This guarantees each action is executed exactly once after recovering from a checkpoint.
+
+{{< hint info >}}
+**Note**: Currently, Kafka is supported as the external action state store.
+{{< /hint >}}
+
+See [Action State Store Configuration]({{< ref "docs/operations/configuration#action-state-store" >}}) for configuration options.
+
+{{< hint info >}}
+**Note**: Exactly-once action consistency is guaranteed only if, after recovering from the same checkpoint, inputs for each key arrive in the same order as before recovery. If this ordering requirement is not met, the system falls back to exactly-once output consistency.
+{{< /hint >}}