Documentation on Java Operator SDK

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:

Event sources and related topics

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

See also this blog post .

Event sources are a relatively simple yet powerful and extensible concept to trigger controller executions, usually based on changes to dependent resources. You typically need an event source when you want your Reconciler to be triggered when something occurs to secondary resources that might affect the state of your primary resource. This is needed because a given Reconciler will only listen by default to events affecting the primary resource type it is configured for. Event sources act as listen to events affecting these secondary resources so that a reconciliation of the associated primary resource can be triggered when needed. Note that these secondary resources need not be Kubernetes resources. Typically, when dealing with non-Kubernetes objects or services, we can extend our operator to handle webhooks or websockets or to react to any event coming from a service we interact with. This allows for very efficient controller implementations because reconciliations are then only triggered when something occurs on resources affecting our primary resources thus doing away with the need to periodically reschedule reconciliations.

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.

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.

Documentation on Java Operator SDK

Implementing a reconciler

How Reconciliation Works

Error handling and retries

How Automatic Retries Work

Default Retry Behavior

Configuration Options

Event sources and related topics

Handling Related Events with Event Sources

Working with EventSource caches

Other Features

Support for Well-Known Kubernetes Resources

Architecture and Internals

The Big Picture and Core Components