How operator-framework/java-operator-sdk works
Project Type and Purpose
• This is a multi-module, Maven-based open-source framework (Java Operator SDK) for building Kubernetes Operators in Java.
• It provides:
• A core runtime library (operator-framework-core)
• An annotation processor (operator-framework)
• A Maven plugin for code bootstrapping (bootstrapper-maven-plugin)
• Support libraries (caffeine-bounded-cache-support, micrometer-support)
• Testing extensions (operator-framework-junit5)
• A BOM POM (operator-framework-bom)
• Sample operators and documentation (sample-operators, docs)
File Structure Analysis
• Top-level POM and wrapper files coordinate builds.
• Subdirectories are discrete Maven modules with their own src/, pom.xml, test/, resources.
• “bootstrapper-maven-plugin”: code-generation plugin
• “caffeine-bounded-cache-support” & “micrometer-support”: optional runtime extensions
• “operator-framework-core”: the heart of the controller machinery (event sources, reconciler API, dependent resources, workflows)
• “operator-framework”: compile-time annotation processor generating configuration metadata
• “operator-framework-junit5”: JUnit 5 test harness extensions
• “sample-operators”: example implementations showing best practices
• “docs”: Hugo-based static site for user documentation
• CI/CD: GitHub Actions workflows for build, test, release, site generation
Key README Insights
• Emphasis on:
• Kubernetes controller runtime
• Fabric8 client integration
• Batteries-included features (event handling, retries, caching, error handling, observability)
• Mentions related extensions (Quarkus, Spring Boot) but those live in separate repos
a. Main Components
• Developer Toolchain:
• Maven Wrapper & POMs
• bootstrapper-maven-plugin (generates scaffolding)
• annotation processor (operator-framework)
• Core Runtime:
• ControllerManager, Operator, Reconciler API
• EventSourceManager (informer, polling, timer, cache)
• DependentResource framework & Workflow engine
• ConfigurationService & LeaderElectionManager
• Fabric8 Kubernetes Client integration
• Optional Extensions:
• Caffeine Cache support
• Micrometer Metrics support
• Testing:
• JUnit 5 OperatorExtension
• Sample CRDs & in-cluster/locally-run operator tests
• Documentation Site: Hugo pipeline, Netlify
• External Systems: Kubernetes API Server, CRD definitions, Logging/Monitoring backends
b. Relationships & Interactions
• At build time: bootstrapper-plugin + annotation processor generate Java operator scaffolding & CRDs
• OperatorRuntime (core) uses Fabric8 client to watch CRDs via Informers → pushes Events into EventSourceManager → EventProcessor dispatches to Reconciler
• DependentResource & Workflow modules orchestrate secondary resource CRUD operations
• Caffeine & Micrometer modules plug into event-source caching and metrics endpoints
• JUnit5 extension spins up a test cluster (or mocks) and runs Reconciler logic for automated tests
• Docs module is built separately into a website, referencing generated API docs
c. Architectural Patterns & Principles
• Inversion of Control for Reconciler implementations
• Modular design with clear Maven module boundaries
• Plug-in architecture for event sources, caching, metrics
• Compile-time annotation processing to enforce configuration consistency
• Publisher-Subscriber (Informer → EventSource → EventProcessor → Reconciler)
• Reconciliation loop: desired vs actual state
d. Technologies & Frameworks
• Java 8+ (or higher)
• Maven multi-module reactor
• Fabric8 Kubernetes Client
• Caffeine cache
• Micrometer metrics
• JUnit 5
• Hugo (docs)