Merge pull request #946 from yinkscss/fix/881-kubernetes-operator-sdk-framework-for-extensions

[881] [EPIC] Kubernetes Operator SDK Framework for Extensions

Author: OtowoSamuel

Cargo.toml

@@ -205,6 +205,10 @@ k8s-openapi = { version = "0.22", default-features = false, features = [
     "v1_30",
 ] }
 
+[[bin]]
+name = "stellar-scaffold"
+path = "src/bin/stellar-scaffold.rs"
+
 [[bin]]
 name = "stellar-operator"
 path = "src/main.rs"

docs/operator-sdk-guide.md

@@ -0,0 +1,44 @@
+# Operator SDK Developer Guide
+
+Build custom operators and extensions for Stellar-K8s using the in-tree SDK.
+
+## SDK Components
+
+| Module | Purpose |
+|--------|---------|
+| `stellar_k8s::sdk` | Public SDK entry point |
+| `stellar_k8s::plugin_sdk` | Reconcile hooks and sidecar injectors |
+| `stellar_k8s::sdk::codegen` | CRD-to-controller stub generation |
+| `stellar_k8s::sdk::testing` | Mock contexts and test harness |
+
+## Scaffold a New Controller
+
+```bash
+cargo run --bin stellar-scaffold -- StellarMyResource --print
+```
+
+## Example Operators
+
+See `examples/operators/` for three reference implementations:
+
+1. `metrics_exporter.rs` - ReconcileHook
+2. `log_shipper.rs` - SidecarInjector
+3. `registry_validator.rs` - Admission policy integration
+
+## Register a Plugin
+
+```rust
+use stellar_k8s::plugin_sdk::PluginRegistry;
+
+let registry = std::sync::Arc::new(
+    PluginRegistry::new().with_hook(MyHook)
+);
+```
+
+## CI/CD Template
+
+Use `.github/workflows/operator-extension.yml` as a starting point for extension CI.
+
+## Tutorial
+
+See `docs/tutorials/building-your-first-operator.md` for a step-by-step walkthrough.

docs/secret-management-guide.md

@@ -0,0 +1,41 @@
+# Secret Management Guide
+
+Declarative secret management via the `StellarSecret` CRD with dynamic credentials,
+automatic rotation, KMS encryption, and multi-backend support.
+
+## Features
+
+- Dynamic database credentials with TTL
+- Automatic rotation every 30 days (configurable via `720h` interval)
+- AWS KMS, Azure Key Vault, GCP KMS, and Vault backends
+- Complete audit logging with anomaly detection
+- Zero-downtime rotation with version history and rollback
+- Secret injection as environment variables or files
+
+## Quick Start
+
+```yaml
+apiVersion: stellar.org/v1alpha1
+kind: StellarSecret
+metadata:
+  name: postgres-dynamic
+spec:
+  secretName: postgres-creds
+  backend: vault
+  provider: Vault
+  dynamic:
+    enabled: true
+    ttl: 1h
+  rotation:
+    interval: 720h
+    zeroDowntime: true
+```
+
+## Grafana Dashboard
+
+Import `monitoring/grafana/stellar-secret-dashboard.json` for rotation metrics,
+sync drift, and access anomaly alerts.
+
+## Compliance
+
+Export audit trails via `stellar-operator export-compliance` for auditor review.

examples/operators/log_shipper.rs

@@ -0,0 +1,21 @@
+//! Example sidecar injector operator using the Stellar-K8s SDK.
+
+use async_trait::async_trait;
+use stellar_k8s::plugin_sdk::{InjectedSidecar, ReconcileContext, SidecarInjector};
+
+pub struct LogShipperInjector;
+
+#[async_trait]
+impl SidecarInjector for LogShipperInjector {
+    fn name(&self) -> &str {
+        "log-shipper"
+    }
+
+    async fn sidecars(&self, _ctx: &ReconcileContext) -> Vec<InjectedSidecar> {
+        vec![InjectedSidecar {
+            name: "log-shipper".into(),
+            image: "fluent/fluent-bit:3.0".into(),
+            ..Default::default()
+        }]
+    }
+}

examples/operators/metrics_exporter.rs

@@ -0,0 +1,18 @@
+//! Example reconcile hook operator using the Stellar-K8s SDK.
+
+use async_trait::async_trait;
+use stellar_k8s::plugin_sdk::{HookResult, ReconcileContext, ReconcileHook};
+
+pub struct MetricsExporterHook;
+
+#[async_trait]
+impl ReconcileHook for MetricsExporterHook {
+    fn name(&self) -> &str {
+        "metrics-exporter"
+    }
+
+    async fn pre_reconcile(&self, ctx: &ReconcileContext) -> HookResult {
+        tracing::debug!(node = %ctx.node_name, "exporting pre-reconcile metrics");
+        HookResult::Continue
+    }
+}

examples/operators/registry_validator.rs

@@ -0,0 +1,46 @@
+//! Example admission policy hook using registry admission checks.
+
+use stellar_k8s::controller::check_admission;
+use stellar_k8s::crd::stellar_registry::{StellarRegistry, VulnerabilitySummary};
+
+pub fn validate_image(registry: &StellarRegistry, image: &str, signed: bool) -> Result<(), String> {
+    check_admission(registry, image, signed, &VulnerabilitySummary::default())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use kube::core::ObjectMeta;
+    use stellar_k8s::crd::stellar_registry::{
+        AdmissionPolicy, RegistryMirror, ScanningConfig, SigningConfig, StellarRegistrySpec,
+    };
+
+    fn sample_registry() -> StellarRegistry {
+        StellarRegistry {
+            metadata: ObjectMeta {
+                name: Some("reg".into()),
+                namespace: Some("stellar".into()),
+                ..Default::default()
+            },
+            spec: StellarRegistrySpec {
+                endpoint: "registry.example.com".into(),
+                scanning: ScanningConfig::default(),
+                signing: SigningConfig {
+                    require_signature: false,
+                    ..Default::default()
+                },
+                admission: AdmissionPolicy::default(),
+                mirrors: vec![],
+                garbage_collection: None,
+                proxy: None,
+                auto_patch: None,
+            },
+            status: None,
+        }
+    }
+
+    #[test]
+    fn allows_signed_image() {
+        assert!(validate_image(&sample_registry(), "app:v1", true).is_ok());
+    }
+}

examples/stellar-secret-example.yaml

@@ -0,0 +1,28 @@
+apiVersion: stellar.org/v1alpha1
+kind: StellarSecret
+metadata:
+  name: postgres-dynamic
+  namespace: stellar
+spec:
+  secretName: postgres-creds
+  backend: vault
+  provider: Vault
+  dynamic:
+    enabled: true
+    ttl: 1h
+    database:
+      host: postgres.stellar.svc
+      database: horizon
+      username: horizon
+      role: readwrite
+  rotation:
+    interval: 720h
+    zeroDowntime: true
+    versionRetention: 5
+  targets:
+    - kind: envVar
+      name: horizon
+      key: DATABASE_URL
+  audit:
+    enabled: true
+    sink: s3://audit-logs/secrets

src/bin/stellar-scaffold.rs

@@ -0,0 +1,36 @@
+//! stellar-scaffold: CLI for scaffolding Stellar-K8s operators
+
+use clap::Parser;
+use stellar_k8s::sdk::codegen::{generate_controller_stub, render_controller_source};
+
+#[derive(Parser)]
+#[command(name = "stellar-scaffold")]
+#[command(about = "Scaffold a new Stellar-K8s operator controller from a CRD kind")]
+struct Args {
+    /// CRD API group
+    #[arg(long, default_value = "stellar.org")]
+    group: String,
+
+    /// CRD API version
+    #[arg(long, default_value = "v1alpha1")]
+    version: String,
+
+    /// CRD Kind name (PascalCase)
+    kind: String,
+
+    /// Print generated Rust source to stdout
+    #[arg(long)]
+    print: bool,
+}
+
+fn main() {
+    let args = Args::parse();
+    let stub = generate_controller_stub(&args.group, &args.version, &args.kind);
+    if args.print {
+        print!("{}", render_controller_source(&stub));
+    } else {
+        println!("Controller stub: {}", stub.reconciler_fn);
+        println!("Module: src/controller/{}.rs", stub.module_name);
+        println!("Run with --print to emit reconciler source");
+    }
+}