hyprstream_k8s/lib.rs
1//! Kubernetes CRD schemas for hyprstream resources under `*.hyprstream.io`.
2//!
3//! This is the foundation crate for the kube-rs track of the Kubernetes epic
4//! (#778). It defines the **hyprstream → Kubernetes** projection: hyprstream
5//! resources as declarative Kubernetes objects, subspaced under hyprstream-owned
6//! API groups so nouns never collide with third-party CRDs
7//! (`serving.hyprstream.io/InferenceService` ≠ `serving.kserve.io/InferenceService`
8//! by construction).
9//!
10//! ## Single-writer rule (baked into every schema)
11//!
12//! Git owns the weights. For every resource here, `spec` is **desired STEP
13//! intent** (Stage → Train → Evaluate → Promote) and `status` is **observed
14//! git/runtime truth**. The operator that reconciles these (K5b/K5c) is a
15//! *translator*, never a second writer of weights: promotion is a git merge and
16//! rollback is a git checkout, both performed through `RegistryService`. Nothing
17//! in these CRDs is authoritative over the weights themselves.
18//!
19//! ## Two-writer drift guard
20//!
21//! Objects owned by the hyprstream operator carry the [`MANAGED_BY_LABEL`]
22//! (value [`MANAGED_BY_VALUE`]) and `ownerReferences` to their parent. Each
23//! driver refuses to adopt objects it does not own.
24//!
25//! ## Confused-deputy guard
26//!
27//! [`mesh::TenantBinding`] is the explicit, admin-created mapping between a
28//! Kubernetes namespace and a hyprstream tenant. It is gated by the
29//! `federation:register` scope and is the anchor the reconcilers (K5b) use to
30//! reject any cross-tenant reference that a binding does not cover. It is
31//! deliberately **cluster-scoped** so a tenant confined to its own namespace
32//! cannot forge its own binding.
33//!
34//! ## Feature layout
35//!
36//! - default (no features): CRD *type* definitions, schema derivation, CEL
37//! validation and YAML emission — all compile with no cluster present.
38//! - `k8s`: pulls in the kube client + controller-runtime for code that needs a
39//! live API server (see the `install` module). CRD types never require it.
40//! - `grant`: exposes only the service-neutral [`grant::TenantGrantService`]
41//! boundary and generic TenantBinding status projection. Authority-bearing
42//! signing and PDS allocation behavior moved to the downstream,
43//! AGPL-licensed `hyprstream-k8s-pds` crate in #1422.
44//!
45//! | Previous path | New path |
46//! | --- | --- |
47//! | `hyprstream_k8s::grant::TenantGrantIssuer` | `hyprstream_k8s_pds::TenantGrantIssuer` |
48//! | `hyprstream_k8s::grant::TenantGrantVerifier` | `hyprstream_k8s_pds::TenantGrantVerifier` |
49//! | `hyprstream_k8s::grant::CompiledTenantGrant` | `hyprstream_k8s_pds::CompiledTenantGrant` |
50//! | `hyprstream_k8s::grant::VerifiedTenantGrant` | `hyprstream_k8s_pds::VerifiedTenantGrant` |
51//! | `hyprstream_k8s::grant::TENANT_GRANT_ED25519_PURPOSE` | `hyprstream_k8s_pds::TENANT_GRANT_ED25519_PURPOSE` |
52//! | `hyprstream_k8s::grant::TENANT_GRANT_ABILITY` | `hyprstream_k8s_pds::TENANT_GRANT_ABILITY` |
53//! | `hyprstream_k8s::grant::now_unix` | `hyprstream_k8s_pds::now_unix` for adapter callers; the substrate helper remains at its old path |
54//! | `operator::run_operator_with_grant_issuer` | `operator::run_operator_with_grant_service` |
55//! | `OperatorState::with_grant_issuer` | `OperatorState::with_grant_service` |
56//! | `compile_tenant_binding_status(binding, issuer, epoch, now)` | `compile_tenant_binding_status(binding, service, epoch, now)`, where `service` is `Option<&dyn TenantGrantService>` |
57//!
58//! The adapter crate contains a compiling `k8s,grant` operator composition
59//! example and compile fixture.
60//!
61//! All CRDs are `v1alpha1`; the conversion/upgrade path to a future stored
62//! version is noted per-resource and is out of scope for this crate (K5b owns
63//! the conversion webhook).
64
65pub mod mesh;
66pub mod models;
67pub mod serving;
68pub mod training;
69
70/// Service-neutral TenantBinding grant reconciliation contract (#929/#1422).
71///
72/// The AGPL `hyprstream-k8s-pds` adapter implements this contract with the
73/// issuer-signing and PDS allocation/CID behavior.
74#[cfg(feature = "grant")]
75pub mod grant;
76
77#[cfg(feature = "k8s")]
78pub mod install;
79#[cfg(feature = "k8s")]
80pub mod operator;
81
82// Re-export the underlying `kube`/`k8s-openapi` crates so downstream crates
83// (e.g. `hyprstream-workers`' `k8s` sandbox backend) consume the *same*
84// versions and the single `v1_*` k8s-openapi feature this crate pins, rather
85// than declaring their own — the workspace allows exactly one k8s-openapi
86// `v1_*` feature, and threading these through one crate keeps that invariant
87// impossible to violate by accident.
88pub use ::k8s_openapi;
89pub use ::kube;
90
91/// `/k8s` VFS projection (K7, #782) — Kubernetes objects as Plan 9 files.
92///
93/// Gated behind `k8s` because it needs the kube watch runtime plus the
94/// in-process VFS `Mount` surface. See [`vfs::K8sMount`].
95#[cfg(feature = "k8s")]
96pub mod vfs;
97
98pub use mesh::{
99 TenantBinding, TenantBindingSpec, TenantBindingStatus, TenantEntitlement, TenantGrantClass,
100};
101pub use models::{Adapter, AdapterSpec, AdapterStatus, Model, ModelSpec, ModelStage, ModelStatus};
102pub use serving::{InferenceService, InferenceServiceSpec, InferenceServiceStatus, Statefulness};
103pub use training::{ResourceSpec, TrainingRun, TrainingRunSpec, TrainingRunStatus};
104
105use ::k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::CustomResourceDefinition;
106use ::kube::CustomResourceExt;
107
108/// Label applied to every object the hyprstream operator manages.
109///
110/// Drivers refuse to adopt an object that does not carry this label with the
111/// expected value ([`MANAGED_BY_VALUE`]), preventing two-writer drift with
112/// other controllers that might project onto the same nouns.
113pub const MANAGED_BY_LABEL: &str = "hyprstream.io/managed-by";
114
115/// Canonical value for [`MANAGED_BY_LABEL`].
116pub const MANAGED_BY_VALUE: &str = "hyprstream-operator";
117
118/// The API version shared by every CRD in this crate.
119pub const API_VERSION: &str = "v1alpha1";
120
121/// Every CRD defined by this crate, in a stable order.
122///
123/// This is the single source of truth consumed by the `gen-crds` binary (YAML
124/// emission) and by the offline structural-validation tests.
125pub fn all_crds() -> Vec<CustomResourceDefinition> {
126 vec![
127 Model::crd(),
128 Adapter::crd(),
129 TrainingRun::crd(),
130 InferenceService::crd(),
131 TenantBinding::crd(),
132 ]
133}
134
135/// `(kind, plural_group, filename_stem)` triples for each CRD, used to name the
136/// emitted YAML files deterministically.
137pub fn crd_manifests() -> Vec<(CustomResourceDefinition, &'static str)> {
138 vec![
139 (Model::crd(), "models.hyprstream.io_models"),
140 (Adapter::crd(), "models.hyprstream.io_adapters"),
141 (TrainingRun::crd(), "training.hyprstream.io_trainingruns"),
142 (
143 InferenceService::crd(),
144 "serving.hyprstream.io_inferenceservices",
145 ),
146 (TenantBinding::crd(), "mesh.hyprstream.io_tenantbindings"),
147 ]
148}