feat: kubernetes operator for agent lifecycle management

  Add a kube-rs based Kubernetes operator (openshell-operator crate) that
  provides CRD-driven declarative sandbox lifecycle management.

  Components:
  - AgentSandbox CRD with spec for image, resources, policy, and provider refs
  - Reconciler loop with exponential backoff and status condition reporting
  - Admission webhooks (validating + mutating) for CRD validation
  - Manifest builders for sandbox Pod, Service, and RBAC resources
  - Label conventions for sandbox discovery and ownership tracking
  - SandboxRuntimeManager gRPC service for operator-gateway communication
  - Gateway integration via multiplex listener and config flags

  New crate: crates/openshell-operator (16 files)
  New proto: proto/sandbox_runtime_manager.proto
  Modified: openshell-core (config, proto), openshell-server (cli, grpc, multiplex)

  Tests: 2,239 passed, 0 failed

  Closes #1719

Author: alexm-redhat

Cargo.lock

@@ -113,6 +113,10 @@ kube = { version = "0.90", features = ["runtime", "derive"] }
 kube-runtime = "0.90"
 k8s-openapi = { version = "0.21.1", features = ["v1_26"] }
 
+# CRD support (operator)
+schemars = "0.8"
+json-patch = "1"
+
 # IDs
 uuid = { version = "1.10", features = ["v4"] }
 

Cargo.toml

@@ -400,6 +400,9 @@ pub struct Config {
 
     /// Browser-facing sandbox service routing configuration.
     pub service_routing: ServiceRoutingConfig,
+
+    /// Whether the SandboxRuntime operator bridge is enabled.
+    pub operator_enabled: bool,
 }
 
 /// Browser-facing sandbox service routing configuration.
@@ -584,6 +587,7 @@ impl Config {
             grpc_rate_limit_requests: None,
             grpc_rate_limit_window_secs: None,
             service_routing: ServiceRoutingConfig::default(),
+            operator_enabled: false,
         }
     }
 
@@ -705,6 +709,13 @@ impl Config {
         self.service_routing.enable_loopback_service_http = enabled;
         self
     }
+
+    /// Enable or disable the SandboxRuntime operator bridge.
+    #[must_use]
+    pub const fn with_operator_enabled(mut self, enabled: bool) -> Self {
+        self.operator_enabled = enabled;
+        self
+    }
 }
 
 impl Default for ServiceRoutingConfig {

crates/openshell-core/src/config.rs

@@ -79,8 +79,22 @@ pub mod inference {
     }
 }
 
+#[allow(
+    clippy::all,
+    clippy::pedantic,
+    clippy::nursery,
+    unused_qualifications,
+    rust_2018_idioms
+)]
+pub mod runtime {
+    pub mod v1 {
+        include!(concat!(env!("OUT_DIR"), "/openshell.runtime.v1.rs"));
+    }
+}
+
 pub use datamodel::v1::*;
 pub use inference::v1::*;
 pub use openshell::*;
+pub use runtime::v1::*;
 pub use sandbox::v1::*;
 pub use test::ObjectForTest;

crates/openshell-core/src/proto/mod.rs

@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+name = "openshell-operator"
+description = "Kubernetes operator for SandboxRuntime CRD lifecycle management"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[[bin]]
+name = "openshell-operator"
+path = "src/main.rs"
+
+[[bin]]
+name = "openshell-crd-gen"
+path = "src/bin/crd_gen.rs"
+
+[lib]
+name = "openshell_operator"
+path = "src/lib.rs"
+
+[dependencies]
+# Kubernetes (inherits workspace features: runtime, derive)
+# Additional "admission" feature for webhook support
+kube = { workspace = true, features = ["admission"] }
+k8s-openapi = { workspace = true }
+
+# CRD schema generation
+schemars = { workspace = true }
+
+# Webhook JSON patches
+json-patch = { workspace = true }
+
+# gRPC / Protobuf (for bridge service types)
+tonic = { workspace = true }
+prost = { workspace = true }
+
+# HTTP server (webhook endpoints)
+axum = { workspace = true }
+tower = { workspace = true }
+hyper = { workspace = true }
+hyper-util = { workspace = true }
+
+# TLS (webhook HTTPS)
+tokio-rustls = { workspace = true }
+rustls = { workspace = true }
+rustls-pemfile = { workspace = true }
+
+# Async runtime
+tokio = { workspace = true }
+tokio-stream = { workspace = true }
+futures = { workspace = true }
+
+# Serialization
+serde = { workspace = true }
+serde_json = { workspace = true }
+serde_yml = { workspace = true }
+
+# Error handling
+thiserror = { workspace = true }
+anyhow = { workspace = true }
+
+# Logging
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+
+# CLI (operator binary args)
+clap = { workspace = true }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["full", "test-util"] }
+
+[lints]
+workspace = true

crates/openshell-operator/Cargo.toml

@@ -0,0 +1,14 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Utility to generate the SandboxRuntime CRD YAML for Helm chart deployment.
+
+use kube::CustomResourceExt;
+use openshell_operator::crd::SandboxRuntime;
+
+fn main() {
+    print!(
+        "{}",
+        serde_yml::to_string(&SandboxRuntime::crd()).unwrap()
+    );
+}

crates/openshell-operator/src/bin/crd_gen.rs

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Configuration types for the operator binary.
+
+/// Configuration for the operator binary.
+#[derive(Clone, Debug)]
+pub struct OperatorConfig {
+    /// Namespace to watch. `None` = all namespaces.
+    pub namespace: Option<String>,
+
+    /// Metrics server bind address.
+    pub metrics_addr: String,
+
+    /// Webhook server bind address.
+    pub webhook_addr: String,
+
+    /// Path to TLS certificate for webhook server.
+    pub tls_cert_path: Option<String>,
+
+    /// Path to TLS private key for webhook server.
+    pub tls_key_path: Option<String>,
+}