allow making controllers without finalizers

they aren't necessary if the controller is only managing other resources
which have owner references set properly, and including them when not
necessary can make cleaning things up more annoying (it won't be
possible to delete watched resources if the controller is down, for
instance)

Author: doy-materialize

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "k8s-controller"
-version = "0.7.0"
+version = "0.8.0"
 edition = "2024"
 rust-version = "1.89.0"
 
@@ -17,6 +17,7 @@ kube = { version = "2.0.1", default-features = false, features = ["client"] }
 kube-runtime = "2.0.1"
 rand = "0.9.2"
 serde = "1"
+thiserror = "2.0.17"
 tracing = "0.1"
 
 [dev-dependencies]

src/controller.rs

@@ -1,5 +1,5 @@
 use std::collections::BTreeMap;
-use std::error::Error;
+use std::error::Error as _;
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
@@ -14,6 +14,14 @@ use kube_runtime::watcher;
 use rand::{Rng, rng};
 use tracing::{Level, event};
 
+#[derive(Debug, thiserror::Error)]
+pub enum Error<E: std::error::Error + 'static> {
+    #[error("{0}")]
+    ControllerError(#[source] E),
+    #[error("{0}")]
+    FinalizerError(#[source] kube_runtime::finalizer::Error<E>),
+}
+
 /// The [`Controller`] watches a set of resources, calling methods on the
 /// provided [`Context`] when events occur.
 pub struct Controller<Ctx: Context>
@@ -36,7 +44,6 @@ impl<Ctx: Context> Controller<Ctx>
 where
     Ctx: Send + Sync + 'static,
     Ctx::Error: Send + Sync + 'static,
-    Ctx::Resource: Send + Sync + 'static,
     Ctx::Resource: Clone + std::fmt::Debug + serde::Serialize,
     for<'de> Ctx::Resource: serde::Deserialize<'de>,
     <Ctx::Resource as Resource>::DynamicType:
@@ -213,15 +220,18 @@ where
 pub trait Context {
     /// The type of Kubernetes [resource](Resource) that will be watched by
     /// the [`Controller`] this context is passed to
-    type Resource: Resource;
+    type Resource: Resource + Send + Sync + 'static;
     /// The error type which will be returned by the [`apply`](Self::apply)
-    /// and [`cleanup`](Self::apply) methods
+    /// and [`cleanup`](Self::cleanup) methods
     type Error: std::error::Error;
 
     /// The name to use for the finalizer. This must be unique across
     /// controllers - if multiple controllers with the same finalizer name
     /// run against the same resource, unexpected behavior can occur.
-    const FINALIZER_NAME: &'static str;
+    ///
+    /// If this is None (the default), a finalizer will not be used, and
+    /// cleanup events will not be reported.
+    const FINALIZER_NAME: Option<&'static str> = None;
 
     /// This method is called when a watched resource is created or updated.
     /// The [`Client`] used by the controller is passed in to allow making
@@ -243,11 +253,19 @@ pub trait Context {
     /// be performed, otherwise if `None` is returned,
     /// [`success_action`](Self::success_action) will be called to find the
     /// action to perform.
+    ///
+    /// Note that this method will only be called if a finalizer is used.
     async fn cleanup(
         &self,
         client: Client,
         resource: &Self::Resource,
-    ) -> Result<Option<Action>, Self::Error>;
+    ) -> Result<Option<Action>, Self::Error> {
+        // use a better name for the parameter name in the docs
+        let _client = client;
+        let _resource = resource;
+
+        Ok(Some(Action::await_change()))
+    }
 
     /// This method is called when a call to [`apply`](Self::apply) or
     /// [`cleanup`](Self::cleanup) returns `Ok(None)`. It should return the
@@ -271,7 +289,7 @@ pub trait Context {
     fn error_action(
         self: Arc<Self>,
         resource: Arc<Self::Resource>,
-        err: &kube_runtime::finalizer::Error<Self::Error>,
+        err: &Error<Self::Error>,
         consecutive_errors: u32,
     ) -> Action {
         // use a better name for the parameter name in the docs
@@ -290,7 +308,7 @@ pub trait Context {
         client: Client,
         api: Api<Self::Resource>,
         resource: Arc<Self::Resource>,
-    ) -> Result<Action, kube_runtime::finalizer::Error<Self::Error>>
+    ) -> Result<Action, Error<Self::Error>>
     where
         Self: Send + Sync + 'static,
         Self::Error: Send + Sync + 'static,
@@ -307,11 +325,8 @@ pub trait Context {
         let dynamic_type = Default::default();
         let kind = Self::Resource::kind(&dynamic_type).into_owned();
         let mut ran = false;
-        let res = finalizer(
-            &api,
-            Self::FINALIZER_NAME,
-            Arc::clone(&resource),
-            |event| async {
+        let res = if let Some(finalizer_name) = Self::FINALIZER_NAME {
+            finalizer(&api, finalizer_name, Arc::clone(&resource), |event| async {
                 ran = true;
                 event!(
                     Level::INFO,
@@ -339,9 +354,27 @@ pub trait Context {
                         .unwrap_or_else(Action::await_change),
                 };
                 Ok(action)
-            },
-        )
-        .await;
+            })
+            .await
+            .map_err(Error::FinalizerError)
+        } else {
+            ran = true;
+            event!(
+                Level::INFO,
+                resource_name = %resource.name_unchecked().as_str(),
+                "Reconciling {} (apply).",
+                kind,
+            );
+            let action = self
+                .apply(client, &resource)
+                .await
+                .map_err(Error::ControllerError)?;
+            Ok(if let Some(action) = action {
+                action
+            } else {
+                self.success_action(&resource)
+            })
+        };
         if !ran {
             event!(
                 Level::INFO,

src/lib.rs

@@ -89,7 +89,7 @@
 //!     type Resource = Pod;
 //!     type Error = kube::Error;
 //!
-//!     const FINALIZER_NAME: &'static str = "example.com/pod-counter";
+//!     const FINALIZER_NAME: Option<&'static str> = Some("example.com/pod-counter");
 //!
 //!     async fn apply(
 //!         &self,
@@ -137,7 +137,7 @@
 //! # impl k8s_controller::Context for PodCounter {
 //! #     type Resource = Pod;
 //! #     type Error = kube::Error;
-//! #     const FINALIZER_NAME: &'static str = "example.com/pod-counter";
+//! #     const FINALIZER_NAME: Option<&'static str> = Some("example.com/pod-counter");
 //! #     async fn apply(
 //! #         &self,
 //! #         client: Client,