|
| 1 | +use std::borrow::Cow; |
| 2 | + |
| 3 | +use k8s_openapi::apimachinery::pkg::apis::meta::v1::Time; |
| 4 | +use kube::CustomResource; |
| 5 | +use schemars::JsonSchema; |
| 6 | +use serde::{Deserialize, Serialize}; |
| 7 | + |
| 8 | +#[cfg(doc)] |
| 9 | +use crate::kvp::Annotation; |
| 10 | +use crate::versioned::versioned; |
| 11 | + |
| 12 | +#[versioned(version(name = "v1alpha1"))] |
| 13 | +pub mod versioned { |
| 14 | + #[versioned(crd( |
| 15 | + group = "autoscaling.stackable.tech", |
| 16 | + status = ScalerStatus, |
| 17 | + scale( |
| 18 | + spec_replicas_path = ".spec.replicas", |
| 19 | + status_replicas_path = ".status.replicas", |
| 20 | + label_selector_path = ".status.selector" |
| 21 | + ), |
| 22 | + namespaced |
| 23 | + ))] |
| 24 | + #[derive(Clone, Debug, PartialEq, CustomResource, Deserialize, Serialize, JsonSchema)] |
| 25 | + pub struct ScalerSpec { |
| 26 | + /// Desired replica count. |
| 27 | + /// |
| 28 | + /// Written by the horizontal pod autoscaling mechanism via the /scale subresource. |
| 29 | + /// |
| 30 | + /// NOTE: This and other replica fields)use a [`u16`] instead of a [`i32`] used by |
| 31 | + /// [`k8s_openapi`] types to force a non-negative replica count. All [`u16`]s can be |
| 32 | + /// converted losslessly to [`i32`]s where needed. |
| 33 | + /// |
| 34 | + /// Upstream issues: |
| 35 | + /// |
| 36 | + /// - https://github.com/kubernetes/kubernetes/issues/105533 |
| 37 | + /// - https://github.com/Arnavion/k8s-openapi/issues/136 |
| 38 | + pub replicas: u16, |
| 39 | + } |
| 40 | +} |
| 41 | + |
| 42 | +/// Status of a StackableScaler. |
| 43 | +#[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)] |
| 44 | +#[serde(rename_all = "camelCase")] |
| 45 | +pub struct ScalerStatus { |
| 46 | + /// The current total number of replicas targeted by the managed StatefulSet. |
| 47 | + /// |
| 48 | + /// Exposed via the `/scale` subresource for horizontal pod autoscaling consumption. |
| 49 | + pub replicas: u16, |
| 50 | + |
| 51 | + /// Label selector string for HPA pod counting. Written at `.status.selector`. |
| 52 | + #[serde(skip_serializing_if = "Option::is_none")] |
| 53 | + pub selector: Option<String>, |
| 54 | + |
| 55 | + /// The current state of the scaler state machine. |
| 56 | + pub state: ScalerState, |
| 57 | + |
| 58 | + /// Timestamp indicating when the scaler state last transitioned. |
| 59 | + pub last_transition_time: Time, |
| 60 | +} |
| 61 | + |
| 62 | +// We use `#[serde(tag)]` and `#[serde(content)]` here to circumvent Kubernetes restrictions in their |
| 63 | +// structural schema subset of OpenAPI schemas. They don't allow one variant to be typed as a string |
| 64 | +// and others to be typed as objects. We therefore encode the variant data in a separate details |
| 65 | +// key/object. With this, all variants can be encoded as strings, while the status can still contain |
| 66 | +// additional data in an extra field when needed. |
| 67 | +#[derive(Clone, Debug, Deserialize, Serialize, strum::Display)] |
| 68 | +#[serde( |
| 69 | + tag = "state", |
| 70 | + content = "details", |
| 71 | + rename_all = "camelCase", |
| 72 | + rename_all_fields = "camelCase" |
| 73 | +)] |
| 74 | +#[strum(serialize_all = "camelCase")] |
| 75 | +pub enum ScalerState { |
| 76 | + /// No scaling operation is in progress. |
| 77 | + Idle, |
| 78 | + |
| 79 | + /// Running the `pre_scale` hook (e.g. data offload). |
| 80 | + PreScaling, |
| 81 | + |
| 82 | + /// Waiting for the StatefulSet to converge to the new replica count. |
| 83 | + /// |
| 84 | + /// This stage additionally tracks the previous replica count to be able derive the direction |
| 85 | + /// of the scaling operation. |
| 86 | + Scaling { previous_replicas: u16 }, |
| 87 | + |
| 88 | + /// Running the `post_scale` hook (e.g. cluster rebalance). |
| 89 | + /// |
| 90 | + /// This stage additionally tracks the previous replica count to be able derive the direction |
| 91 | + /// of the scaling operation. |
| 92 | + PostScaling { previous_replicas: u16 }, |
| 93 | + |
| 94 | + /// A hook returned an error. |
| 95 | + /// |
| 96 | + /// The scaler stays here until the user applies the [`Annotation::autoscaling_retry`] annotation |
| 97 | + /// to trigger a reset to [`ScalerState::Idle`]. |
| 98 | + Failed { |
| 99 | + /// Which stage produced the error. |
| 100 | + failed_in: FailedInState, |
| 101 | + |
| 102 | + /// Human-readable error message from the hook. |
| 103 | + reason: String, |
| 104 | + }, |
| 105 | +} |
| 106 | + |
| 107 | +// We manually implement the JSON schema instead of deriving it, because kube's schema transformer |
| 108 | +// cannot handle the derived JsonSchema and proceeds to hit the following error: "Property "state" |
| 109 | +// has the schema ... but was already defined as ... in another subschema. The schemas for a |
| 110 | +// property used in multiple subschemas must be identical". |
| 111 | +impl JsonSchema for ScalerState { |
| 112 | + fn schema_name() -> Cow<'static, str> { |
| 113 | + "ScalerState".into() |
| 114 | + } |
| 115 | + |
| 116 | + fn json_schema(generator: &mut schemars::generate::SchemaGenerator) -> schemars::Schema { |
| 117 | + schemars::json_schema!({ |
| 118 | + "type": "object", |
| 119 | + "required": ["state"], |
| 120 | + "properties": { |
| 121 | + "state": { |
| 122 | + "type": "string", |
| 123 | + "enum": ["idle", "preScaling", "scaling", "postScaling", "failed"] |
| 124 | + }, |
| 125 | + "details": { |
| 126 | + "type": "object", |
| 127 | + "properties": { |
| 128 | + "failedIn": generator.subschema_for::<FailedInState>(), |
| 129 | + "previous_replicas": { |
| 130 | + "type": "uint16", |
| 131 | + "minimum": u16::MIN, |
| 132 | + "maximum": u16::MAX |
| 133 | + }, |
| 134 | + "reason": { "type": "string" } |
| 135 | + } |
| 136 | + } |
| 137 | + } |
| 138 | + }) |
| 139 | + } |
| 140 | +} |
| 141 | + |
| 142 | +/// In which state the scaling operation failed. |
| 143 | +#[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)] |
| 144 | +#[serde(rename_all = "camelCase")] |
| 145 | +pub enum FailedInState { |
| 146 | + /// The `pre_scale` hook returned an error. |
| 147 | + PreScaling, |
| 148 | + |
| 149 | + /// The StatefulSet failed to reach the desired replica count. |
| 150 | + Scaling, |
| 151 | + |
| 152 | + /// The `post_scale` hook returned an error. |
| 153 | + PostScaling, |
| 154 | +} |
0 commit comments