java-operator-sdk: the controller runtime behind Kubernetes operators written in Java

Why an operator needs a framework at all

A Kubernetes operator is a controller running inside a cluster, watching for custom resources and reconciling real state against what the user asked for. The reconciliation loop is simple to describe and tedious to implement. You need to watch an API type, notice changes, do work, handle the case where the work fails, and retry without either spinning or giving up, all while a second copy of your controller might be running because a previous pod was evicted.

The Java Operator SDK exists to supply exactly that machinery. The README describes it as a production-ready framework that makes implementing Kubernetes Operators in Java easy, and it calls itself a higher level framework and related tooling to support writing Kubernetes Operators in Java. The stated aim is to make it easy to implement best practices and patterns for an Operator.

The features it claims to implement are the parts every hand written operator ends up reinventing. Optimal handling of Kubernetes API events, handling of dependent resources, related events and caching, automatic retries, smart event scheduling, and error handling that is easy to use. The README rounds this off with a joke about everything that a batteries included framework needs.

The audience is a Java team with an existing service that now needs to be packaged and operated as a Kubernetes API, usually because a platform team wants other teams to consume it declaratively instead of through tickets and scripts. The adoption argument is about deleting operational code, not about adding capability.

Informer caching, retries and event scheduling are the framework's real work

It is worth being precise about which parts of the loop the framework owns, because that is where the difference between a good operator and a flaky one usually comes from.

Caching is the first. An operator that reads the API for every reconciliation turn is slow and hammers the API server, so the framework keeps an informer cache and lets the controller read from it. The README lists handling of dependent resources, related events, and caching as a single feature area, which is a hint that the cache is not merely an optimisation but part of how dependent resources are modelled. A dependent resource is the object an operator creates on behalf of a custom resource, and a controller that watches the cache for changes to those objects can react to their state without polling.

Retries are the second. Automatic retries are listed as a distinct feature, and the reason this is not trivial is that a failed reconciliation may have made partial progress. The controller has to know whether the failure is worth retrying at all, and how long to wait before doing so.

Event scheduling is the third, and it is the least obvious. Smart event scheduling is about how work is queued and reordered when many changes arrive at once, which is where a controller that does not batch or deduplicate can hammer the API server with redundant reconciles of the same object.

Together these three features are what the framework actually contributes. The reconcile method you write is the small part; the surrounding machinery is the value.

The Fabric8 Kubernetes Client does the API work

The README is explicit about the foundation. Under the hood the SDK uses the Fabric8 Kubernetes Client, and it notes that this client provides additional facilities, like generating a CRD from source code, and vice versa.

That second capability deserves more attention than it usually gets. A Kubernetes operator is only useful if the cluster can accept its custom resource, which means shipping a CustomResourceDefinition. In many stacks that YAML is maintained by hand and drifts from the Java classes that model the same objects, so a rename in the code silently leaves the schema behind. Being able to generate the CRD from the source code, in both directions, removes that drift. The reverse direction, generating code from a CRD, is how a team that already has a schema adopts the framework without rewriting it first.

The Fabric8 client also means the SDK is not a from scratch Kubernetes protocol implementation. It inherits the client ecosystem, including the typed DSL that the Glasskube operator entry uses, and the project list names the Apache Flink and Apache Spark operators, Debezium, Keycloak and Apache Hive operators among the projects built with it.

The corollary is a dependency tree. Using the SDK means using the Fabric8 client and its transitive dependencies, and the repository layout shows the framework is split across many Maven modules rather than being one jar: operator-framework-core, operator-framework-junit, operator-framework-bom, and separate support modules for observability, micrometer metrics, a caffeine bounded cache and a migration path.

Testing an operator needs a second module and an index processor

An operator that cannot be tested is an operator that can only be tested in a cluster, and the repository layout shows testing as a first class concern rather than an afterthought.

There is a module named operator-framework-junit, which is the JUnit facing part of the framework, and the README lists support for testing operators among the things the framework provides. There is also a module called test-index-processor, which in a Java project of this kind is an annotation processor, and its presence suggests the testing support is index driven rather than reflection driven.

This matters for a specific reason. A Kubernetes operator test usually has two halves: the reconcile logic can be exercised against a simulated API, and the wiring of the controller, its watches and its dependencies can be verified. The first half is what most frameworks attempt. The second half is where controllers usually break, because a watch on the wrong type, or a dependent resource that is never registered, only shows up when the controller runs against a real API server.

There is a separate sample-operators directory in the repository, and the presence of a dedicated testing module plus a processor of its own says the maintainers treat the test harness as a product surface.

The multi module layout also means the BOM, operator-framework-bom, exists so that a consumer can align the versions of the framework modules and the Fabric8 client without pinning each one.

Starting from the website and the samples, not from a quick start guide

The README does not contain an install snippet, so the honest route is the one it points to. The full documentation lives on the JOSDK website at javaoperatorsdk.io, and the README points there for the features and their usage, with the documentation section linking the documentation directly.

In the repository itself, the practical starting points are the sample-operators directory, which contains working controllers, and the Maven wrapper, mvnw, which is present at the root alongside mvnw.cmd. The build is a Maven build, driven by the root pom.xml, and the .mvn directory holds the wrapper configuration. A developer who wants a first taste of the framework clones the repository, builds the samples with the wrapper and reads a sample controller, rather than adding a dependency to an application and guessing at the wiring.

That ordering is deliberate and it is a sign of how the project sees itself. A framework whose first use is a sample project in its own repository is a framework that expects you to understand the controller model before you ship a controller. The Quarkus Extension and the Spring Boot Starter listed in the related projects section are the integration points for people who already have an application framework, and the Kubernetes Glue Operator goes further and lets you create operators by applying a custom resource, which removes the Java requirement entirely.

The docs site is also where the contribution guide lives, which tells you where the maintainers expect proposals to start.

Three ways in, from plain Java to a language neutral meta operator

The related projects section is really a set of alternatives, each removing a different constraint.

The Quarkus Extension packages the framework for Quarkus applications, so a Java operator can be built as a native capable Quarkus application. The Spring Boot Starter does the same for Spring Boot, for teams whose application stack is already Spring and who want the operator embedded in an existing service rather than in a new binary.

The Kubernetes Glue Operator is the most interesting of the three, and it is a genuine alternative approach rather than a wrapper. The README describes it as a meta operator that builds on the framework to use the workflows and dependent resources features, and it allows you to create operators by simply applying a custom resource, which is described as a language independent way. The difference in approach is fundamental. Instead of writing and compiling Java, you describe the desired operator as data, and the platform generates it. That moves the operator logic out of the JVM entirely and changes the deployment story from a jar to a configuration.

The Kubernetes Webhooks Framework, in the same list, is the complement to the core SDK. The README notes that conversion hooks and dynamic admission controllers are supported as a separate project, and that the main project offers much more. So the ecosystem is split along lines of concern: the core handles reconciliation, and adjacent projects handle webhooks.

For a team choosing between them, the question is whether the operator's logic is a Java problem. If it is, the SDK plus a Quarkus or Spring integration is the shortest path. If the logic is closer to configuration, the Glue Operator is worth reading about.

Apache-2.0, a 5.x line and a repository with many modules

The licence field says Apache-2.0, which is the standard permissive licence for CNCF projects and carries an explicit patent grant. A commercial product that embeds the SDK, or an operator written with it, has no source disclosure obligation. That is a licensing observation rather than legal advice, and organisations with their own review process should still check the licence text in the repository.

On maintenance, the repository is not archived and the last push was on 2026-10-14. The release history shows a steady line of patch releases: 5.6.2 on 2026-09-22, 5.6.1 on 2026-09-15 and 5.6.0 on 2026-09-04. A 5.x line with three releases in under a month is what an actively used framework looks like when its dependents ship frequently.

The upgrade cost comes from the module count rather than the release rate. The repository root holds operator-framework-core, operator-framework-junit, operator-framework-bom, a bootstrapper maven plugin, a caffeine bounded cache support module, a micrometer support module, a migration module, an observability module, a test index processor, a helm directory, a sample-operators directory and the operator-framework aggregate module. A consumer who depends on more than one of these has to keep their versions aligned, which is what the BOM is for, and a major version bump can move APIs across several of them at once.

Two other files in the root tell you how the project is policed. There is a license-header.txt, which is what a build uses to check that source files carry the right header, and a spotbugs-exclude.xml at root for the static analysis exclusions, which is a sign that the static analysis is strict enough to need documented exceptions. There is also an AGENTS.md and a CLAUDE.md at the root, which is a fairly direct statement that the project expects coding assistants to be used against its source.

Editorial conclusion

java-operator-sdk is the right choice for a Java shop that wants to operate Kubernetes as an API rather than through shell scripts, and the wrong choice for a team that wants a dependency free operator or a language neutral controller, since the framework brings a Maven dependency tree, a Gradle-free Maven build and a set of modules you have to keep aligned. Verify the version first, because the published line is 5.6.x with 5.6.2 on 2026-09-22, and read the sample-operators directory in the repository before writing your first controller, because the samples are the fastest way to see how the reconcile loop, the informer cache and the CRD generation fit together.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. operator-framework/java-operator-sdk on GitHub
3. Project website
4. README
5. Releases