feat: Add Scaler CRD

Author: Techassi

crates/stackable-operator/src/crd/mod.rs

@@ -8,6 +8,7 @@ pub mod authentication;
 pub mod git_sync;
 pub mod listener;
 pub mod s3;
+pub mod scaler;
 
 /// A reference to a product cluster (for example, a `ZookeeperCluster`)
 ///

crates/stackable-operator/src/crd/scaler/mod.rs

@@ -0,0 +1,107 @@
+use k8s_openapi::apimachinery::pkg::apis::meta::v1::Time;
+use kube::CustomResource;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+#[cfg(doc)]
+use crate::kvp::Annotation;
+use crate::versioned::versioned;
+
+#[versioned(version(name = "v1alpha1"))]
+pub mod versioned {
+    #[versioned(crd(
+        group = "autoscaling.stackable.tech",
+        status = ScalerStatus,
+        scale(
+            spec_replicas_path = ".spec.replicas",
+            status_replicas_path = ".status.replicas",
+            label_selector_path = ".status.selector"
+        ),
+        namespaced
+    ))]
+    #[derive(Clone, Debug, PartialEq, CustomResource, Deserialize, Serialize, JsonSchema)]
+    pub struct ScalerSpec {
+        /// Desired replica count.
+        ///
+        /// Written by the horizontal pod autoscaling mechanism via the /scale subresource.
+        ///
+        /// NOTE: This and other replica fields)use a [`u16`] instead of a [`i32`] used by
+        /// [`k8s_openapi`] types to force a non-negative replica count. All [`u16`]s can be
+        /// converted losslessly to [`i32`]s where needed.
+        ///
+        /// Upstream issues:
+        ///
+        /// - https://github.com/kubernetes/kubernetes/issues/105533
+        /// - https://github.com/Arnavion/k8s-openapi/issues/136
+        pub replicas: u16,
+    }
+}
+
+/// Status of a StackableScaler.
+#[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct ScalerStatus {
+    /// The current total number of replicas targeted by the managed StatefulSet.
+    ///
+    /// Exposed via the `/scale` subresource for horizontal pod autoscaling consumption.
+    pub replicas: u16,
+
+    /// Label selector string for HPA pod counting. Written at `.status.selector`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub selector: Option<String>,
+
+    /// The current state of the scaler state machine.
+    pub state: ScalerState,
+
+    /// Timestamp indicating when the scaler state last transitioned.
+    pub last_transition_time: Time,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, JsonSchema, strum::Display)]
+#[serde(rename_all = "camelCase", rename_all_fields = "camelCase")]
+#[strum(serialize_all = "camelCase")]
+pub enum ScalerState {
+    /// No scaling operation is in progress.
+    Idle,
+
+    /// Running the `pre_scale` hook (e.g. data offload).
+    PreScaling,
+
+    /// Waiting for the StatefulSet to converge to the new replica count.
+    ///
+    /// This stage additionally tracks the previous replica count to be able derive the direction
+    /// of the scaling operation.
+    Scaling { previous_replicas: u16 },
+
+    /// Running the `post_scale` hook (e.g. cluster rebalance).
+    ///
+    /// This stage additionally tracks the previous replica count to be able derive the direction
+    /// of the scaling operation.
+    PostScaling { previous_replicas: u16 },
+
+    /// A hook returned an error.
+    ///
+    /// The scaler stays here until the user applies the [`Annotation::autoscaling_retry`] annotation
+    /// to trigger a reset to [`ScalerState::Idle`].
+    Failed {
+        /// Which stage produced the error.
+        failed_in: FailedInState,
+
+        /// Human-readable error message from the hook.
+        reason: String,
+    },
+}
+
+/// Which stage of a scaling operation failed.
+#[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub enum FailedInState {
+    /// The `pre_scale` hook returned an error.
+    PreScaling,
+
+    /// The StatefulSet failed to reach the desired replica count.
+    Scaling,
+
+    /// The `post_scale` hook returned an error.
+    PostScaling,
+}

crates/stackable-operator/src/kvp/annotation/mod.rs

@@ -156,6 +156,16 @@ impl Annotation {
         ))?;
         Ok(Self(kvp))
     }
+
+    /// Constructs a `autoscaling.stackable.tech/retry` annotation.
+    pub fn autoscaling_retry(retry: bool) -> Self {
+        // SAFETY: We use expect here, because the input parameter can only be one of two possible
+        // values: true or false. This fact in combination with the known annotation key length
+        // allows use to use expect here, instead of bubbling up the error.
+        let kvp = KeyValuePair::try_from(("autoscaling.stackable.tech/retry", retry.to_string()))
+            .expect("autoscaling retry annotation must be valid");
+        Self(kvp)
+    }
 }
 
 /// A validated set/list of Kubernetes annotations.

crates/xtask/src/crd/mod.rs

@@ -10,6 +10,7 @@ use stackable_operator::{
             PodListenersVersion,
         },
         s3::{S3Bucket, S3BucketVersion, S3Connection, S3ConnectionVersion},
+        scaler::{Scaler, ScalerVersion},
     },
     kube::core::crd::MergeError,
 };
@@ -77,6 +78,7 @@ pub fn generate_preview() -> Result<(), Error> {
     write_crd!(path, PodListeners, V1Alpha1);
     write_crd!(path, S3Bucket, V1Alpha1);
     write_crd!(path, S3Connection, V1Alpha1);
+    write_crd!(path, Scaler, V1Alpha1);
 
     write_crd!(path, DummyCluster, V1Alpha1);