Skip to main content

hyprstream_k8s/
serving.rs

1//! `serving.hyprstream.io/v1alpha1` — [`InferenceService`].
2//!
3//! Serving intent for a model:branch, with autoscaling bounds and a
4//! statefulness class. The group is DNS-subspaced under `hyprstream.io` so it
5//! never collides with `serving.kserve.io/InferenceService`; KServe is an
6//! optional adapter target (K6b), never the owner of this noun.
7//!
8//! `spec` is desired intent; `status` is observed serving truth.
9
10use kube::CustomResource;
11use schemars::JsonSchema;
12use serde::{Deserialize, Serialize};
13
14/// Statefulness class of a served model, which the serving controller (K6a)
15/// uses to decide autoscaling behaviour.
16#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, Default, JsonSchema)]
17pub enum Statefulness {
18    /// Stateless inference; replicas are freely interchangeable.
19    Stateless,
20    /// Test-Time-Training-stateful: replicas hold per-tenant LoRA deltas, so
21    /// scaling/routing must be TTT-aware (session affinity, drain-before-scale).
22    #[default]
23    TttStateful,
24}
25
26/// Desired state of an [`InferenceService`].
27///
28/// # Validation
29/// - `model` must be non-empty.
30/// - `minReplicas` must be `<= maxReplicas`.
31/// - `maxReplicas` must be `>= 1`.
32#[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)]
33#[kube(
34    group = "serving.hyprstream.io",
35    version = "v1alpha1",
36    kind = "InferenceService",
37    plural = "inferenceservices",
38    singular = "inferenceservice",
39    shortname = "hsisvc",
40    namespaced,
41    status = "InferenceServiceStatus",
42    category = "hyprstream",
43    doc = "Serving intent for a model:branch with autoscaling bounds and a statefulness class. Subspaced under serving.hyprstream.io so it never collides with serving.kserve.io.",
44    printcolumn = r#"{"name":"Model","type":"string","jsonPath":".spec.model"}"#,
45    printcolumn = r#"{"name":"Ready","type":"integer","jsonPath":".status.readyReplicas"}"#,
46    printcolumn = r#"{"name":"URL","type":"string","jsonPath":".status.url"}"#,
47    validation = "self.spec.model != ''",
48    validation = "self.spec.minReplicas <= self.spec.maxReplicas",
49    validation = "self.spec.maxReplicas >= 1",
50    cel
51)]
52#[serde(rename_all = "camelCase")]
53pub struct InferenceServiceSpec {
54    /// Model to serve, in `model:branch` form (branch optional, defaults to the
55    /// promoted ref).
56    pub model: String,
57
58    /// Minimum replica count. `0` permits scale-to-zero for stateless services.
59    #[serde(default)]
60    pub min_replicas: u32,
61
62    /// Maximum replica count. Must be at least `1`.
63    #[serde(default = "default_max_replicas")]
64    pub max_replicas: u32,
65
66    /// Statefulness class driving autoscaling behaviour.
67    #[serde(default)]
68    pub statefulness: Statefulness,
69}
70
71fn default_max_replicas() -> u32 {
72    1
73}
74
75/// Observed serving truth for an [`InferenceService`]. Written only by the
76/// operator.
77#[derive(Serialize, Deserialize, Clone, Debug, Default, JsonSchema)]
78#[serde(rename_all = "camelCase")]
79pub struct InferenceServiceStatus {
80    /// Coarse lifecycle phase (`Pending`, `Ready`, `Failed`, ...).
81    #[serde(default, skip_serializing_if = "Option::is_none")]
82    pub phase: Option<String>,
83
84    /// Number of ready replicas currently serving.
85    #[serde(default, skip_serializing_if = "Option::is_none")]
86    pub ready_replicas: Option<u32>,
87
88    /// Externally reachable URL, once serving.
89    #[serde(default, skip_serializing_if = "Option::is_none")]
90    pub url: Option<String>,
91
92    /// Human-readable reconcile outcome or reason for the current phase.
93    #[serde(default, skip_serializing_if = "Option::is_none")]
94    pub message: Option<String>,
95
96    /// `metadata.generation` last reconciled.
97    #[serde(default, skip_serializing_if = "Option::is_none")]
98    pub observed_generation: Option<i64>,
99}