fix!: Default ListenerClass externalTrafficPolicy to null (#1107)

* chore!: Default ListenerClass externalTrafficPolicy to null

* changelog

* Update crates/stackable-operator/src/crd/listener/class/mod.rs

Co-authored-by: Techassi <git@techassi.dev>

* Update crates/stackable-operator/src/crd/listener/core/mod.rs

* Add dec comment of defaults

* Use patched kube

* Update kube branch

* Update crates/stackable-operator/src/crd/listener/class/mod.rs

Co-authored-by: Techassi <git@techassi.dev>

---------

Co-authored-by: Techassi <git@techassi.dev>

Author: sbernauer

Cargo.lock

@@ -37,7 +37,8 @@ json-patch = "4.0.0"
 k8s-openapi = { version = "0.26.0", default-features = false, features = ["schemars", "v1_34"] }
 # We use rustls instead of openssl for easier portability, e.g. so that we can build stackablectl without the need to vendor (build from source) openssl
 # We use ring instead of aws-lc-rs, as this currently fails to build in "make run-dev"
-kube = { version = "2.0.0", default-features = false, features = ["client", "jsonpatch", "runtime", "derive", "rustls-tls", "ring"] }
+# We pin the kube version, as we use a patch for 2.0.1 below
+kube = { version = "=2.0.1", default-features = false, features = ["client", "jsonpatch", "runtime", "derive", "rustls-tls", "ring"] }
 opentelemetry = "0.31.0"
 opentelemetry_sdk = { version = "0.31.0", features = ["rt-tokio"] }
 opentelemetry-appender-tracing = "0.31.0"
@@ -93,3 +94,6 @@ rsa.opt-level = 3
 [profile.dev.package]
 insta.opt-level = 3
 similar.opt-level = 3
+
+[patch.crates-io]
+kube = { git = "https://github.com/stackabletech/kube-rs", branch = "2.0.1-fix-schema-hoisting" }

Cargo.toml

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Fixed
+
+- BREAKING: Default ListenerClass `.spec.externalTrafficPolicy` to `null` so that LoadBalancers work everywhere ([#1107]).
+
+[#1107]: https://github.com/stackabletech/operator-rs/pull/1107
+
 ## [0.100.1] - 2025-10-23
 
 ### Changed

crates/stackable-operator/CHANGELOG.md

@@ -50,13 +50,26 @@ pub mod versioned {
         #[serde(default)]
         pub service_annotations: BTreeMap<String, String>,
 
-        /// `externalTrafficPolicy` that should be set on the created [`Service`] objects.
+        /// `externalTrafficPolicy` that should be set on the created Service objects.
         ///
-        /// The default is `Local` (in contrast to `Cluster`), as we aim to direct traffic to a node running the workload
-        /// and we should keep testing that as the primary configuration. Cluster is a fallback option for providers that
-        /// break Local mode (IONOS so far).
-        #[serde(default = "ListenerClassSpec::default_service_external_traffic_policy")]
-        pub service_external_traffic_policy: core_v1alpha1::KubernetesTrafficPolicy,
+        /// It is a Kubernetes feature that controls how external traffic is routed to a Kubernetes
+        /// Service.
+        ///
+        /// * `Cluster`: Kubernetes default. Traffic is routed to any node in the Kubernetes cluster that
+        ///   has a pod running the service.
+        /// * `Local`: Traffic is only routed to pods running on the same node as the Service.
+        ///
+        /// The `Local` mode has better performance as it avoids a network hop, but requires a more
+        /// sophisticated LoadBalancer, that respects what Pods run on which nodes and routes traffic only
+        /// to these nodes accordingly. Some cloud providers or bare metal installations do not implement
+        /// some of the required features.
+        //
+        // Please note that Option is used here instead of a different default traffic policy. This will be
+        // deserialized as `None` and will thus forward the selection of the traffic policy to Kubernetes
+        // (which currently defaults to `Cluster`). This should be the most sensible option in most cases.
+        // There is the possibility Kubernetes will automatically choose `Local` if support for it on the
+        // LoadBalancer has been detected.
+        pub service_external_traffic_policy: Option<core_v1alpha1::KubernetesTrafficPolicy>,
 
         /// Whether addresses should prefer using the IP address (`IP`) or the hostname (`Hostname`).
         /// Can also be set to `HostnameConservative`, which will use `IP` for `NodePort` service types, but `Hostname` for everything else.

crates/stackable-operator/crds/AuthenticationClass.yaml

@@ -1,13 +1,9 @@
 use crate::crd::listener::{
     class::v1alpha1::ListenerClassSpec,
-    core::v1alpha1::{AddressType, KubernetesTrafficPolicy, PreferredAddressType},
+    core::v1alpha1::{AddressType, PreferredAddressType},
 };
 
 impl ListenerClassSpec {
-    pub(super) const fn default_service_external_traffic_policy() -> KubernetesTrafficPolicy {
-        KubernetesTrafficPolicy::Local
-    }
-
     pub(super) const fn default_preferred_address_type() -> PreferredAddressType {
         PreferredAddressType::HostnameConservative
     }

crates/stackable-operator/crds/DummyCluster.yaml

@@ -45,6 +45,8 @@ pub mod versioned {
 
         /// Preserves the client source IP and avoid a second hop for LoadBalancer and NodePort type
         /// Services, but makes clients responsible for spreading the load.
+        ///
+        /// Does not work on all Kubernetes installations.
         Local,
     }