From a210ee482055ec3683297d85eac9ef1697b066bc Mon Sep 17 00:00:00 2001 From: Gabriele Quaresima Date: Wed, 5 Aug 2026 15:20:37 +0200 Subject: [PATCH 1/3] docs(plugin_configuration): clarify clusterName uniqueness scope The clusterName field is the identity key for a cluster's WAL/backup stream on the Klio server it registers with, but this was only documented as an override field without noting its scope. Two clusters in different namespaces sharing the same clusterName on one server get WAL streaming rejected with a system ID mismatch error, which is safe but previously undocumented. Fixes #40 Signed-off-by: Gabriele Quaresima --- .../web/docs/user/plugin_configuration.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/documentation/web/docs/user/plugin_configuration.md b/documentation/web/docs/user/plugin_configuration.md index 12d9d997..8f77ddd6 100644 --- a/documentation/web/docs/user/plugin_configuration.md +++ b/documentation/web/docs/user/plugin_configuration.md @@ -380,6 +380,27 @@ spec: clusterName: my-custom-cluster-name ``` +:::warning Uniqueness across namespaces +`clusterName` is the sole identity key for a cluster's WAL/backup stream +on the Klio server it is registered with. It must be unique among all +clusters backed by the same Klio server, regardless of the Kubernetes +namespace they live in. Two clusters in different namespaces that share +a `clusterName` on the same server are not a supported configuration: +the second cluster to connect will have its WAL streaming rejected by +the server with an error such as: + +``` +during server-side replication point validation: rpc error: +code = InvalidArgument +desc = invalid system ID, expected "" +``` + +This is expected, safe behavior: the server detects the mismatched +system ID and refuses to mix data from the two clusters. If you hit +this error, check whether another cluster on the same server is +already using the same `clusterName`. +::: + ### Tier 2 configuration Tier 2 provides secondary storage (typically object storage like S3) for From 1bc3f21ca2b22ae5063e6a02c5d5020694452d25 Mon Sep 17 00:00:00 2001 From: Gabriele Quaresima Date: Tue, 11 Aug 2026 14:29:48 +0200 Subject: [PATCH 2/3] docs(plugin_configuration): clarify clusterName reuse across time The uniqueness warning only covered concurrent reuse of clusterName across namespaces. Deleting a cluster and later reusing its clusterName on the same server hits the same system ID mismatch error, since the server has no way to tell the old cluster is gone. Co-authored-by: Hai He Signed-off-by: Gabriele Quaresima --- documentation/web/docs/user/plugin_configuration.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/documentation/web/docs/user/plugin_configuration.md b/documentation/web/docs/user/plugin_configuration.md index 8f77ddd6..ae793d68 100644 --- a/documentation/web/docs/user/plugin_configuration.md +++ b/documentation/web/docs/user/plugin_configuration.md @@ -399,6 +399,11 @@ This is expected, safe behavior: the server detects the mismatched system ID and refuses to mix data from the two clusters. If you hit this error, check whether another cluster on the same server is already using the same `clusterName`. + +This also applies across time: deleting a cluster and later reusing its +`clusterName` on the same server hits the same error, since the server +can't tell the old cluster is gone. Use a different `clusterName` even for +unrelated clusters that reuse a retired one. ::: ### Tier 2 configuration From b769b60ef0bda4ad12150d92bf9e87cba326b987 Mon Sep 17 00:00:00 2001 From: Francesco Canovai Date: Thu, 13 Aug 2026 10:02:41 +0200 Subject: [PATCH 3/3] docs: simplify explanation Signed-off-by: Francesco Canovai --- documentation/web/docs/user/plugin_configuration.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/documentation/web/docs/user/plugin_configuration.md b/documentation/web/docs/user/plugin_configuration.md index ae793d68..075e5f16 100644 --- a/documentation/web/docs/user/plugin_configuration.md +++ b/documentation/web/docs/user/plugin_configuration.md @@ -390,9 +390,7 @@ the second cluster to connect will have its WAL streaming rejected by the server with an error such as: ``` -during server-side replication point validation: rpc error: -code = InvalidArgument -desc = invalid system ID, expected "" +Error: during server-side replication point validation: rpc error: code = InvalidArgument desc = invalid system ID, expected "" ``` This is expected, safe behavior: the server detects the mismatched @@ -400,10 +398,9 @@ system ID and refuses to mix data from the two clusters. If you hit this error, check whether another cluster on the same server is already using the same `clusterName`. -This also applies across time: deleting a cluster and later reusing its -`clusterName` on the same server hits the same error, since the server -can't tell the old cluster is gone. Use a different `clusterName` even for -unrelated clusters that reuse a retired one. +Deleting a cluster and later reusing its `clusterName` on the same +server hits the same error, since the original cluster backups and +WALs will still exist on the Klio server. ::: ### Tier 2 configuration