From fe366cdeaad3dd7af98ccf6fc21f4f324e5e8dff Mon Sep 17 00:00:00 2001 From: Armando Ruocco Date: Tue, 11 Aug 2026 17:45:47 +0200 Subject: [PATCH 1/3] refactor(operator): drop dead ClusterName defaulting fallback The `PluginConfiguration.spec.clusterName` field has been `Required` with `MinLength=1` since the auto-propagation work, so the API server rejects empty values and the two defaulting branches in klioconfig could no longer fire for any object written through the current CRD. Remove both branches, along with the stale comment claiming the cluster name doubles as the host name. Objects created while the field was still optional (v0.0.7 to v0.0.12) are not revalidated on read, so they can still carry an empty `clusterName`. Those now fail at client configuration validation with `invalid client config: cluster_name is empty` instead of being silently defaulted; setting `clusterName` on the resource fixes them. Closes #69 Signed-off-by: Armando Ruocco --- operator/internal/klioconfig/config.go | 8 -------- 1 file changed, 8 deletions(-) diff --git a/operator/internal/klioconfig/config.go b/operator/internal/klioconfig/config.go index 04ade284..dbaa0333 100644 --- a/operator/internal/klioconfig/config.go +++ b/operator/internal/klioconfig/config.go @@ -252,9 +252,6 @@ func addExternalClusterConfiguration( return fmt.Errorf("failed to get '%s' configuration, error: %w", ref, err) } - if klioPluginConfiguration.Spec.ClusterName == "" { - klioPluginConfiguration.Spec.ClusterName = serverName - } configurations[serverName].klioPluginConfiguration = klioPluginConfiguration return nil @@ -312,11 +309,6 @@ func getArchivePluginConfigurations( return configurations, fmt.Errorf("failed to get '%s' configuration, error: %w", ref, err) } - if klioPluginConfiguration.Spec.ClusterName == "" { - // if the host name is not set, use the cluster name as the host name - klioPluginConfiguration.Spec.ClusterName = cluster.Name - } - configurations[ArchiveConfigKey].klioPluginConfiguration = klioPluginConfiguration.DeepCopy() return configurations, nil From 43af34430f99a48ebe47b7f1feef207eaac12fd1 Mon Sep 17 00:00:00 2001 From: Armando Ruocco Date: Wed, 12 Aug 2026 13:55:44 +0200 Subject: [PATCH 2/3] docs: clarify the clusterName constraint The restore example commented `clusterName` as optional, while the field is `Required` with `MinLength=1`, so omitting it is rejected by the API server. Also state explicitly that the value must match the host name in the Common Name of the client certificate, which is the constraint the Kopia client enforces at connection time. Signed-off-by: Armando Ruocco --- documentation/web/docs/user/backup_and_restore.md | 2 +- documentation/web/docs/user/plugin_configuration.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/documentation/web/docs/user/backup_and_restore.md b/documentation/web/docs/user/backup_and_restore.md index d14871cb..8943ce33 100644 --- a/documentation/web/docs/user/backup_and_restore.md +++ b/documentation/web/docs/user/backup_and_restore.md @@ -240,7 +240,7 @@ spec: clientSecretName: my-client-credentials serverSecretName: klio-server-tls - # Optional: specify the original cluster name if different + # Required: the name of the original cluster that was backed up clusterName: my-cluster ``` diff --git a/documentation/web/docs/user/plugin_configuration.md b/documentation/web/docs/user/plugin_configuration.md index 075e5f16..ecc851d2 100644 --- a/documentation/web/docs/user/plugin_configuration.md +++ b/documentation/web/docs/user/plugin_configuration.md @@ -403,6 +403,10 @@ server hits the same error, since the original cluster backups and WALs will still exist on the Klio server. ::: +Whichever value you use, it must match the host name in the Common Name of the +client certificate (`userName@hostName`), otherwise the connection to the Klio +server is refused. + ### Tier 2 configuration Tier 2 provides secondary storage (typically object storage like S3) for From baebd42451f2ebb59ad1784a03f771b8c11d2487 Mon Sep 17 00:00:00 2001 From: Gabriele Quaresima Date: Wed, 12 Aug 2026 15:49:39 +0200 Subject: [PATCH 3/3] docs: correct clusterName certificate-CN mismatch behavior Tier 1 base backups reject a Common Name mismatch at connection time, but WAL streaming has no such check and can silently misroute WALs. Also drops a stale GenerateConfig comment for a removed parameter. Signed-off-by: Gabriele Quaresima --- documentation/web/docs/user/plugin_configuration.md | 6 ++++-- operator/internal/klioconfig/config.go | 1 - 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/documentation/web/docs/user/plugin_configuration.md b/documentation/web/docs/user/plugin_configuration.md index ecc851d2..0ccde4ed 100644 --- a/documentation/web/docs/user/plugin_configuration.md +++ b/documentation/web/docs/user/plugin_configuration.md @@ -404,8 +404,10 @@ WALs will still exist on the Klio server. ::: Whichever value you use, it must match the host name in the Common Name of the -client certificate (`userName@hostName`), otherwise the connection to the Klio -server is refused. +client certificate (`userName@hostName`). For tier 1 base backups, a mismatch +is rejected at connection time; for WAL streaming, a mismatch is not currently +detected and can lead to WALs being stored or retrieved under the wrong +cluster path. ### Tier 2 configuration diff --git a/operator/internal/klioconfig/config.go b/operator/internal/klioconfig/config.go index dbaa0333..89b43d0d 100644 --- a/operator/internal/klioconfig/config.go +++ b/operator/internal/klioconfig/config.go @@ -87,7 +87,6 @@ const ConfigDataKey = "config.yaml" // GenerateConfig builds a config.Data from a PluginConfigurationSpec. // configKey is the configuration key (e.g. "klio-archive"). -// clusterName is the default cluster name when the PC doesn't set one. func GenerateConfig( spec kliov1alpha1.PluginConfigurationSpec, configKey string,