Java Operator SDK Documentation on Java Operator SDK

Introduction to Kubernetes operators

Mon, 01 Jan 0001 00:00:00 +0000

What are Kubernetes Operators?

Kubernetes operators are software extensions that manage both cluster and non-cluster resources on behalf of Kubernetes. The Java Operator SDK (JOSDK) makes it easy to implement Kubernetes operators in Java, with APIs designed to feel natural to Java developers and framework handling of common problems so you can focus on your business logic.

Why Use Java Operator SDK?

JOSDK provides several key advantages:

Java-native APIs that feel familiar to Java developers
Automatic handling of common operator challenges (caching, event handling, retries)
Production-ready features like observability, metrics, and error handling
Simplified development so you can focus on business logic instead of Kubernetes complexities

Learning Resources

Getting Started

Introduction to Kubernetes operators - Core concepts explained
Implementing Kubernetes Operators in Java - Introduction talk
Kubernetes operator pattern documentation - Official Kubernetes docs

Deep Dives

Problems JOSDK solves - Technical deep dive
Why Java operators make sense - Java in cloud-native infrastructure
Building a Kubernetes operator SDK for Java - Framework design principles

Tutorials

Writing Kubernetes operators using JOSDK - Step-by-step blog series

Bootstrapping and samples

Mon, 01 Jan 0001 00:00:00 +0000

Creating a New Operator Project

Using the Maven Plugin

The simplest way to start a new operator project is using the provided Maven plugin, which generates a complete project skeleton:

mvn io.javaoperatorsdk:bootstrapper:[version]:create \
 -DprojectGroupId=org.acme \
 -DprojectArtifactId=getting-started

This command creates a new Maven project with:

A basic operator implementation
Maven configuration with required dependencies
Generated CustomResourceDefinition (CRD)

Building Your Project

Build the generated project with Maven:

mvn clean install

The build process automatically generates the CustomResourceDefinition YAML file that you’ll need to apply to your Kubernetes cluster.

Patterns and best practices

Mon, 01 Jan 0001 00:00:00 +0000

This document describes patterns and best practices for building and running operators, and how to implement them using the Java Operator SDK (JOSDK).

See also best practices in the Operator SDK.

Implementing a Reconciler

Always Reconcile All Resources

Reconciliation can be triggered by events from multiple sources. It might be tempting to check the events and only reconcile the related resource or subset of resources that the controller manages. However, this is considered an anti-pattern for operators.

Implementing a reconciler

Mon, 01 Jan 0001 00:00:00 +0000

How Reconciliation Works

The reconciliation process is event-driven and follows this flow:

Event Reception: Events trigger reconciliation from:
- Primary resources (usually custom resources) when created, updated, or deleted
- Secondary resources through registered event sources
Reconciliation Execution: Each reconciler handles a specific resource type and listens for events from the Kubernetes API server. When an event arrives, it triggers reconciliation unless one is already running for that resource. The framework ensures no concurrent reconciliation occurs for the same resource.

Error handling and retries

Mon, 01 Jan 0001 00:00:00 +0000

How Automatic Retries Work

JOSDK automatically schedules retries whenever your Reconciler throws an exception. This robust retry mechanism helps handle transient issues like network problems or temporary resource unavailability.

Default Retry Behavior

The default retry implementation covers most typical use cases with exponential backoff:

GenericRetry.defaultLimitedExponentialRetry()
 .setInitialInterval(5000) // Start with 5-second delay
 .setIntervalMultiplier(1.5D) // Increase delay by 1.5x each retry
 .setMaxAttempts(5); // Maximum 5 attempts

Configuration Options

Using the @GradualRetry annotation:

Rate limiting

Mon, 01 Jan 0001 00:00:00 +0000

It is possible to rate limit reconciliation on a per-resource basis. The rate limit takes precedence over retry/reschedule configurations: for example, even if a retry would reschedule a reconciliation but this request would make the resource go over its rate limit, the next reconciliation will be postponed according to the rate limiting rules. Note that the reconciliation is never cancelled, it will just be executed as early as possible based on rate limitations.

Event sources and related topics

Mon, 01 Jan 0001 00:00:00 +0000

Working with EventSource caches

Mon, 01 Jan 0001 00:00:00 +0000

As described in Event sources and related topics, event sources serve as the backbone for caching resources and triggering reconciliation for primary resources that are related to these secondary resources.

In the Kubernetes ecosystem, the component responsible for this is called an Informer. Without delving into the details (there are plenty of excellent resources online about informers), informers watch resources, cache them, and emit events when resources change.

EventSource is a generalized concept that extends the Informer pattern to non-Kubernetes resources, allowing you to cache external resources and trigger reconciliation when those resources change.

Other Features

Mon, 01 Jan 0001 00:00:00 +0000

The Java Operator SDK (JOSDK) is a high-level framework and tooling suite for implementing Kubernetes operators. By default, features follow best practices in an opinionated way. However, configuration options and feature flags are available to fine-tune or disable these features.

Support for Well-Known Kubernetes Resources

Controllers can be registered for standard Kubernetes resources (not just custom resources), such as Ingress, Deployment, and others.

See the integration test for an example of reconciling deployments.

Dependent resources

Mon, 01 Jan 0001 00:00:00 +0000

Motivations and Goals

Most operators need to deal with secondary resources when trying to realize the desired state described by the primary resource they are in charge of. For example, the Kubernetes-native Deployment controller needs to manage ReplicaSet instances as part of a Deployment’s reconciliation process. In this instance, ReplicatSet is considered a secondary resource for the Deployment controller.

Controllers that deal with secondary resources typically need to perform the following steps, for each secondary resource:

Workflows

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Kubernetes (k8s) does not have the notion of a resource “depending on” on another k8s resource, at least not in terms of the order in which these resources should be reconciled. Kubernetes operators typically need to reconcile resources in order because these resources’ state often depends on the state of other resources or cannot be processed until these other resources reach a given state or some condition holds true for them. Dealing with such scenarios are therefore rather common for operators and the purpose of the workflow feature of the Java Operator SDK (JOSDK) is to simplify supporting such cases in a declarative way. Workflows build on top of the dependent resources feature. While dependent resources focus on how a given secondary resource should be reconciled, workflows focus on orchestrating how these dependent resources should be reconciled.

Configurations

Mon, 01 Jan 0001 00:00:00 +0000

The Java Operator SDK (JOSDK) provides abstractions that work great out of the box. However, we recognize that default behavior isn’t always suitable for every use case. Numerous configuration options help you tailor the framework to your specific needs.

Configuration options operate at several levels:

Operator-level using ConfigurationService
Reconciler-level using ControllerConfiguration
DependentResource-level using the DependentResourceConfigurator interface
EventSource-level where some event sources (like InformerEventSource) need fine-tuning to identify which events trigger the associated reconciler

Operator-Level Configuration

Configuration that impacts the entire operator is performed via the ConfigurationService class. ConfigurationService is an abstract class with different implementations based on which framework flavor you use (e.g., Quarkus Operator SDK replaces the default implementation). Configurations initialize with sensible defaults but can be changed during initialization.

Logging

Mon, 01 Jan 0001 00:00:00 +0000

Contextual Info for Logging with MDC

Logging is enhanced with additional contextual information using MDC. The following attributes are available in most parts of reconciliation logic and during the execution of the controller:

MDC Key	Value added from primary resource
`resource.apiVersion`	`.apiVersion`
`resource.kind`	`.kind`
`resource.name`	`.metadata.name`
`resource.namespace`	`.metadata.namespace`
`resource.resourceVersion`	`.metadata.resourceVersion`
`resource.generation`	`.metadata.generation`
`resource.uid`	`.metadata.uid`

For more information about MDC see this link.

MDC entries during event handling

Although, usually users might not require it in their day-to-day workflow, it is worth mentioning that there are additional MDC entries managed for event handling. Typically, you might be interested in it in your SecondaryToPrimaryMapper related logs. For InformerEventSource and ControllerEventSource the following information is present:

Metrics

Mon, 01 Jan 0001 00:00:00 +0000

Runtime Info

RuntimeInfo is used mainly to check the actual health of event sources. Based on this information it is easy to implement custom liveness probes.

stopOnInformerErrorDuringStartup setting, where this flag usually needs to be set to false, in order to control the exact liveness properties.

See also an example implementation in the WebPage sample

Metrics

JOSDK provides built-in support for metrics reporting on what is happening with your reconcilers in the form of the Metrics interface which can be implemented to connect to your metrics provider of choice, JOSDK calling the methods as it goes about reconciling resources. By default, a no-operation implementation is provided thus providing a no-cost sane default. A micrometer-based implementation is also provided.

Leader Election

Mon, 01 Jan 0001 00:00:00 +0000

When running multiple replicas of an operator for high availability, leader election ensures that only one instance actively reconciles resources at a time. JOSDK uses Kubernetes Lease objects for leader election.

Enabling Leader Election

Programmatic Configuration

var operator = new Operator(o -> o.withLeaderElectionConfiguration(
 new LeaderElectionConfiguration("my-operator-lease", "operator-namespace")));

Or using the builder for full control:

import static io.javaoperatorsdk.operator.api.config.LeaderElectionConfigurationBuilder.aLeaderElectionConfiguration;

var config = aLeaderElectionConfiguration("my-operator-lease")
 .withLeaseNamespace("operator-namespace")
 .withIdentity(System.getenv("POD_NAME"))
 .withLeaseDuration(Duration.ofSeconds(15))
 .withRenewDeadline(Duration.ofSeconds(10))
 .withRetryPeriod(Duration.ofSeconds(2))
 .build();

var operator = new Operator(o -> o.withLeaderElectionConfiguration(config));

External Configuration

Leader election can also be configured via properties (e.g. environment variables or a config file).

Generic Helm Chart

Mon, 01 Jan 0001 00:00:00 +0000

A generic, reusable Helm chart for deploying Java operators built with JOSDK is available at helm/generic-helm-chart.

It is intended as a template for operator developers — a starting point that covers common deployment patterns so you don’t have to write a chart from scratch. The chart is maintained on a best-effort basis. Contributions are more than welcome.

The chart is used in the metrics-processing sample operator E2E test to deploy the operator to a cluster via Helm.

Architecture and Internals

Mon, 01 Jan 0001 00:00:00 +0000

This document provides an overview of the Java Operator SDK’s internal structure and components to help developers understand and contribute to the project. While not a comprehensive reference, it introduces core concepts that should make other components easier to understand.

The Big Picture and Core Components

An Operator is a set of independent controllers.

The Controller class is an internal class managed by the framework and typically shouldn’t be interacted with directly. It manages all processing units involved with reconciling a single type of Kubernetes resource.

Version 5.3 Released!

Fri, 13 Mar 2026 00:00:00 +0000

We’re pleased to announce the release of Java Operator SDK v5.3.0! This minor version brings two headline features — read-cache-after-write consistency and a new metrics implementation — along with a configuration adapter system, MDC improvements, and a number of smaller improvements and cleanups.

Key Features

Read-cache-after-write Consistency and Event Filtering

This is the headline feature of 5.3. Informer caches are inherently eventually consistent: after your reconciler updates a resource, there is a window of time before the change is visible in the cache. This can cause subtle bugs, particularly when storing allocated values in the status sub-resource and reading them back in the next reconciliation.

Welcome read-cache-after-write consistency!

Fri, 13 Mar 2026 00:00:00 +0000

TL;DR: In version 5.3.0 we introduced strong consistency guarantees for updates with a new API. You can now update resources (both your custom resource and managed resources) and the framework will guarantee that these updates will be instantly visible when accessing resources from caches, and naturally also for subsequent reconciliations.

I briefly talked about this topic at KubeCon last year.

public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> context) {
 
 ConfigMap managedConfigMap = prepareConfigMap(webPage);
 // apply the resource with new API
 context.resourceOperations().serverSideApply(managedConfigMap);
 
 // fresh resource instantly available from our update in the caches
 var upToDateResource = context.getSecondaryResource(ConfigMap.class);
 
 // from now on built-in update methods by default use this feature;
 // it is guaranteed that resource changes will be visible for next reconciliation
 return UpdateControl.patchStatus(alterStatusObject(webPage));
}

In addition to that, the framework will automatically filter events for your own updates, so they don’t trigger the reconciliation again.

Version 5.2 Released!

Tue, 25 Nov 2025 00:00:00 +0000

We’re pleased to announce the release of Java Operator SDK v5.2! This minor version brings several powerful new features and improvements that enhance the framework’s capabilities for building Kubernetes operators. This release focuses on flexibility, external resource management, and advanced reconciliation patterns.

Key Features

ResourceIDMapper for External Resources

One of the most significant improvements in 5.2 is the introduction of a unified approach to working with custom ID types across the framework through ResourceIDMapper and ResourceIDProvider.

How to guarantee allocated values for next reconciliation

Thu, 22 May 2025 00:00:00 +0000

Deprecated

Read-cache-after-write consistency feature replaces this functionality. (since version 5.3.0)

It provides this functionality also for secondary resources and optimistic locking is not required anymore. See the docs and related blog post for details.

We recently released v5.1 of Java Operator SDK (JOSDK). One of the highlights of this release is related to a topic of so-called allocated values.

To describe the problem, let’s say that our controller needs to create a resource that has a generated identifier, i.e. a resource which identifier cannot be directly derived from the custom resource’s desired state as specified in its spec field. To record the fact that the resource was successfully created, and to avoid attempting to recreate the resource again in subsequent reconciliations, it is typical for this type of controller to store the generated identifier in the custom resource’s status field.

From legacy approach to server-side apply

Tue, 25 Feb 2025 00:00:00 +0000

From version 5 of Java Operator SDK server side apply is a first-class feature and is used by default to update resources. As we will see, unfortunately (or fortunately), using it requires changes for your reconciler implementation.

For this reason, we prepared a feature flag, which you can flip if you are not prepared to migrate yet: ConfigurationService.useSSAToPatchPrimaryResource

Setting this flag to false will make the operations done by UpdateControl using the former approach (not SSA). Similarly, the finalizer handling won’t utilize SSA handling. The plan is to keep this flag and allow the use of the former approach (non-SSA) also in future releases.

Using k8s' ETCD as your application DB

Thu, 16 Jan 2025 00:00:00 +0000

FAQ: Is Kubernetes’ ETCD the Right Database for My Application?

Answer

While the idea of moving your application data to Custom Resources (CRs) aligns with the “Cloud Native” philosophy, it often introduces more challenges than benefits. Let’s break it down:

Top Reasons Why Storing Data in ETCD Through CRs Looks Appealing

Storing application data as CRs enables treating your application’s data like infrastructure:
- GitOps compatibility: Declarative content can be stored in Git repositories, ensuring reproducibility.
- Infrastructure alignment: Application data can follow the same workflow as other infrastructure components.

Challenges of Using Kubernetes’ ETCD as Your Application’s Database

Technical Limitations:

Data Size Limitations 🔴:

Version 5 Released!

Mon, 06 Jan 2025 00:00:00 +0000

We are excited to announce that Java Operator SDK v5 has been released. This significant effort contains various features and enhancements accumulated since the last major release and required changes in our APIs. Within this post, we will go through all the main changes and help you upgrade to this new version, and provide a rationale behind the changes if necessary.

We will omit descriptions of changes that should only require simple code updates; please do contact us if you encounter issues anyway.

Version 5 Released! (beta1)

Fri, 06 Dec 2024 00:00:00 +0000

See release notes here.

Migrating from v1 to v2

Mon, 01 Jan 0001 00:00:00 +0000

Version 2 of the framework introduces improvements, features and breaking changes for the APIs both internal and user facing ones. The migration should be however trivial in most of the cases. For detailed overview of all major issues until the release of v2.0.0 see milestone on GitHub . For a summary and reasoning behind some naming changes see this issue

User Facing API Changes

The following items are renamed and slightly changed:

Migrating from v2 to v3

Mon, 01 Jan 0001 00:00:00 +0000

Version 3 introduces some breaking changes to APIs, however the migration to these changes should be trivial.

Reconciler

Reconciler can throw checked exception (not just runtime exception), and that also can be handled by ErrorStatusHandler.
cleanup method is extracted from the Reconciler interface to a separate Cleaner interface. Finalizers only makes sense that the Cleanup is implemented, from now finalizer is only added if the Reconciler implements this interface (or has managed dependent resources implementing Deleter interface, see dependent resource docs).
Context object of Reconciler now takes the Primary resource as parametrized type: Context<MyCustomResource>.
ErrorStatusHandler result changed, it functionally has been extended to now prevent Exception to be retried and handles checked exceptions as mentioned above.

Event Sources

Event Sources are now registered with a name. But utility method is available to make it easy to migrate to a default name.
InformerEventSource constructor changed to reflect additional functionality in a non backwards compatible way. All the configuration options from the constructor where moved to InformerConfiguration . See sample usage in WebPageReconciler .
PrimaryResourcesRetriever was renamed to SecondaryToPrimaryMapper
AssociatedSecondaryResourceIdentifier was renamed to PrimaryToSecondaryMapper
getAssociatedResource is now renamed to get getSecondaryResource in multiple places

Migrating from v3 to v3.1

Mon, 01 Jan 0001 00:00:00 +0000

ReconciliationMaxInterval Annotation has been renamed to MaxReconciliationInterval

Associated methods on both the ControllerConfiguration class and annotation have also been renamed accordingly.

Workflows Impact on Managed Dependent Resources Behavior

Version 3.1 comes with a workflow engine that replaces the previous behavior of managed dependent resources. See Workflows documentation for further details. The primary impact after upgrade is a change of the order in which managed dependent resources are reconciled. They are now reconciled in parallel with optional ordering defined using the ‘depends_on’ relation to define order between resources if needed. In v3, managed dependent resources were implicitly reconciled in the order they were defined in.

Migrating from v4.2 to v4.3

Mon, 01 Jan 0001 00:00:00 +0000

Condition API Change

In Workflows the target of the condition was the managed resource itself, not the target dependent resource. This changed, now the API contains the dependent resource.

New API:

public interface Condition<R, P extends HasMetadata> {

 boolean isMet(DependentResource<R, P> dependentResource, P primary, Context<P> context);

}

Former API:

public interface Condition<R, P extends HasMetadata> {

 boolean isMet(P primary, R secondary, Context<P> context);

}

Migration is trivial. Since the secondary resource can be accessed from the dependent resource. So to access the secondary resource just use dependentResource.getSecondaryResource(primary,context).

Migrating from v4.3 to v4.4

Mon, 01 Jan 0001 00:00:00 +0000

API changes

ConfigurationService

We have simplified how to deal with the Kubernetes client. Previous versions provided direct access to underlying aspects of the client’s configuration or serialization mechanism. However, the link between these aspects wasn’t as explicit as it should have been. Moreover, the Fabric8 client framework has also revised their serialization architecture in the 6.7 version (see this fabric8 pull request for a discussion of that change), moving from statically configured serialization to a per-client configuration (though it’s still possible to share serialization mechanism between client instances). As a consequence, we made the following changes to the ConfigurationService API:

Migrating from v4.4 to v4.5

Mon, 01 Jan 0001 00:00:00 +0000

Version 4.5 introduces improvements related to event handling for Dependent Resources, more precisely the caching and event handling features. As a result the Kubernetes resources managed using KubernetesDependentResource or its subclasses, will add an annotation recording the resource’s version whenever JOSDK updates or creates such resources. This can be turned off using a feature flag if causes some issues in your use case.

Using this feature, JOSDK now tracks versions of cached resources. It also uses, by default, that information to prevent unneeded reconciliations that could occur when, depending on the timing of operations, an outdated resource would happen to be in the cache. This relies on the fact that versions (as recorded by the metadata.resourceVersion field) are currently implemented as monotonically increasing integers (though they should be considered as opaque and their interpretation discouraged). Note that, while this helps preventing unneeded reconciliations, things would eventually reach consistency even in the absence of this feature. Also, if this interpreting of the resource versions causes issues, you can turn the feature off using the following feature flag.

Migrating from v4.7 to v5.0

Mon, 01 Jan 0001 00:00:00 +0000

For migration to v5 see this blogpost.

Migrating from v5.1 to v5.2

Mon, 01 Jan 0001 00:00:00 +0000

Version 5.2 brings some breaking changes to certain components. This document provides a migration guide for these changes. For all the new features, see the release notes.

Custom ID types across multiple components using ResourceIDMapper and ResourceIDProvider

Working with the id of a resource is needed across various components in the framework. Until this version, the components provided by the framework assumed that you could easily convert the id of a resource into a String representation. For example, BulkDependentResources worked with a Map<String,R> of resources, where the id was always of type String.

Migrating from v5.2 to v5.3

Mon, 01 Jan 0001 00:00:00 +0000

Automated Migration with OpenRewrite

You can automatically apply all the migration changes described below using OpenRewrite. Add the following to your pom.xml and run mvn rewrite:run:

<plugin>
 <groupId>org.openrewrite.maven</groupId>
 <artifactId>rewrite-maven-plugin</artifactId>
 <version>6.33.0</version>
 <configuration>
 <activeRecipes>
 <recipe>io.javaoperatorsdk.operator.migration.V5_3Migration</recipe>
 </activeRecipes>
 </configuration>
 <dependencies>
 <dependency>
 <groupId>io.javaoperatorsdk</groupId>
 <artifactId>migration</artifactId>
 <version>5.3.1</version>
 </dependency>
 </dependencies>
</plugin>

Rename of JUnit module

If you use JUnit extension in your test just rename it from:

<dependency>
 <groupId>io.javaoperatorsdk</groupId>
 <artifactId>operator-framework-junit-5</artifactId>
 <version>5.2.x<version>
 <scope>test</scope>
</dependency>

<dependency>
 <groupId>io.javaoperatorsdk</groupId>
 <artifactId>operator-framework-junit</artifactId>
 <version>5.3.0<version>
 <scope>test</scope>
</dependency>

Metrics interface changes

The Metrics interface changed in non backwards compatible way, in order to make the API cleaner:

Search Results

Mon, 01 Jan 0001 00:00:00 +0000

Java Operator SDK Documentation on Java Operator SDK

Introduction to Kubernetes operators

What are Kubernetes Operators?

Why Use Java Operator SDK?

Learning Resources

Getting Started

Deep Dives

Tutorials

Bootstrapping and samples

Creating a New Operator Project

Using the Maven Plugin

Building Your Project

Patterns and best practices

Implementing a Reconciler

Always Reconcile All Resources

Implementing a reconciler

How Reconciliation Works

Error handling and retries

How Automatic Retries Work

Default Retry Behavior

Configuration Options

Rate limiting

Event sources and related topics

Handling Related Events with Event Sources

Working with EventSource caches

Other Features

Support for Well-Known Kubernetes Resources

Dependent resources

Motivations and Goals

Workflows

Overview

Configurations

Operator-Level Configuration

Logging

Contextual Info for Logging with MDC

MDC entries during event handling

Metrics

Runtime Info

Metrics

Leader Election

Enabling Leader Election

Programmatic Configuration

External Configuration

Generic Helm Chart

Architecture and Internals

The Big Picture and Core Components

Version 5.3 Released!

Key Features

Read-cache-after-write Consistency and Event Filtering

Welcome read-cache-after-write consistency!

Version 5.2 Released!

Key Features

ResourceIDMapper for External Resources

How to guarantee allocated values for next reconciliation

From legacy approach to server-side apply

Using k8s' ETCD as your application DB

FAQ: Is Kubernetes’ ETCD the Right Database for My Application?

Answer

Top Reasons Why Storing Data in ETCD Through CRs Looks Appealing

Challenges of Using Kubernetes’ ETCD as Your Application’s Database

Technical Limitations:

Version 5 Released!

Version 5 Released! (beta1)

Migrating from v1 to v2

User Facing API Changes

Migrating from v2 to v3

Reconciler

Event Sources

Migrating from v3 to v3.1

ReconciliationMaxInterval Annotation has been renamed to MaxReconciliationInterval

Workflows Impact on Managed Dependent Resources Behavior

Migrating from v4.2 to v4.3

Condition API Change

Migrating from v4.3 to v4.4

API changes

ConfigurationService

Migrating from v4.4 to v4.5

Migrating from v4.7 to v5.0

Migrating from v5.1 to v5.2

Custom ID types across multiple components using ResourceIDMapper and ResourceIDProvider