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:

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.

Testing

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

Testing is a critical part of building reliable operators. JOSDK supports multiple testing strategies, from fast unit tests that mock the Kubernetes API, to full integration tests that run your operator against a real cluster.

Unit Testing Reconcilers

The fastest way to test reconciler logic is to unit test the reconcile method directly. You can construct a mock or stub Context and call your reconciler without starting an operator or connecting to a cluster.

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

Rate limiting

Event sources and related topics

Handling Related Events with Event Sources

Working with EventSource caches

Testing

Unit Testing Reconcilers

Other Features

Support for Well-Known Kubernetes Resources

Architecture and Internals

The Big Picture and Core Components