How risingwavelabs/risingwave-operator works
Project Type and Purpose
• This is a Kubernetes Operator (written in Go using Kubebuilder/controller-runtime) whose job is to manage RisingWave clusters on Kubernetes.
• It defines CustomResourceDefinitions (CRDs) for RisingWave and RisingWaveScaleView, watches for these custom resources, and reconciles desired state by creating/updating native Kubernetes resources (StatefulSets, Deployments, Services, PVCs, ConfigMaps, Webhooks).
Key Top-Level Directories
• apis/…: CRD type definitions under risingwave/v1alpha1
• cmd/manager: operator entrypoint (manager.go)
• pkg/controller: reconciliation logic for RisingWave and ScaleView
• pkg/webhook: mutating & validating webhook handlers
• config/: all Kustomize manifests for CRDs, RBAC, manager, webhook, samples
• ci/, .github/: build/test/release pipelines
• test/ and pytest/: e2e and unit tests
Main Components
a. Kubernetes Cluster
• API Server & etcd (built-in Kubernetes control plane)
• Cert-Manager (external dependency for TLS/secrets)
b. CustomResourceDefinitions (CRDs)
• RisingWave
• RisingWaveScaleView
c. Operator Pod (“risingwave-operator-controller-manager”)
• Controller Manager (root manager.Process)
• RisingWaveController (pkg/controller/risingwave_controller.go)
• ScaleViewController (pkg/controller/risingwave_scale_view_controller.go)
• Webhook Server (pkg/webhook/*.go)
• Mutating & Validating Webhooks for RisingWave/ScaleView
• Metrics Recorder (pkg/metrics)
d. Child Resources Managed by the Operator
• StatefulSet(s): risingwave-meta (etcd), risingwave-compute
• Deployment(s): risingwave-frontend, compactor, scale-view workers
• Services: frontend, meta, metrics, webhook-service
• PersistentVolumeClaims: for etcd metadata, MinIO state store, etc.
• ConfigMaps: generated configurations, controller config
e. External Components (optional, if used in sample includes)
• MinIO or other object store (for state store)
• PVC-backed Postgres or SQLite (for metadata store)
Relationships & Data Flows
• CRD Registration → API Server
• User/Subsystem creates a RisingWave CR → API Server
• Operator’s Manager watches CRs (informer cache) → Reconciliation loops
• Reconciler issues CRUD calls to API Server → Creates/Updates StatefulSets, Deployments, Services, PVCs
• Webhook Server hooked into API Server admission → Validates/mutates CR requests
• Operator records metrics → Prometheus (if monitoring configured)
Architectural Patterns & Principles
• Operator Pattern / Controller Pattern:
• Single control loop per resource type
• Desired state in CR → Actual state in cluster → Reconcile
• Modularization: separate packages for API types, controllers, webhooks, metrics
• GitOps/Kustomize: all k8s manifests kept in config/ and docs/
• CI/CD: GitHub Actions and Buildkite pipelines build Docker image, run unit/e2e tests
Technologies & Frameworks
• Go + Kubebuilder/controller-runtime for controllers & webhooks
• Kustomize for Kubernetes manifest templating
• cert-manager for TLS certificate provisioning
• Prometheus metrics using controller-runtime instrumentation
• Helm (optional install path)