next (5.3 do not merge)

.github/workflows/e2e-test.yml

@@ -6,14 +6,15 @@ on:
     paths-ignore:
       - 'docs/**'
       - 'adr/**'
-    branches: [ main, next ]
+    branches: [ main, next, v5.3 ]
   push:
     paths-ignore:
       - 'docs/**'
       - 'adr/**'
     branches:
       - main
       - next
+      - v5.3
 
 jobs:
   sample_operators_tests:

bootstrapper-maven-plugin/pom.xml

@@ -22,7 +22,7 @@
   <parent>
     <groupId>io.javaoperatorsdk</groupId>
     <artifactId>java-operator-sdk</artifactId>
-    <version>5.2.4-SNAPSHOT</version>
+    <version>999-SNAPSHOT</version>
   </parent>
 
   <artifactId>bootstrapper</artifactId>

bootstrapper-maven-plugin/src/main/resources/templates/pom.xml

@@ -57,7 +57,7 @@
         </dependency>
         <dependency>
             <groupId>io.javaoperatorsdk</groupId>
-            <artifactId>operator-framework-junit-5</artifactId>
+            <artifactId>operator-framework-junit</artifactId>
             <version>${josdk.version}</version>
             <scope>test</scope>
         </dependency>

caffeine-bounded-cache-support/pom.xml

@@ -21,7 +21,7 @@
   <parent>
     <groupId>io.javaoperatorsdk</groupId>
     <artifactId>java-operator-sdk</artifactId>
-    <version>5.2.4-SNAPSHOT</version>
+    <version>999-SNAPSHOT</version>
   </parent>
 
   <artifactId>caffeine-bounded-cache-support</artifactId>
@@ -43,7 +43,7 @@
     </dependency>
     <dependency>
       <groupId>io.javaoperatorsdk</groupId>
-      <artifactId>operator-framework-junit-5</artifactId>
+      <artifactId>operator-framework-junit</artifactId>
       <version>${project.version}</version>
       <scope>test</scope>
     </dependency>

docs/content/en/blog/news/primary-cache-for-next-recon.md

@@ -5,6 +5,15 @@ author: >-
   [Attila Mészáros](https://github.com/csviri) and [Chris Laprun](https://github.com/metacosm)
 ---
 
+{{% alert title="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 [details here](./../../docs/documentation/reconciler.md#read-cache-after-write-consistency-and-event-filtering).
+{{% /alert %}}
+
+
 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](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#representing-allocated-values

docs/content/en/docs/documentation/configuration.md

@@ -149,6 +149,212 @@ For more information on how to use this feature, we recommend looking at how thi
 `KubernetesDependentResource` in the core framework, `SchemaDependentResource` in the samples or `CustomAnnotationDep`
 in the `BaseConfigurationServiceTest` test class.
 
-## EventSource-level configuration
+## Loading Configuration from External Sources
+
+JOSDK ships a `ConfigLoader` that bridges any key-value configuration source to the operator and
+controller configuration APIs. This lets you drive operator behaviour from environment variables,
+system properties, YAML files, or any config library (MicroProfile Config, SmallRye Config,
+Spring Environment, etc.) without writing glue code by hand.
+
+### Architecture
+
+The system is built around two thin abstractions:
+
+- **[`ConfigProvider`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/main/java/io/javaoperatorsdk/operator/config/loader/ConfigProvider.java)**
+  — a single-method interface that resolves a typed value for a dot-separated key:
+
+  ```java
+  public interface ConfigProvider {
+      <T> Optional<T> getValue(String key, Class<T> type);
+  }
+  ```
+
+- **[`ConfigLoader`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/main/java/io/javaoperatorsdk/operator/config/loader/ConfigLoader.java)**
+  — reads all known JOSDK keys from a `ConfigProvider` and returns
+  `Consumer<ConfigurationServiceOverrider>` / `Consumer<ControllerConfigurationOverrider<R>>`
+  values that you pass directly to the `Operator` constructor or `operator.register()`.
+
+The default `ConfigLoader` (no-arg constructor) stacks environment variables over system
+properties: environment variables win, system properties are the fallback.
+
+```java
+// uses env vars + system properties out of the box
+Operator operator = new Operator(ConfigLoader.getDefault().applyConfigs());
+```
+
+### Built-in Providers
+
+| Provider | Source | Key mapping |
+|---|---|---|
+| `EnvVarConfigProvider` | `System.getenv()` | dots and hyphens → underscores, upper-cased (`josdk.check-crd` → `JOSDK_CHECK_CRD`) |
+| `PropertiesConfigProvider` | `java.util.Properties` or `.properties` file | key used as-is; use `PropertiesConfigProvider.systemProperties()` to read Java system properties |
+| `YamlConfigProvider` | YAML file | dot-separated key traverses nested mappings |
+| `AgregatePriorityListConfigProvider` | ordered list of providers | first non-empty result wins |
+
+All string-based providers convert values to the target type automatically.
+Supported types: `String`, `Boolean`, `Integer`, `Long`, `Double`, `Duration` (ISO-8601, e.g. `PT30S`).
+
+### Plugging in Any Config Library
+
+`ConfigProvider` is a single-method interface, so adapting any config library takes only a few
+lines. As an example, here is an adapter for
+[SmallRye Config](https://smallrye.io/smallrye-config/):
+
+```java
+public class SmallRyeConfigProvider implements ConfigProvider {
+
+    private final SmallRyeConfig config;
+
+    public SmallRyeConfigProvider(SmallRyeConfig config) {
+        this.config = config;
+    }
+
+    @Override
+    public <T> Optional<T> getValue(String key, Class<T> type) {
+        return config.getOptionalValue(key, type);
+    }
+}
+```
+
+The same pattern applies to MicroProfile Config, Spring `Environment`, Apache Commons
+Configuration, or any other library that can look up typed values by string key.
+
+### Wiring Everything Together
+
+Pass the `ConfigLoader` results when constructing the operator and registering reconcilers:
+
+```java
+// Load operator-wide config from a YAML file via SmallRye Config
+URL configUrl = MyOperator.class.getResource("/application.yaml");
+var configLoader = new ConfigLoader(
+    new SmallRyeConfigProvider(
+        new SmallRyeConfigBuilder()
+            .withSources(new YamlConfigSource(configUrl))
+            .build()));
+
+// applyConfigs() → Consumer<ConfigurationServiceOverrider>
+Operator operator = new Operator(configLoader.applyConfigs());
+
+// applyControllerConfigs(name) → Consumer<ControllerConfigurationOverrider<R>>
+operator.register(new MyReconciler(),
+    configLoader.applyControllerConfigs(MyReconciler.NAME));
+```
+
+Only keys that are actually present in the source are applied; everything else retains its
+programmatic or annotation-based default.
+
+You can also compose multiple sources with explicit priority using
+`AgregatePriorityListConfigProvider`:
+
+```java
+var configLoader = new ConfigLoader(
+    new AgregatePriorityListConfigProvider(List.of(
+        new EnvVarConfigProvider(),          // highest priority
+        PropertiesConfigProvider.systemProperties(),
+        new YamlConfigProvider(Path.of("config/operator.yaml"))  // lowest priority
+    )));
+```
+
+### Operator-Level Configuration Keys
+
+All operator-level keys are prefixed with `josdk.`.
+
+#### General
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.check-crd` | `Boolean` | Validate CRDs against local model on startup |
+| `josdk.close-client-on-stop` | `Boolean` | Close the Kubernetes client when the operator stops |
+| `josdk.use-ssa-to-patch-primary-resource` | `Boolean` | Use Server-Side Apply to patch the primary resource |
+| `josdk.clone-secondary-resources-when-getting-from-cache` | `Boolean` | Clone secondary resources on cache reads |
+
+#### Reconciliation
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.reconciliation.concurrent-threads` | `Integer` | Thread pool size for reconciliation |
+| `josdk.reconciliation.termination-timeout` | `Duration` | How long to wait for in-flight reconciliations to finish on shutdown |
+
+#### Workflow
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.workflow.executor-threads` | `Integer` | Thread pool size for workflow execution |
+
+#### Informer
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.informer.cache-sync-timeout` | `Duration` | Timeout for the initial informer cache sync |
+| `josdk.informer.stop-on-error-during-startup` | `Boolean` | Stop the operator if an informer fails to start |
+
+#### Dependent Resources
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.dependent-resources.ssa-based-create-update-match` | `Boolean` | Use SSA-based matching for dependent resource create/update |
+
+#### Leader Election
+
+Leader election is activated when at least one `josdk.leader-election.*` key is present.
+`josdk.leader-election.lease-name` is required when any other leader-election key is set.
+Setting `josdk.leader-election.enabled=false` suppresses leader election even if other keys are
+present.
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.leader-election.enabled` | `Boolean` | Explicitly enable (`true`) or disable (`false`) leader election |
+| `josdk.leader-election.lease-name` | `String` | **Required.** Name of the Kubernetes Lease object used for leader election |
+| `josdk.leader-election.lease-namespace` | `String` | Namespace for the Lease object (defaults to the operator's namespace) |
+| `josdk.leader-election.identity` | `String` | Unique identity for this instance; defaults to the pod name |
+| `josdk.leader-election.lease-duration` | `Duration` | How long a lease is valid (default `PT15S`) |
+| `josdk.leader-election.renew-deadline` | `Duration` | How long the leader tries to renew before giving up (default `PT10S`) |
+| `josdk.leader-election.retry-period` | `Duration` | How often a candidate polls while waiting to become leader (default `PT2S`) |
+
+### Controller-Level Configuration Keys
+
+All controller-level keys are prefixed with `josdk.controller.<controller-name>.`, where
+`<controller-name>` is the value returned by the reconciler's name (typically set via
+`@ControllerConfiguration(name = "...")`).
+
+#### General
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.controller.<name>.finalizer` | `String` | Finalizer string added to managed resources |
+| `josdk.controller.<name>.generation-aware` | `Boolean` | Skip reconciliation when the resource generation has not changed |
+| `josdk.controller.<name>.label-selector` | `String` | Label selector to filter watched resources |
+| `josdk.controller.<name>.max-reconciliation-interval` | `Duration` | Maximum interval between reconciliations even without events |
+| `josdk.controller.<name>.field-manager` | `String` | Field manager name used for SSA operations |
+| `josdk.controller.<name>.trigger-reconciler-on-all-events` | `Boolean` | Trigger reconciliation on every event, not only meaningful changes |
+
+#### Informer
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.controller.<name>.informer.label-selector` | `String` | Label selector for the primary resource informer (alias for `label-selector`) |
+| `josdk.controller.<name>.informer.list-limit` | `Long` | Page size for paginated informer list requests; omit for no pagination |
+
+#### Retry
+
+If any `retry.*` key is present, a `GenericRetry` is configured starting from the
+[default limited exponential retry](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/retry/GenericRetry.java).
+Only explicitly set keys override the defaults.
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.controller.<name>.retry.max-attempts` | `Integer` | Maximum number of retry attempts |
+| `josdk.controller.<name>.retry.initial-interval` | `Long` (ms) | Initial backoff interval in milliseconds |
+| `josdk.controller.<name>.retry.interval-multiplier` | `Double` | Exponential backoff multiplier |
+| `josdk.controller.<name>.retry.max-interval` | `Long` (ms) | Maximum backoff interval in milliseconds |
+
+#### Rate Limiter
+
+The rate limiter is only activated when `rate-limiter.limit-for-period` is present and has a
+positive value. `rate-limiter.refresh-period` is optional and falls back to the default of 10 s.
+
+| Key | Type | Description |
+|---|---|---|
+| `josdk.controller.<name>.rate-limiter.limit-for-period` | `Integer` | Maximum number of reconciliations allowed per refresh period. Must be positive to activate the limiter |
+| `josdk.controller.<name>.rate-limiter.refresh-period` | `Duration` | Window over which the limit is counted (default `PT10S`) |
 
-TODO

docs/content/en/docs/documentation/observability.md

@@ -33,6 +33,35 @@ parts of reconciliation logic and during the execution of the controller:
 
 For more information about MDC see this [link](https://www.baeldung.com/mdc-in-log4j-2-logback).
 
+### 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:
+
+| MDC Key                                        | Value from Resource from the Event               |
+|:-----------------------------------------------|:-------------------------------------------------|
+| `eventsource.event.resource.name`              | `.metadata.name`                                 |
+| `eventsource.event.resource.uid`               | `.metadata.uid`                                  |
+| `eventsource.event.resource.namespace`         | `.metadata.namespace`                            |
+| `eventsource.event.resource.kind`              | resource kind                                    |
+| `eventsource.event.resource.resourceVersion`   | `.metadata.resourceVersion`                      |
+| `eventsource.event.action`                     | action name (e.g. `ADDED`, `UPDATED`, `DELETED`) |
+| `eventsource.name`                             | name of the event source                         |
+
+### Note on null values
+
+If a resource doesn't provide values for one of the specified keys, the key will be omitted and not added to the MDC
+context. There is, however, one notable exception: the resource's namespace, where, instead of omitting the key, we emit
+the `MDCUtils.NO_NAMESPACE` value instead. This allows searching for resources without namespace (notably, clustered
+resources) in the logs more easily.
+
+### Disabling MDC support
+
+MDC support is enabled by default. If you want to disable it, you can set the `JAVA_OPERATOR_SDK_USE_MDC` environment
+variable to `false` when you start your operator.
+
 ## Metrics
 
 JOSDK provides built-in support for metrics reporting on what is happening with your reconcilers in the form of