rivven_operator/lib.rs
1//! # Rivven Kubernetes Operator
2//!
3//! Production-grade Kubernetes operator for deploying and managing Rivven clusters and connectors.
4//!
5//! This crate provides the core functionality for the Rivven Kubernetes operator,
6//! enabling declarative management of Rivven clusters using Custom Resource Definitions (CRDs).
7//!
8//! ## Features
9//!
10//! - **Custom Resource Definitions**: `RivvenCluster` and `RivvenConnect` CRDs for declarative management
11//! - **Automated Reconciliation**: Continuous state management with eventual consistency
12//! - **StatefulSet Management**: Ordered deployment, scaling, and rolling updates
13//! - **Service Discovery**: Automatic headless service for broker discovery
14//! - **Configuration Management**: ConfigMaps for broker and connector configuration
15//! - **Security**: Pod security contexts, TLS support, and secure defaults
16//! - **Observability**: Prometheus-compatible operator metrics
17//! - **High Availability**: PodDisruptionBudget support for safe upgrades
18//!
19//! ## Quick Start
20//!
21//! ```rust,ignore
22//! use rivven_operator::prelude::*;
23//! use kube::Client;
24//!
25//! #[tokio::main]
26//! async fn main() -> Result<()> {
27//! // Create Kubernetes client from default config
28//! let client = Client::try_default().await?;
29//!
30//! // Run the operator controller
31//! run_controller(client, None).await
32//! }
33//! ```
34//!
35//! ## Architecture
36//!
37//! The operator follows the standard Kubernetes controller pattern:
38//!
39//! 1. **Watch**: Monitor RivvenCluster and RivvenConnect resources for changes
40//! 2. **Reconcile**: Compare desired state (CRD spec) with actual state (K8s resources)
41//! 3. **Act**: Create, update, or delete resources to match desired state
42//! 4. **Status**: Update CRD status with current cluster state
43//!
44//! ## Modules
45//!
46//! - [`crd`] - Custom Resource Definition types with validation
47//! - [`controller`] - Reconciliation logic and controller setup
48//! - [`resources`] - Kubernetes resource builders (StatefulSet, Service, ConfigMap)
49//! - [`error`] - Error types for operator operations
50//!
51//! ## Custom Resource Definitions
52//!
53//! ### RivvenCluster
54//!
55//! Manages Rivven broker clusters with StatefulSets:
56//!
57//! ```yaml
58//! apiVersion: rivven.io/v1alpha1
59//! kind: RivvenCluster
60//! metadata:
61//! name: production
62//! spec:
63//! replicas: 3
64//! version: "0.0.1"
65//! storage:
66//! size: 100Gi
67//! config:
68//! defaultPartitions: 3
69//! defaultReplicationFactor: 2
70//! ```
71//!
72//! ### RivvenConnect
73//!
74//! Manages connector pipelines for CDC and data integration:
75//!
76//! ```yaml
77//! apiVersion: rivven.io/v1alpha1
78//! kind: RivvenConnect
79//! metadata:
80//! name: cdc-pipeline
81//! spec:
82//! clusterRef:
83//! name: production
84//! sources:
85//! - name: postgres-cdc
86//! connector: postgres-cdc
87//! topic: cdc.events
88//! sinks:
89//! - name: s3-archive
90//! connector: s3
91//! topics: ["cdc.*"]
92//! ```
93//!
94//! ### RivvenTopic
95//!
96//! Manages topics declaratively for GitOps workflows:
97//!
98//! ```yaml
99//! apiVersion: rivven.io/v1alpha1
100//! kind: RivvenTopic
101//! metadata:
102//! name: orders-events
103//! spec:
104//! clusterRef:
105//! name: production
106//! partitions: 12
107//! replicationFactor: 3
108//! config:
109//! retentionMs: 604800000
110//! cleanupPolicy: delete
111//! compressionType: lz4
112//! acls:
113//! - principal: "user:order-service"
114//! operations: ["Read", "Write"]
115//! ```
116//!
117//! ## Security
118//!
119//! The operator applies secure defaults:
120//!
121//! - **Non-root containers**: `runAsNonRoot: true`
122//! - **Read-only filesystem**: `readOnlyRootFilesystem: true`
123//! - **Dropped capabilities**: All capabilities dropped
124//! - **Seccomp profiles**: RuntimeDefault seccomp profile
125//! - **TLS support**: Optional TLS for broker communication
126//!
127//! ## Metrics
128//!
129//! The operator exposes Prometheus metrics:
130//!
131//! - `rivven_operator_reconcile_total` - Total reconciliation attempts
132//! - `rivven_operator_reconcile_errors_total` - Reconciliation errors
133//! - `rivven_operator_reconcile_duration_seconds` - Reconciliation latency
134//!
135//! ## Feature Flags
136//!
137//! This crate does not have optional features - all functionality is included
138//! by default for simplicity.
139
140pub mod connect_controller;
141pub mod controller;
142pub mod crd;
143pub mod error;
144pub mod resources;
145pub mod topic_controller;
146
147pub mod prelude {
148 //! Re-exports for convenient usage
149 pub use crate::connect_controller::{
150 run_connect_controller, ConnectControllerContext, ConnectControllerMetrics,
151 };
152 pub use crate::controller::{run_controller, ControllerContext, ControllerMetrics};
153 pub use crate::topic_controller::{
154 run_topic_controller, TopicControllerContext, TopicControllerMetrics,
155 };
156 // RivvenCluster CRD types
157 pub use crate::crd::{
158 BrokerConfig, ClusterCondition, ClusterPhase, MetricsSpec, PdbSpec, ProbeSpec,
159 RivvenCluster, RivvenClusterSpec, RivvenClusterStatus, ServiceMonitorSpec, StorageSpec,
160 TlsSpec,
161 };
162 // RivvenConnect CRD types
163 pub use crate::crd::{
164 ClusterReference, ConnectCondition, ConnectConfigSpec, ConnectMetricsSpec, ConnectPhase,
165 ConnectTlsSpec, ConnectorStatus, GlobalConnectSettings, HealthConfigSpec, RateLimitSpec,
166 RetryConfigSpec, RivvenConnect, RivvenConnectSpec, RivvenConnectStatus, SinkConnectorSpec,
167 SourceConnectorSpec, SourceTopicConfigSpec, TableSpec, TopicSettingsSpec,
168 };
169 // RivvenTopic CRD types
170 pub use crate::crd::{
171 PartitionInfo, RivvenTopic, RivvenTopicSpec, RivvenTopicStatus, TopicAcl, TopicCondition,
172 TopicConfig,
173 };
174 pub use crate::error::{OperatorError, Result};
175 pub use crate::resources::ResourceBuilder;
176}