cache;
diff --git a/caffeine-bounded-cache-support/src/main/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedItemStores.java b/caffeine-bounded-cache-support/src/main/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedItemStores.java
index a58d58bd2a..89fbcef70f 100644
--- a/caffeine-bounded-cache-support/src/main/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedItemStores.java
+++ b/caffeine-bounded-cache-support/src/main/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedItemStores.java
@@ -9,9 +9,9 @@
import com.github.benmanes.caffeine.cache.Caffeine;
/**
- * A factory for Caffeine-backed
- * {@link BoundedItemStore}. The implementation uses a {@link CaffeineBoundedCache} to store
- * resources and progressively evict them if they haven't been used in a while. The idea about
+ * A factory for Caffeine-backed {@link
+ * BoundedItemStore}. The implementation uses a {@link CaffeineBoundedCache} to store resources and
+ * progressively evict them if they haven't been used in a while. The idea about
* CaffeinBoundedItemStore-s is that, caffeine will cache the resources which were recently used,
* and will evict resource, which are not used for a while. This is ideal for startup performance
* and efficiency when all resources should be cached to avoid undue load on the API server. This is
@@ -20,11 +20,11 @@
* happen that some / many of these resources are then seldom or even reconciled anymore. In that
* situation, large amounts of memory might be consumed to cache resources that are never used
* again.
- *
- * Note that if a resource is reconciled and is not present anymore in cache, it will transparently
- * be fetched again from the API server. Similarly, since associated secondary resources are usually
- * reconciled too, they might need to be fetched and populated to the cache, and will remain there
- * for some time, for subsequent reconciliations.
+ *
+ *
Note that if a resource is reconciled and is not present anymore in cache, it will
+ * transparently be fetched again from the API server. Similarly, since associated secondary
+ * resources are usually reconciled too, they might need to be fetched and populated to the cache,
+ * and will remain there for some time, for subsequent reconciliations.
*/
public class CaffeineBoundedItemStores {
@@ -39,11 +39,8 @@ private CaffeineBoundedItemStores() {}
*/
@SuppressWarnings("unused")
public static BoundedItemStore boundedItemStore(
- KubernetesClient client, Class rClass,
- Duration accessExpireDuration) {
- Cache cache = Caffeine.newBuilder()
- .expireAfterAccess(accessExpireDuration)
- .build();
+ KubernetesClient client, Class rClass, Duration accessExpireDuration) {
+ Cache cache = Caffeine.newBuilder().expireAfterAccess(accessExpireDuration).build();
return boundedItemStore(client, rClass, cache);
}
@@ -51,5 +48,4 @@ public static BoundedItemStore boundedItemStore(
KubernetesClient client, Class rClass, Cache cache) {
return new BoundedItemStore<>(new CaffeineBoundedCache<>(cache), rClass, client);
}
-
}
diff --git a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/BoundedCacheTestBase.java b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/BoundedCacheTestBase.java
index 21adf81cc0..532e5237f8 100644
--- a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/BoundedCacheTestBase.java
+++ b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/BoundedCacheTestBase.java
@@ -17,7 +17,8 @@
import static org.assertj.core.api.Assertions.assertThat;
import static org.awaitility.Awaitility.await;
-public abstract class BoundedCacheTestBase> {
+public abstract class BoundedCacheTestBase<
+ P extends CustomResource> {
private static final Logger log = LoggerFactory.getLogger(BoundedCacheTestBase.class);
@@ -42,34 +43,46 @@ void reconciliationWorksWithLimitedCache() {
}
private void assertConfigMapsDeleted() {
- await().atMost(Duration.ofSeconds(30))
- .untilAsserted(() -> IntStream.range(0, NUMBER_OF_RESOURCE_TO_TEST).forEach(i -> {
- var cm = extension().get(ConfigMap.class, RESOURCE_NAME_PREFIX + i);
- assertThat(cm).isNull();
- }));
+ await()
+ .atMost(Duration.ofSeconds(120))
+ .untilAsserted(
+ () ->
+ IntStream.range(0, NUMBER_OF_RESOURCE_TO_TEST)
+ .forEach(
+ i -> {
+ var cm = extension().get(ConfigMap.class, RESOURCE_NAME_PREFIX + i);
+ assertThat(cm).isNull();
+ }));
}
private void deleteTestResources() {
- IntStream.range(0, NUMBER_OF_RESOURCE_TO_TEST).forEach(i -> {
- var cm = extension().get(customResourceClass(), RESOURCE_NAME_PREFIX + i);
- var deleted = extension().delete(cm);
- if (!deleted) {
- log.warn("Custom resource might not be deleted: {}", cm);
- }
- });
+ IntStream.range(0, NUMBER_OF_RESOURCE_TO_TEST)
+ .forEach(
+ i -> {
+ var cm = extension().get(customResourceClass(), RESOURCE_NAME_PREFIX + i);
+ var deleted = extension().delete(cm);
+ if (!deleted) {
+ log.warn("Custom resource might not be deleted: {}", cm);
+ }
+ });
}
private void updateTestResources() {
- IntStream.range(0, NUMBER_OF_RESOURCE_TO_TEST).forEach(i -> {
- var cm = extension().get(ConfigMap.class, RESOURCE_NAME_PREFIX + i);
- cm.getData().put(DATA_KEY, UPDATED_PREFIX + i);
- extension().replace(cm);
- });
+ IntStream.range(0, NUMBER_OF_RESOURCE_TO_TEST)
+ .forEach(
+ i -> {
+ var cm = extension().get(ConfigMap.class, RESOURCE_NAME_PREFIX + i);
+ cm.getData().put(DATA_KEY, UPDATED_PREFIX + i);
+ extension().replace(cm);
+ });
}
void assertConfigMapData(String dataPrefix) {
- await().untilAsserted(() -> IntStream.range(0, NUMBER_OF_RESOURCE_TO_TEST)
- .forEach(i -> assertConfigMap(i, dataPrefix)));
+ await()
+ .untilAsserted(
+ () ->
+ IntStream.range(0, NUMBER_OF_RESOURCE_TO_TEST)
+ .forEach(i -> assertConfigMap(i, dataPrefix)));
}
private void assertConfigMap(int i, String prefix) {
@@ -79,9 +92,11 @@ private void assertConfigMap(int i, String prefix) {
}
private void createTestResources() {
- IntStream.range(0, NUMBER_OF_RESOURCE_TO_TEST).forEach(i -> {
- extension().create(createTestResource(i));
- });
+ IntStream.range(0, NUMBER_OF_RESOURCE_TO_TEST)
+ .forEach(
+ i -> {
+ extension().create(createTestResource(i));
+ });
}
abstract P createTestResource(int index);
@@ -89,7 +104,4 @@ private void createTestResources() {
abstract Class customResourceClass();
abstract LocallyRunOperatorExtension extension();
-
-
-
}
diff --git a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedCacheClusterScopeIT.java b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedCacheClusterScopeIT.java
index 252b20f4a4..0c16c1227b 100644
--- a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedCacheClusterScopeIT.java
+++ b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedCacheClusterScopeIT.java
@@ -19,21 +19,22 @@ public class CaffeineBoundedCacheClusterScopeIT
@RegisterExtension
LocallyRunOperatorExtension extension =
LocallyRunOperatorExtension.builder()
- .withReconciler(new BoundedCacheClusterScopeTestReconciler(), o -> {
- o.withItemStore(boundedItemStore(
- new KubernetesClientBuilder().build(),
- BoundedCacheClusterScopeTestCustomResource.class,
- Duration.ofMinutes(1),
- 1));
- })
+ .withReconciler(
+ new BoundedCacheClusterScopeTestReconciler(),
+ o -> {
+ o.withItemStore(
+ boundedItemStore(
+ new KubernetesClientBuilder().build(),
+ BoundedCacheClusterScopeTestCustomResource.class,
+ Duration.ofMinutes(1),
+ 1));
+ })
.build();
@Override
BoundedCacheClusterScopeTestCustomResource createTestResource(int index) {
var res = new BoundedCacheClusterScopeTestCustomResource();
- res.setMetadata(new ObjectMetaBuilder()
- .withName(RESOURCE_NAME_PREFIX + index)
- .build());
+ res.setMetadata(new ObjectMetaBuilder().withName(RESOURCE_NAME_PREFIX + index).build());
res.setSpec(new BoundedCacheTestSpec());
res.getSpec().setData(INITIAL_DATA_PREFIX + index);
res.getSpec().setTargetNamespace(extension.getNamespace());
diff --git a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedCacheNamespacedIT.java b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedCacheNamespacedIT.java
index ae7f8f5873..534d7b2027 100644
--- a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedCacheNamespacedIT.java
+++ b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedCacheNamespacedIT.java
@@ -18,19 +18,22 @@ class CaffeineBoundedCacheNamespacedIT
@RegisterExtension
LocallyRunOperatorExtension extension =
- LocallyRunOperatorExtension.builder().withReconciler(new BoundedCacheTestReconciler(), o -> {
- o.withItemStore(boundedItemStore(
- new KubernetesClientBuilder().build(), BoundedCacheTestCustomResource.class,
- Duration.ofMinutes(1),
- 1));
- })
+ LocallyRunOperatorExtension.builder()
+ .withReconciler(
+ new BoundedCacheTestReconciler(),
+ o -> {
+ o.withItemStore(
+ boundedItemStore(
+ new KubernetesClientBuilder().build(),
+ BoundedCacheTestCustomResource.class,
+ Duration.ofMinutes(1),
+ 1));
+ })
.build();
BoundedCacheTestCustomResource createTestResource(int index) {
var res = new BoundedCacheTestCustomResource();
- res.setMetadata(new ObjectMetaBuilder()
- .withName(RESOURCE_NAME_PREFIX + index)
- .build());
+ res.setMetadata(new ObjectMetaBuilder().withName(RESOURCE_NAME_PREFIX + index).build());
res.setSpec(new BoundedCacheTestSpec());
res.getSpec().setData(INITIAL_DATA_PREFIX + index);
res.getSpec().setTargetNamespace(extension.getNamespace());
@@ -46,5 +49,4 @@ Class customResourceClass() {
LocallyRunOperatorExtension extension() {
return extension;
}
-
}
diff --git a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/AbstractTestReconciler.java b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/AbstractTestReconciler.java
index 9d912986e1..b059ac033b 100644
--- a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/AbstractTestReconciler.java
+++ b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/AbstractTestReconciler.java
@@ -28,7 +28,8 @@
import com.github.benmanes.caffeine.cache.Cache;
import com.github.benmanes.caffeine.cache.Caffeine;
-public abstract class AbstractTestReconciler>
+public abstract class AbstractTestReconciler<
+ P extends CustomResource>
implements Reconciler {
private static final Logger log =
@@ -37,9 +38,7 @@ public abstract class AbstractTestReconciler
reconcile(
- P resource,
- Context
context) {
+ public UpdateControl
reconcile(P resource, Context
context) {
var maybeConfigMap = context.getSecondaryResource(ConfigMap.class);
maybeConfigMap.ifPresentOrElse(
cm -> updateConfigMapIfNeeded(cm, resource, context),
@@ -58,33 +57,39 @@ protected void updateConfigMapIfNeeded(ConfigMap cm, P resource, Context
cont
}
protected void createConfigMap(P resource, Context
context) {
- var cm = new ConfigMapBuilder()
- .withMetadata(new ObjectMetaBuilder()
- .withName(resource.getMetadata().getName())
- .withNamespace(resource.getSpec().getTargetNamespace())
- .build())
- .withData(Map.of(DATA_KEY, resource.getSpec().getData()))
- .build();
+ var cm =
+ new ConfigMapBuilder()
+ .withMetadata(
+ new ObjectMetaBuilder()
+ .withName(resource.getMetadata().getName())
+ .withNamespace(resource.getSpec().getTargetNamespace())
+ .build())
+ .withData(Map.of(DATA_KEY, resource.getSpec().getData()))
+ .build();
cm.addOwnerReference(resource);
context.getClient().configMaps().resource(cm).create();
}
@Override
- public List> prepareEventSources(
- EventSourceContext context) {
+ public List> prepareEventSources(EventSourceContext context) {
var boundedItemStore =
- boundedItemStore(new KubernetesClientBuilder().build(),
- ConfigMap.class, Duration.ofMinutes(1), 1); // setting max size for testing purposes
-
- var es = new InformerEventSource<>(
- InformerEventSourceConfiguration.from(ConfigMap.class, primaryClass())
- .withInformerConfiguration(c -> c.withItemStore(boundedItemStore))
- .withSecondaryToPrimaryMapper(
- Mappers.fromOwnerReferences(context.getPrimaryResourceClass(),
- this instanceof BoundedCacheClusterScopeTestReconciler))
- .build(),
- context);
+ boundedItemStore(
+ new KubernetesClientBuilder().build(),
+ ConfigMap.class,
+ Duration.ofMinutes(1),
+ 1); // setting max size for testing purposes
+
+ var es =
+ new InformerEventSource<>(
+ InformerEventSourceConfiguration.from(ConfigMap.class, primaryClass())
+ .withItemStore(boundedItemStore)
+ .withSecondaryToPrimaryMapper(
+ Mappers.fromOwnerReferences(
+ context.getPrimaryResourceClass(),
+ this instanceof BoundedCacheClusterScopeTestReconciler))
+ .build(),
+ context);
return List.of(es);
}
@@ -96,17 +101,18 @@ private void ensureStatus(P resource) {
}
public static BoundedItemStore boundedItemStore(
- KubernetesClient client, Class rClass,
+ KubernetesClient client,
+ Class rClass,
Duration accessExpireDuration,
// max size is only for testing purposes
long cacheMaxSize) {
- Cache cache = Caffeine.newBuilder()
- .expireAfterAccess(accessExpireDuration)
- .maximumSize(cacheMaxSize)
- .build();
+ Cache cache =
+ Caffeine.newBuilder()
+ .expireAfterAccess(accessExpireDuration)
+ .maximumSize(cacheMaxSize)
+ .build();
return CaffeineBoundedItemStores.boundedItemStore(client, rClass, cache);
}
protected abstract Class primaryClass();
-
}
diff --git a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/clusterscope/BoundedCacheClusterScopeTestCustomResource.java b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/clusterscope/BoundedCacheClusterScopeTestCustomResource.java
index a77416715e..6fc9a5babc 100644
--- a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/clusterscope/BoundedCacheClusterScopeTestCustomResource.java
+++ b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/clusterscope/BoundedCacheClusterScopeTestCustomResource.java
@@ -11,5 +11,4 @@
@Version("v1")
@ShortNames("bccs")
public class BoundedCacheClusterScopeTestCustomResource
- extends CustomResource {
-}
+ extends CustomResource {}
diff --git a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/clusterscope/BoundedCacheClusterScopeTestReconciler.java b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/clusterscope/BoundedCacheClusterScopeTestReconciler.java
index 84448fc9d8..93f103cbf2 100644
--- a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/clusterscope/BoundedCacheClusterScopeTestReconciler.java
+++ b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/clusterscope/BoundedCacheClusterScopeTestReconciler.java
@@ -4,8 +4,8 @@
import io.javaoperatorsdk.operator.processing.event.source.cache.sample.AbstractTestReconciler;
@ControllerConfiguration
-public class BoundedCacheClusterScopeTestReconciler extends
- AbstractTestReconciler {
+public class BoundedCacheClusterScopeTestReconciler
+ extends AbstractTestReconciler {
@Override
protected Class primaryClass() {
diff --git a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/namespacescope/BoundedCacheTestCustomResource.java b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/namespacescope/BoundedCacheTestCustomResource.java
index a5e37917ba..9b77aa7bf8 100644
--- a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/namespacescope/BoundedCacheTestCustomResource.java
+++ b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/namespacescope/BoundedCacheTestCustomResource.java
@@ -10,5 +10,4 @@
@Version("v1")
@ShortNames("bct")
public class BoundedCacheTestCustomResource
- extends CustomResource implements Namespaced {
-}
+ extends CustomResource implements Namespaced {}
diff --git a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/namespacescope/BoundedCacheTestStatus.java b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/namespacescope/BoundedCacheTestStatus.java
index 2bdd434d23..5aa5ca2258 100644
--- a/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/namespacescope/BoundedCacheTestStatus.java
+++ b/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/namespacescope/BoundedCacheTestStatus.java
@@ -1,4 +1,3 @@
package io.javaoperatorsdk.operator.processing.event.source.cache.sample.namespacescope;
-public class BoundedCacheTestStatus {
-}
+public class BoundedCacheTestStatus {}
diff --git a/contributing/eclipse-google-style.xml b/contributing/eclipse-google-style.xml
deleted file mode 100644
index 64340b1054..0000000000
--- a/contributing/eclipse-google-style.xml
+++ /dev/null
@@ -1,337 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/contributing/eclipse.importorder b/contributing/eclipse.importorder
deleted file mode 100644
index 8a156041e9..0000000000
--- a/contributing/eclipse.importorder
+++ /dev/null
@@ -1,7 +0,0 @@
-0=java
-1=javax
-2=org
-3=io
-4=com
-5=
-6=\#
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index db177d4ac7..5ea571c69d 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -1,28 +1,57 @@
-# How to Contribute
+# Contributing to Java Operator SDK Documentation
-We'd love to accept your patches and contributions to this project. There are
-just a few small guidelines you need to follow.
+Thank you for your interest in improving the Java Operator SDK documentation! We welcome contributions from the community and appreciate your help in making our documentation better.
-## Contributor License Agreement
+## How to Contribute
-Contributions to this project must be accompanied by a Contributor License
-Agreement. You (or your employer) retain the copyright to your contribution;
-this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to to see
-your current agreements on file or to sign a new one.
+### Getting Started
-You generally only need to submit a CLA once, so if you've already submitted one
-(even if it was for a different project), you probably don't need to do it
-again.
+1. **Fork the repository** and clone your fork locally
+2. **Create a new branch** for your changes
+3. **Make your improvements** to the documentation
+4. **Test your changes** locally using `hugo server`
+5. **Submit a pull request** with a clear description of your changes
-## Code reviews
+### Types of Contributions
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
+We welcome various types of contributions:
+
+- **Content improvements**: Fix typos, clarify explanations, add examples
+- **New documentation**: Add missing sections or entirely new guides
+- **Structural improvements**: Better organization, navigation, or formatting
+- **Translation**: Help translate documentation to other languages
+
+## Guidelines
+
+### Writing Style
+
+- Use clear, concise language
+- Write in active voice when possible
+- Define technical terms when first used
+- Include practical examples where helpful
+- Keep sentences and paragraphs reasonably short
+
+### Technical Requirements
+
+- Test all code examples to ensure they work
+- Use proper markdown formatting
+- Follow existing documentation structure and conventions
+- Ensure links work and point to current resources
+
+## Legal Requirements
+
+### Contributor License Agreement
+
+All contributions must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; the CLA simply gives us permission to use and redistribute your contributions as part of the project.
+
+Visit to see your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one (even for a different project), you probably don't need to do it again.
+
+### Code Review Process
+
+All submissions, including those by project members, require review. We use GitHub pull requests for this purpose. Please consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests.
## Community Guidelines
-This project follows
-[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
+This project follows [Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
diff --git a/docs/README.md b/docs/README.md
index f9d6ce7183..14f675b53b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,190 +1,82 @@
-# JOSDK comments:
+# Java Operator SDK Documentation
-see: sample github action: https://gohugo.io/hosting-and-deployment/hosting-on-github/
+This repository contains the documentation website for the Java Operator SDK (JOSDK), built using Hugo and the Docsy theme.
-currently use hugo version v0.125.7
+## About Java Operator SDK
-# Docsy Example
+Java Operator SDK is a framework that makes it easy to build Kubernetes operators in Java. It provides APIs designed to feel natural to Java developers and handles common operator challenges automatically, allowing you to focus on your business logic.
-[Docsy][] is a [Hugo theme module][] for technical documentation sites, providing easy
-site navigation, structure, and more. This **Docsy Example Project** uses the Docsy
-theme component as a hugo module and provides a skeleton documentation structure for you to use.
-You can clone/copy this project and edit it with your own content, or use it as an example.
+## Development Setup
-In this project, the Docsy theme is pulled in as a Hugo module, together with
-its dependencies:
+This documentation site uses Hugo v0.125.7 with the Docsy theme.
-```console
-$ hugo mod graph
-...
-```
-
-For Docsy documentation, see [Docsy user guide][].
-
-This Docsy Example Project is hosted on [Netlify][] at [example.docsy.dev][].
-You can view deploy logs from the [deploy section of the project's Netlify
-dashboard][deploys], or this [alternate dashboard][].
-
-This is not an officially supported Google product. This project is currently maintained.
-
-## Using the Docsy Example Project as a template
-
-A simple way to get started is to use this project as a template, which gives you a site project that is set up and ready to use. To do this:
-
-1. Use the dropdown for switching branches/tags to change to the **latest** released tag.
-
-2. Click **Use this template**.
-
-3. Select a name for your new project and click **Create repository from template**.
-
-4. Make your own local working copy of your new repo using git clone, replacing https://github.com/me/example.git with your repo’s web URL:
-
-```bash
-git clone --depth 1 https://github.com/me/example.git
-```
+## Prerequisites
-You can now edit your own versions of the site’s source files.
+- Hugo v0.125.7 or later (extended version required)
+- Node.js and npm (for PostCSS processing)
+- Git
-If you want to do SCSS edits and want to publish these, you need to install `PostCSS`
+## Local Development
-```bash
-npm install
-```
-
-## Running the website locally
-
-Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
-You can find out more about how to install Hugo for your environment in our
-[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide.
-
-Once you've made your working copy of the site repo, from the repo root folder, run:
-
-```bash
-hugo server
-```
+### Quick Start
-## Running a container locally
+1. Clone this repository
+2. Install dependencies:
+ ```bash
+ npm install
+ ```
+3. Start the development server:
+ ```bash
+ hugo server
+ ```
+4. Open your browser to `http://localhost:1313`
-You can run docsy-example inside a [Docker](https://docs.docker.com/)
-container, the container runs with a volume bound to the `docsy-example`
-folder. This approach doesn't require you to install any dependencies other
-than [Docker Desktop](https://www.docker.com/products/docker-desktop) on
-Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/)
-on Linux.
+### Using Docker
-1. Build the docker image
+You can also run the documentation site using Docker:
+1. Build the container:
```bash
docker-compose build
```
-
-1. Run the built image
-
+2. Run the container:
```bash
docker-compose up
```
+ > **Note**: You can combine both commands with `docker-compose up --build`
- > NOTE: You can run both commands at once with `docker-compose up --build`.
+3. Access the site at `http://localhost:1313`
-1. Verify that the service is working.
-
- Open your web browser and type `http://localhost:1313` in your navigation bar,
- This opens a local instance of the docsy-example homepage. You can now make
- changes to the docsy example and those changes will immediately show up in your
- browser after you save.
-
-### Cleanup
-
-To stop Docker Compose, on your terminal window, press **Ctrl + C**.
-
-To remove the produced images run:
+To stop the container, press **Ctrl + C** in your terminal.
+To clean up Docker resources:
```bash
docker-compose rm
```
-For more information see the [Docker Compose documentation][].
-
-## Using a local Docsy clone
-
-Make sure your installed go version is `1.18` or higher.
-
-Clone the latest version of the docsy theme into the parent folder of your project. The newly created repo should now reside in a sibling folder of your site's root folder.
-
-```shell
-cd root-of-your-site
-git clone --branch v0.7.2 https://github.com/google/docsy.git ../docsy
-```
-
-Now run:
-
-```shell
-HUGO_MODULE_WORKSPACE=docsy.work hugo server --ignoreVendorPaths "**"
-```
-
-or, when using npm, prepend `local` to the script you want to invoke, e.g.:
-
-```shell
-npm run local serve
-```
-
-By using the `HUGO_MODULE_WORKSPACE` directive (either directly or via prefix `local` when using npm), the server now watches all files and directories inside the sibling directory `../docsy` , too. Any changes inside the local `docsy` theme clone are now immediately picked up (hot reload), you can instantly see the effect of your local edits.
-In the command above, we used the environment variable `HUGO_MODULE_WORKSPACE` to tell hugo about the local workspace file `docsy.work`. Alternatively, you can declare the workspace file inside your settings file `hugo.toml`:
-
-```toml
-[module]
- workspace = "docsy.work"
-```
+## Contributing
-Your project's `hugo.toml` file already contains these lines, the directive for workspace assignment is commented out, however. Remove the two trailing comment characters '//' so that this line takes effect.
+We welcome contributions to improve the documentation! Please see our [contribution guidelines](CONTRIBUTING.md) for details on how to get started.
## Troubleshooting
-As you run the website locally, you may run into the following error:
-
-```console
-$ hugo server
-WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information.
-Start building sites …
-hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio
-Error: Error building site: "C:\Users\foo\path\to\docsy-example\content\en\_index.md:5:1": failed to extract shortcode: template for shortcode "blocks/cover" not found
-Built in 27 ms
-```
-
-This error occurs if you are running an outdated version of Hugo. As of docsy theme version `v0.7.0`, hugo version `0.110.0` or higher is required.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
-
-Or you may be confronted with the following error:
-
+### Module Compatibility Error
+If you see an error about module compatibility, ensure you're using Hugo v0.110.0 or higher:
```console
-$ hugo server
-
-INFO 2021/01/21 21:07:55 Using config file:
-Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
-Built in 288 ms
-Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
+Error: Error building site: failed to extract shortcode: template for shortcode "blocks/cover" not found
```
-This error occurs if you have not installed the extended version of Hugo.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
-
-Or you may encounter the following error:
-
+### SCSS Processing Error
+If you encounter SCSS-related errors, make sure you have the extended version of Hugo installed:
```console
-$ hugo server
-
-Error: failed to download modules: binary with name "go" not found
+Error: TOCSS: failed to transform "scss/main.scss"
```
-This error occurs if you have not installed the `go` programming language on your system.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`.
+### Go Binary Not Found
+If you see "binary with name 'go' not found", install the Go programming language from [golang.org](https://golang.org).
+## Links
-[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys
-[deploys]: https://app.netlify.com/sites/docsy-example/deploys
-[Docsy user guide]: https://docsy.dev/docs
-[Docsy]: https://github.com/google/docsy
-[example.docsy.dev]: https://example.docsy.dev
-[Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme
-[Netlify]: https://netlify.com
-[Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/
+- [Hugo Documentation](https://gohugo.io/documentation/)
+- [Docsy Theme Documentation](https://www.docsy.dev/docs/)
+- [Java Operator SDK GitHub Repository](https://github.com/operator-framework/java-operator-sdk)
diff --git a/docs/content/en/_index.md b/docs/content/en/_index.md
index f2124a21a2..f375ebfb97 100644
--- a/docs/content/en/_index.md
+++ b/docs/content/en/_index.md
@@ -33,7 +33,7 @@ We do a [Pull Request](https://github.com/operator-framework/java-operator-sdk/p
{{% /blocks/feature %}}
-{{% blocks/feature icon="fab fa-twitter" title="Follow us on Twitter!" url="https://twitter.com/javaoperatorsdk" %}}
+{{% blocks/feature icon="fa-brands fa-bluesky" title="Follow us on BlueSky!" url="https://bsky.app/profile/javaoperatorsdk.bsky.social" %}}
For announcement of latest features etc.
{{% /blocks/feature %}}
diff --git a/docs/content/en/blog/_index.md b/docs/content/en/blog/_index.md
index c8219f7994..e792e415fe 100644
--- a/docs/content/en/blog/_index.md
+++ b/docs/content/en/blog/_index.md
@@ -1,6 +1,6 @@
---
title: Blog
-menu: {main: {weight: 30}}
+menu: {main: {weight: 2}}
---
This is the **blog** section. It has two categories: News and Releases.
diff --git a/docs/content/en/blog/news/_index.md b/docs/content/en/blog/news/_index.md
index c609aa2543..aaf1c2adcd 100644
--- a/docs/content/en/blog/news/_index.md
+++ b/docs/content/en/blog/news/_index.md
@@ -1,4 +1,4 @@
---
-title: News
-weight: 20
+title: Posts
+weight: 220
---
diff --git a/docs/content/en/blog/news/etcd-as-app-db.md b/docs/content/en/blog/news/etcd-as-app-db.md
new file mode 100644
index 0000000000..c6306ddffc
--- /dev/null
+++ b/docs/content/en/blog/news/etcd-as-app-db.md
@@ -0,0 +1,115 @@
+---
+title: Using k8s' ETCD as your application DB
+date: 2025-01-16
+---
+
+# 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
+
+1. **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 🔴:**
+ - Each CR is capped at 1.5 MB by default. Raising this limit is possible but impacts cluster performance.
+ - Kubernetes ETCD has a storage cap of 2 GB by default. Adjusting this limit affects the cluster globally, with potential performance degradation.
+
+- **API Server Load Considerations 🟡:**
+ - The Kubernetes API server is designed to handle infrastructure-level requests.
+ - Storing application data in CRs might add significant load to the API server, requiring it to be scaled appropriately to handle both infrastructure and application demands.
+ - This added load can impact cluster performance and increase operational complexity.
+
+- **Guarantees 🟡:**
+ - Efficient queries are hard to implement and there is no support for them.
+ - ACID properties are challenging to leverage and everything holds mostly in read-only mode.
+
+#### Operational Impact:
+
+- **Lost Flexibility 🟡:**
+ - Modifying application data requires complex YAML editing and full redeployment.
+ - This contrasts with traditional databases that often feature user-friendly web UIs or APIs for real-time updates.
+
+- **Infrastructure Complexity 🟠:**
+ - Backup, restore, and lifecycle management for application data are typically separate from deployment workflows.
+ - Storing both in ETCD mixes these concerns, complicating operations and standardization.
+
+#### Security:
+
+- **Governance and Security 🔴:**
+ - Sensitive data stored in plain YAML may lack adequate encryption or access controls.
+ - Applying governance policies over text-based files can become a significant challenge.
+
+---
+
+### When Might Using CRs Make Sense?
+
+For small, safe subsets of data—such as application configurations—using CRs might be appropriate. However, this approach requires a detailed evaluation of the trade-offs.
+
+---
+
+### Conclusion
+
+While it’s tempting to unify application data with infrastructure control via CRs, this introduces risks that can outweigh the benefits. For most applications, separating concerns by using a dedicated database is the more robust, scalable, and manageable solution.
+
+---
+
+### A Practical Example
+
+A typical “user” described in JSON:
+
+```json
+{
+ "username": "myname",
+ "enabled": true,
+ "email": "myname@test.com",
+ "firstName": "MyFirstName",
+ "lastName": "MyLastName",
+ "credentials": [
+ {
+ "type": "password",
+ "value": "test"
+ },
+ {
+ "type": "token",
+ "value": "oidc"
+ }
+ ],
+ "realmRoles": [
+ "user",
+ "viewer",
+ "admin"
+ ],
+ "clientRoles": {
+ "account": [
+ "view-profile",
+ "change-group",
+ "manage-account"
+ ]
+ }
+}
+```
+
+This example represents about **0.5 KB of data**, meaning (with standard settings) a maximum of ~2000 users can be defined in the same CR.
+Additionally:
+
+- It contains **sensitive information**, which should be securely stored.
+- Regulatory rules (like GDPR) apply.
+
+---
+
+### References
+
+- [Using etcd as primary store database](https://stackoverflow.com/questions/41063238/using-etcd-as-primary-store-database)
diff --git a/docs/content/en/blog/news/nonssa-vs-ssa.md b/docs/content/en/blog/news/nonssa-vs-ssa.md
new file mode 100644
index 0000000000..8ea7497771
--- /dev/null
+++ b/docs/content/en/blog/news/nonssa-vs-ssa.md
@@ -0,0 +1,117 @@
+---
+title: From legacy approach to server-side apply
+date: 2025-02-25
+author: >-
+ [Attila Mészáros](https://github.com/csviri)
+---
+
+From version 5 of Java Operator SDK [server side apply](https://kubernetes.io/docs/reference/using-api/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`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L493)
+
+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.
+
+For dependent resources, a separate flag exists (this was true also before v5) to use SSA or not:
+[`ConfigurationService.ssaBasedCreateUpdateMatchForDependentResources`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L373)
+
+
+## Resource handling without and with SSA
+
+Until version 5, changing primary resources through `UpdateControl` did not use server-side apply.
+So usually, the implementation of the reconciler looked something like this:
+
+```java
+
+ @Override
+ public UpdateControl reconcile(WebPage webPage, Context context) {
+
+ reconcileLogicForManagedResources(webPage);
+ webPage.setStatus(updatedStatusForWebPage(webPage));
+
+ return UpdateControl.patchStatus(webPage);
+ }
+
+```
+
+In other words, after the reconciliation of managed resources, the reconciler updates the status of the
+primary resource passed as an argument to the reconciler.
+Such changes on the primary are fine since we don't work directly with the cached object, the argument is
+already cloned.
+
+So, how does this change with SSA?
+For SSA, the updates should contain (only) the "fully specified intent".
+In other words, we should only fill in the values we care about.
+In practice, it means creating a **fresh copy** of the resource and setting only what is necessary:
+
+```java
+
+@Override
+public UpdateControl reconcile(WebPage webPage, Context context) {
+
+ reconcileLogicForManagedResources(webPage);
+
+ WebPage statusPatch = new WebPage();
+ statusPatch.setMetadata(new ObjectMetaBuilder()
+ .withName(webPage.getMetadata().getName())
+ .withNamespace(webPage.getMetadata().getNamespace())
+ .build());
+ statusPatch.setStatus(updatedStatusForWebPage(webPage));
+
+ return UpdateControl.patchStatus(statusPatch);
+}
+```
+
+Note that we just filled out the status here since we patched the status (not the resource spec).
+Since the status is a sub-resource in Kubernetes, it will only update the status part.
+
+Every controller you register will have its default [field manager](https://kubernetes.io/docs/reference/using-api/server-side-apply/#managers).
+You can override the field manager name using [`ControllerConfiguration.fieldManager`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ControllerConfiguration.java#L89).
+That will set the field manager for the primary resource and dependent resources as well.
+
+## Migrating to SSA
+
+Using the legacy or the new SSA way of resource management works well.
+However, migrating existing resources to SSA might be a challenge.
+We strongly recommend testing the migration, thus implementing an integration test where
+a custom resource is created using the legacy approach and is managed by the new approach.
+
+We prepared an integration test to demonstrate how such migration, even in a simple case, can go wrong,
+and how to fix it.
+
+To fix some cases, you might need to [strip managed fields](https://kubernetes.io/docs/reference/using-api/server-side-apply/#clearing-managedfields)
+from the custom resource.
+
+See [`StatusPatchSSAMigrationIT`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/statuspatchnonlocking/StatusPatchSSAMigrationIT.java) for details.
+
+Feel free to report common issues, so we can prepare some utilities to handle them.
+
+## Optimistic concurrency control
+
+When you create a resource for SSA as mentioned above, the framework will apply changes even if the underlying resource
+or status subresource is changed while the reconciliation was running.
+First, it always forces the conflicts in the background as advised in [Kubernetes docs](https://kubernetes.io/docs/reference/using-api/server-side-apply/#using-server-side-apply-in-a-controller),
+ in addition to that since the resource version is not set it won't do optimistic locking. If you still
+want to have optimistic locking for the patch, use the resource version of the original resource:
+
+```java
+@Override
+public UpdateControl reconcile(WebPage webPage, Context context) {
+
+ reconcileLogicForManagedResources(webPage);
+
+ WebPage statusPatch = new WebPage();
+ statusPatch.setMetadata(new ObjectMetaBuilder()
+ .withName(webPage.getMetadata().getName())
+ .withNamespace(webPage.getMetadata().getNamespace())
+ .withResourceVersion(webPage.getMetadata().getResourceVersion())
+ .build());
+ statusPatch.setStatus(updatedStatusForWebPage(webPage));
+
+ return UpdateControl.patchStatus(statusPatch);
+}
+```
diff --git a/docs/content/en/blog/news/primary-cache-for-next-recon.md b/docs/content/en/blog/news/primary-cache-for-next-recon.md
new file mode 100644
index 0000000000..67326a6f17
--- /dev/null
+++ b/docs/content/en/blog/news/primary-cache-for-next-recon.md
@@ -0,0 +1,92 @@
+---
+title: How to guarantee allocated values for next reconciliation
+date: 2025-05-22
+author: >-
+ [Attila Mészáros](https://github.com/csviri) and [Chris Laprun](https://github.com/metacosm)
+---
+
+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
+).
+
+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.
+
+The Java Operator SDK relies on the informers' cache to retrieve resources. These caches, however, are only guaranteed
+to be eventually consistent. It could happen that, if some other event occurs, that would result in a new
+reconciliation, **before** the update that's been made to our resource status has the chance to be propagated first to
+the cluster and then back to the informer cache, that the resource in the informer cache does **not** contain the latest
+version as modified by the reconciler. This would result in a new reconciliation where the generated identifier would be
+missing from the resource status and, therefore, another attempt to create the resource by the reconciler, which is not
+what we'd like.
+
+Java Operator SDK now provides a utility class [
+`PrimaryUpdateAndCacheUtils`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/PrimaryUpdateAndCacheUtils.java)
+to handle this particular use case. Using that overlay cache, your reconciler is guaranteed to see the most up-to-date
+version of the resource on the next reconciliation:
+
+```java
+
+@Override
+public UpdateControl reconcile(
+ StatusPatchCacheCustomResource resource,
+ Context context) {
+
+ // omitted code
+
+ var freshCopy = createFreshCopy(resource); // need fresh copy just because we use the SSA version of update
+ freshCopy
+ .getStatus()
+ .setValue(statusWithAllocatedValue());
+
+ // using the utility instead of update control to patch the resource status
+ var updated =
+ PrimaryUpdateAndCacheUtils.ssaPatchStatusAndCacheResource(resource, freshCopy, context);
+ return UpdateControl.noUpdate();
+}
+```
+
+How does `PrimaryUpdateAndCacheUtils` work?
+There are multiple ways to solve this problem, but ultimately, we only provide the solution described below. If you
+want to dig deep in alternatives, see
+this [PR](https://github.com/operator-framework/java-operator-sdk/pull/2800/files).
+
+The trick is to intercept the resource that the reconciler updated and cache that version in an additional cache on top
+of the informer's cache. Subsequently, if the reconciler needs to read the resource, the SDK will first check if it is
+in the overlay cache and read it from there if present, otherwise read it from the informer's cache. If the informer
+receives an event with a fresh resource, we always remove the resource from the overlay cache, since that is a more
+recent resource. But this **works only** if the reconciler updates the resource using **optimistic locking**.
+If the update fails on conflict, because the resource has already been updated on the cluster before we got
+the chance to get our update in, we simply wait and poll the informer cache until the new resource version from the
+server appears in the informer's cache,
+and then try to apply our updates to the resource again using the updated version from the server, again with optimistic
+locking.
+
+So why is optimistic locking required? We hinted at it above, but the gist of it, is that if another party updates the
+resource before we get a chance to, we wouldn't be able to properly handle the resulting situation correctly in all
+cases. The informer would receive that new event before our own update would get a chance to propagate. Without
+optimistic locking, there wouldn't be a fail-proof way to determine which update should prevail (i.e. which occurred
+first), in particular in the event of the informer losing the connection to the cluster or other edge cases (the joys of
+distributed computing!).
+
+Optimistic locking simplifies the situation and provides us with stronger guarantees: if the update succeeds, then we
+can be sure we have the proper resource version in our caches. The next event will contain our update in all cases.
+Because we know that, we can also be sure that we can evict the cached resource in the overlay cache whenever we receive
+a new event. The overlay cache is only used if the SDK detects that the original resource (i.e. the one before we
+applied our status update in the example above) is still in the informer's cache.
+
+The following diagram sums up the process:
+
+```mermaid
+flowchart TD
+ A["Update Resource with Lock"] --> B{"Is Successful"}
+ B -- Fails on conflict --> D["Poll the Informer cache until resource updated"]
+ D --> A
+ B -- Yes --> n2{"Original resource still in informer cache?"}
+ n2 -- Yes --> C["Cache the resource in overlay cache"]
+ n2 -- No --> n3["Informer cache already contains up-to-date version, do not use overlay cache"]
+```
diff --git a/docs/content/en/blog/releases/_index.md b/docs/content/en/blog/releases/_index.md
index 9143a23148..dbf2ee1729 100644
--- a/docs/content/en/blog/releases/_index.md
+++ b/docs/content/en/blog/releases/_index.md
@@ -1,4 +1,4 @@
---
title: Releases
-weight: 20
+weight: 230
---
diff --git a/docs/content/en/blog/releases/v5-release-beta1.md b/docs/content/en/blog/releases/v5-release-beta1.md
new file mode 100644
index 0000000000..7dd133cc1d
--- /dev/null
+++ b/docs/content/en/blog/releases/v5-release-beta1.md
@@ -0,0 +1,6 @@
+---
+title: Version 5 Released! (beta1)
+date: 2024-12-06
+---
+
+See release notes [here](v5-release.md).
\ No newline at end of file
diff --git a/docs/content/en/blog/releases/v5-release.md b/docs/content/en/blog/releases/v5-release.md
index aa41c38746..6d14dfb73a 100644
--- a/docs/content/en/blog/releases/v5-release.md
+++ b/docs/content/en/blog/releases/v5-release.md
@@ -1,6 +1,6 @@
---
-title: Version 5 Released! (beta1)
-date: 2024-12-06
+title: Version 5 Released!
+date: 2025-01-06
---
We are excited to announce that Java Operator SDK v5 has been released. This significant effort contains
@@ -20,7 +20,7 @@ You can see an introduction and some important changes and rationale behind them
## All Changes
-You can see all changes [here](https://github.com/operator-framework/java-operator-sdk/compare/v4.9.7...main).
+You can see all changes [here](https://github.com/operator-framework/java-operator-sdk/compare/v4.9.7...v5.0.0).
## Changes in low-level APIs
@@ -41,7 +41,7 @@ to `false`.
See some identified problematic migration cases and how to handle them
in [StatusPatchSSAMigrationIT](https://github.com/operator-framework/java-operator-sdk/blob/1635c9ea338f8e89bacc547808d2b409de8734cf/operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/statuspatchnonlocking/StatusPatchSSAMigrationIT.java).
-TODO using new instance to update status always,
+For more detailed description, see our [blog post](../news/nonssa-vs-ssa.md) on SSA.
### Event Sources related changes
diff --git a/docs/content/en/community/_index.md b/docs/content/en/community/_index.md
index 3f237b8a79..fa42c2d974 100644
--- a/docs/content/en/community/_index.md
+++ b/docs/content/en/community/_index.md
@@ -1,6 +1,6 @@
---
title: Community
-menu: {main: {weight: 40}}
+menu: {main: {weight: 3}}
---
diff --git a/docs/content/en/docs/_index.md b/docs/content/en/docs/_index.md
index 76486e22f7..5c7b74ab4b 100755
--- a/docs/content/en/docs/_index.md
+++ b/docs/content/en/docs/_index.md
@@ -1,8 +1,6 @@
---
title: Documentation
linkTitle: Docs
-menu: {main: {weight: 20}}
-weight: 20
+menu: {main: {weight: 1}}
+weight: 1
---
-
-
diff --git a/docs/content/en/docs/architecture/_index.md b/docs/content/en/docs/architecture/_index.md
deleted file mode 100644
index a29f70c4f6..0000000000
--- a/docs/content/en/docs/architecture/_index.md
+++ /dev/null
@@ -1,65 +0,0 @@
----
-title: Architecture and Internals
-weight: 90
----
-
-
-This document gives an overview of the internal structure and components of Java Operator SDK core,
-in order to make it easier for developers to understand and contribute to it. This document is
-not intended to be a comprehensive reference, rather an introduction to the core concepts and we
-hope that the other parts should be fairly easy to understand. We will evolve this document
-based on the community's feedback.
-
-## The Big Picture and Core Components
-
-
-
-An [Operator](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/Operator.java)
-is a set of
-independent [controllers](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/Controller.java)
-.
-The `Controller` class, however, is an internal class managed by the framework itself and
-usually shouldn't interacted with directly by end users. It
-manages all the processing units involved with reconciling a single type of Kubernetes resource.
-
-Other components include:
-
-- [Reconciler](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Reconciler.java)
- is the primary entry-point for the developers of the framework to implement the reconciliation
- logic.
-- [EventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/EventSource.java)
- represents a source of events that might eventually trigger a reconciliation.
-- [EventSourceManager](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventSourceManager.java)
- aggregates all the event sources associated with a controller. Manages the event sources'
- lifecycle.
-- [ControllerResourceEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/controller/ControllerResourceEventSource.java)
- is a central event source that watches the resources associated with the controller (also
- called primary resources) for changes, propagates events and caches the related state.
-- [EventProcessor](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventProcessor.java)
- processes the incoming events and makes sure they are executed in a sequential manner, that is
- making sure that the events are processed in the order they are received for a given resource,
- despite requests being processed concurrently overall. The `EventProcessor` also takes care of
- re-scheduling or retrying requests as needed.
-- [ReconcilerDispatcher](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/ReconciliationDispatcher.java)
- is responsible for dispatching requests to the appropriate `Reconciler` method and handling
- the reconciliation results, making the instructed Kubernetes API calls.
-
-## Typical Workflow
-
-A typical workflows looks like following:
-
-1. An `EventSource` produces an event, that is propagated to the `EventProcessor`.
-2. The resource associated with the event is read from the internal cache.
-3. If the resource is not already being processed, a reconciliation request is
- submitted to the executor service to be executed in a different thread, encapsulated in a
- `ControllerExecution` instance.
-4. This, in turns, calls the `ReconcilerDispatcher` which dispatches the call to the appropriate
- `Reconciler` method, passing along all the required information.
-5. Once the `Reconciler` is done, what happens depends on the result returned by the
- `Reconciler`. If needed, the `ReconcilerDispatcher` will make the appropriate calls to the
- Kubernetes API server.
-6. Once the `Reconciler` is done, the `EventProcessor` is called back to finalize the
- execution and update the controller's state.
-7. The `EventProcessor` checks if the request needs to be rescheduled or retried and if there are no
- subsequent events received for the same resource.
-8. When none of this happens, the processing of the event is finished.
diff --git a/docs/content/en/docs/configuration/_index.md b/docs/content/en/docs/configuration/_index.md
deleted file mode 100644
index 11929e3358..0000000000
--- a/docs/content/en/docs/configuration/_index.md
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: Configuring JOSDK
-layout: docs
-permalink: /docs/configuration
----
-
-# Configuration options
-
-The Java Operator SDK (JOSDK) provides several abstractions that work great out of the
-box. However, while we strive to cover the most common cases with the default behavior, we also
-recognize that that default behavior is not always what any given user might want for their
-operator. Numerous configuration options are therefore provided to help people tailor the
-framework to their needs.
-
-Configuration options act at several levels, depending on which behavior you wish to act upon:
-- `Operator`-level using `ConfigurationService`
-- `Reconciler`-level using `ControllerConfiguration`
-- `DependentResouce`-level using the `DependentResourceConfigurator` interface
-- `EventSource`-level: some event sources, such as `InformerEventSource`, might need to be
- fine-tuned to properly identify which events will trigger the associated reconciler.
-
-## Operator-level configuration
-
-Configuration that impacts the whole operator is performed via the `ConfigurationService` class.
-`ConfigurationService` is an abstract class, and the implementation can be different based
-on which flavor of the framework is used. For example Quarkus Operator SDK replaces the
-default implementation. Configurations are initialized with sensible defaults, but can
-be changed during initialization.
-
-For instance, if you wish to not validate that the CRDs are present on your cluster when the
-operator starts and configure leader election, you would do something similar to:
-
-```java
-Operator operator = new Operator( override -> override
- .checkingCRDAndValidateLocalModel(false)
- .withLeaderElectionConfiguration(new LeaderElectionConfiguration("bar", "barNS")));
-```
-
-## Reconciler-level configuration
-
-While reconcilers are typically configured using the `@ControllerConfiguration` annotation, it
-is also possible to override the configuration at runtime, when the reconciler is registered
-with the operator instance, either by passing it a completely new `ControllerConfiguration`
-instance or by preferably overriding some aspects of the current configuration using a
-`ControllerConfigurationOverrider` `Consumer`:
-
-```java
-Operator operator;
-Reconciler reconciler;
-...
-operator.register(reconciler, configOverrider ->
- configOverrider.withFinalizer("my-nifty-operator/finalizer").withLabelSelector("foo=bar"));
-```
-
-## DependentResource-level configuration
-
-`DependentResource` implementations can implement the `DependentResourceConfigurator` interface
-to pass information to the implementation. For example, the SDK
-provides specific support for the `KubernetesDependentResource`, which can be configured via the
-`@KubernetesDependent` annotation. This annotation is, in turn, converted into a
-`KubernetesDependentResourceConfig` instance, which is then passed to the `configureWith` method
-implementation.
-
-TODO: still subject to change / uniformization
-
-## EventSource-level configuration
-
-TODO
diff --git a/docs/content/en/docs/contributing/_index.md b/docs/content/en/docs/contributing/_index.md
index e67c45ebb6..0ab40d55b1 100644
--- a/docs/content/en/docs/contributing/_index.md
+++ b/docs/content/en/docs/contributing/_index.md
@@ -1,84 +1,68 @@
---
-title: Contributing To Java Operator SDK
-weight: 100
+title: Contributing
+weight: 110
---
-First of all, we'd like to thank you for considering contributing to the project! We really
-hope to create a vibrant community around this project but this won't happen without help from
-people like you!
+Thank you for considering contributing to the Java Operator SDK project! We're building a vibrant community and need help from people like you to make it happen.
## Code of Conduct
-We are serious about making this a welcoming, happy project. We will not tolerate discrimination,
-aggressive or insulting behaviour.
+We're committed to making this a welcoming, inclusive project. We do not tolerate discrimination, aggressive or insulting behavior.
-To this end, the project and everyone participating in it is bound by the [Code of
-Conduct]({{baseurl}}/coc). By participating, you are expected to uphold this code. Please report
-unacceptable behaviour to any of the project admins.
+This project and all participants are bound by our [Code of Conduct]({{baseurl}}/coc). By participating, you're expected to uphold this code. Please report unacceptable behavior to any project admin.
-## Bugs
+## Reporting Bugs
-If you find a bug,
-please [open an issue](https://github.com/java-operator-sdk/java-operator-sdk/issues)! Do try
-to include all the details needed to recreate your problem. This is likely to include:
+Found a bug? Please [open an issue](https://github.com/java-operator-sdk/java-operator-sdk/issues)! Include all details needed to recreate the problem:
-- The version of the Operator SDK being used
-- The exact platform and version of the platform that you're running on
-- The steps taken to cause the bug
-- Reproducer code is also very welcome to help us diagnose the issue and fix it quickly
+- Operator SDK version being used
+- Exact platform and version you're running on
+- Steps to reproduce the bug
+- Reproducer code (very helpful for quick diagnosis and fixes)
-## Building Features and Documentation
+## Contributing Features and Documentation
-If you're looking for something to work on, take look at the issue tracker, in particular any items
-labelled [good first issue](https://github.com/java-operator-sdk/java-operator-sdk/labels/good%20first%20issue)
-.
-Please leave a comment on the issue to mention that you have started work, in order to avoid
-multiple people working on the same issue.
+Looking for something to work on? Check the issue tracker, especially items labeled [good first issue](https://github.com/java-operator-sdk/java-operator-sdk/labels/good%20first%20issue). Please comment on the issue when you start work to avoid duplicated effort.
-If you have an idea for a feature - whether or not you have time to work on it - please also open an
-issue describing your feature and label it "enhancement". We can then discuss it as a community and
-see what can be done. Please be aware that some features may not align with the project goals and
-might therefore be closed. In particular, please don't start work on a new feature without
-discussing it first to avoid wasting effort. We do commit to listening to all proposals and will do
-our best to work something out!
+### Feature Ideas
-Once you've got the go ahead to work on a feature, you can start work. Feel free to communicate with
-team via updates on the issue tracker or the [Discord channel](https://discord.gg/DacEhAy) and ask
-for feedback, pointers etc. Once you're happy with your code, go ahead and open a Pull Request.
+Have a feature idea? Open an issue labeled "enhancement" even if you can't work on it immediately. We'll discuss it as a community and see what's possible.
-## Pull Request Process
+**Important**: Some features may not align with project goals. Please discuss new features before starting work to avoid wasted effort. We commit to listening to all proposals and working something out when possible.
+
+### Development Process
-First, please format your commit messages so that they follow
-the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
+Once you have approval to work on a feature:
+1. Communicate progress via issue updates or our [Discord channel](https://discord.gg/DacEhAy)
+2. Ask for feedback and pointers as needed
+3. Open a Pull Request when ready
+
+## Pull Request Process
-On opening a PR, a GitHub action will execute the test suite against the new code. All code is
-required to pass the tests, and new code must be accompanied by new tests.
+### Commit Messages
+Format commit messages following [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
-All PRs have to be reviewed and signed off by another developer before being merged. This review
-will likely ask for some changes to the code - please don't be alarmed or upset
-at this; it is expected that all PRs will need tweaks and a normal part of the process.
+### Testing and Review
+- GitHub Actions will run the test suite on your PR
+- All code must pass tests
+- New code must include new tests
+- All PRs require review and sign-off from another developer
+- Expect requests for changes - this is normal and part of the process
+- PRs must comply with Java Google code style
-The PRs are checked to be compliant with the Java Google code style.
+### Licensing
+All Operator SDK code is released under the [Apache 2.0 licence](LICENSE).
-Be aware that all Operator SDK code is released under the [Apache 2.0 licence](LICENSE).
+## Development Environment Setup
-## Development environment setup
+### Code Style
-### Code style
+SDK modules and samples follow Java Google code style. Code gets formatted automatically on every `compile`, but to avoid PR rejections due to style issues, set up your IDE:
-The SDK modules and samples are formatted to follow the Java Google code style.
-On every `compile` the code gets formatted automatically, however, to make things simpler (i.e.
-avoid getting a PR rejected simply because of code style issues), you can import one of the
-following code style schemes based on the IDE you use:
+**IntelliJ IDEA**: Install the [google-java-format](https://plugins.jetbrains.com/plugin/8527-google-java-format) plugin
-- for *Intellij IDEA*
- import [contributing/intellij-google-style.xml](contributing/intellij-google-style.xml)
-- for *Eclipse*
- import [contributing/eclipse-google-style.xml](contributing/eclipse-google-style.xml)
+**Eclipse**: Follow [these instructions](https://github.com/google/google-java-format?tab=readme-ov-file#eclipse)
-## Thanks
+## Acknowledgments
-These guidelines were based on several sources, including
-[Atom](https://github.com/atom/atom/blob/master/CONTRIBUTING.md), [PurpleBooth's
-advice](https://gist.github.com/PurpleBooth/b24679402957c63ec426) and the [Contributor
-Covenant](https://www.contributor-covenant.org/).
+These guidelines were inspired by [Atom](https://github.com/atom/atom/blob/master/CONTRIBUTING.md), [PurpleBooth's advice](https://gist.github.com/PurpleBooth/b24679402957c63ec426), and the [Contributor Covenant](https://www.contributor-covenant.org/).
diff --git a/docs/content/en/docs/documentation/_index.md b/docs/content/en/docs/documentation/_index.md
new file mode 100644
index 0000000000..59373c6974
--- /dev/null
+++ b/docs/content/en/docs/documentation/_index.md
@@ -0,0 +1,25 @@
+---
+title: Documentation
+weight: 40
+---
+
+# JOSDK Documentation
+
+This section contains detailed documentation for all Java Operator SDK features and concepts. Whether you're building your first operator or need advanced configuration options, you'll find comprehensive guides here.
+
+## Core Concepts
+
+- **[Implementing a Reconciler](reconciler/)** - The heart of any operator
+- **[Architecture](architecture/)** - How JOSDK works under the hood
+- **[Dependent Resources & Workflows](dependent-resource-and-workflows/)** - Managing resource relationships
+- **[Configuration](configuration/)** - Customizing operator behavior
+- **[Error Handling & Retries](error-handling-retries/)** - Managing failures gracefully
+
+## Advanced Features
+
+- **[Eventing](eventing/)** - Understanding the event-driven model
+- **[Accessing Resources in Caches](working-with-es-caches/) - How to access resources in caches
+- **[Observability](observability/)** - Monitoring and debugging your operators
+- **[Other Features](features/)** - Additional capabilities and integrations
+
+Each guide includes practical examples and best practices to help you build robust, production-ready operators.
diff --git a/docs/content/en/docs/documentation/architecture.md b/docs/content/en/docs/documentation/architecture.md
new file mode 100644
index 0000000000..4108849c04
--- /dev/null
+++ b/docs/content/en/docs/documentation/architecture.md
@@ -0,0 +1,36 @@
+---
+title: Architecture and Internals
+weight: 85
+---
+
+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](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/Operator.java) is a set of independent [controllers](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/Controller.java).
+
+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.
+
+### Core Components
+
+- **[Reconciler](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Reconciler.java)** - The primary entry point for developers to implement reconciliation logic
+- **[EventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/EventSource.java)** - Represents a source of events that might trigger reconciliation
+- **[EventSourceManager](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventSourceManager.java)** - Aggregates all event sources for a controller and manages their lifecycle
+- **[ControllerResourceEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/controller/ControllerResourceEventSource.java)** - Central event source that watches primary resources associated with a given controller for changes, propagates events and caches state
+- **[EventProcessor](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventProcessor.java)** - Processes incoming events sequentially per resource while allowing concurrent overall processing. Handles rescheduling and retrying
+- **[ReconcilerDispatcher](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/ReconciliationDispatcher.java)** - Dispatches requests to appropriate `Reconciler` methods and handles reconciliation results, making necessary Kubernetes API calls
+
+## Typical Workflow
+
+A typical workflow follows these steps:
+
+1. **Event Generation**: An `EventSource` produces an event and propagates it to the `EventProcessor`
+2. **Resource Reading**: The resource associated with the event is read from the internal cache
+3. **Reconciliation Submission**: If the resource isn't already being processed, a reconciliation request is submitted to the executor service in a different thread (encapsulated in a `ControllerExecution` instance)
+4. **Dispatching**: The `ReconcilerDispatcher` is called, which dispatches the call to the appropriate `Reconciler` method with all required information
+5. **Reconciler Execution**: Once the `Reconciler` completes, the `ReconcilerDispatcher` makes appropriate Kubernetes API server calls based on the returned result
+6. **Finalization**: The `EventProcessor` is called back to finalize execution and update the controller's state
+7. **Rescheduling Check**: The `EventProcessor` checks if the request needs rescheduling or retrying, and whether subsequent events were received for the same resource
+8. **Completion**: When no further action is needed, event processing is finished
diff --git a/docs/content/en/docs/documentation/configuration.md b/docs/content/en/docs/documentation/configuration.md
new file mode 100644
index 0000000000..888804628f
--- /dev/null
+++ b/docs/content/en/docs/documentation/configuration.md
@@ -0,0 +1,154 @@
+---
+title: Configurations
+weight: 55
+---
+
+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.
+
+For example, to disable CRD validation on startup and configure leader election:
+
+```java
+Operator operator = new Operator( override -> override
+ .checkingCRDAndValidateLocalModel(false)
+ .withLeaderElectionConfiguration(new LeaderElectionConfiguration("bar", "barNS")));
+```
+
+## Reconciler-Level Configuration
+
+While reconcilers are typically configured using the `@ControllerConfiguration` annotation, you can also override configuration at runtime when registering the reconciler with the operator. You can either:
+- Pass a completely new `ControllerConfiguration` instance
+- Override specific aspects using a `ControllerConfigurationOverrider` `Consumer` (preferred)
+
+```java
+Operator operator;
+Reconciler reconciler;
+...
+operator.register(reconciler, configOverrider ->
+ configOverrider.withFinalizer("my-nifty-operator/finalizer").withLabelSelector("foo=bar"));
+```
+
+## Dynamically Changing Target Namespaces
+
+A controller can be configured to watch a specific set of namespaces in addition of the
+namespace in which it is currently deployed or the whole cluster. The framework supports
+dynamically changing the list of these namespaces while the operator is running.
+When a reconciler is registered, an instance of
+[`RegisteredController`](https://github.com/java-operator-sdk/java-operator-sdk/blob/ec37025a15046d8f409c77616110024bf32c3416/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/RegisteredController.java#L5)
+is returned, providing access to the methods allowing users to change watched namespaces as the
+operator is running.
+
+A typical scenario would probably involve extracting the list of target namespaces from a
+`ConfigMap` or some other input but this part is out of the scope of the framework since this is
+use-case specific. For example, reacting to changes to a `ConfigMap` would probably involve
+registering an associated `Informer` and then calling the `changeNamespaces` method on
+`RegisteredController`.
+
+```java
+
+public static void main(String[] args) {
+ KubernetesClient client = new DefaultKubernetesClient();
+ Operator operator = new Operator(client);
+ RegisteredController registeredController = operator.register(new WebPageReconciler(client));
+ operator.installShutdownHook();
+ operator.start();
+
+ // call registeredController further while operator is running
+}
+
+```
+
+If watched namespaces change for a controller, it might be desirable to propagate these changes to
+`InformerEventSources` associated with the controller. In order to express this,
+`InformerEventSource` implementations interested in following such changes need to be
+configured appropriately so that the `followControllerNamespaceChanges` method returns `true`:
+
+```java
+
+@ControllerConfiguration
+public class MyReconciler implements Reconciler {
+
+ @Override
+ public Map prepareEventSources(
+ EventSourceContext context) {
+
+ InformerEventSource configMapES =
+ new InformerEventSource<>(InformerEventSourceConfiguration.from(ConfigMap.class, TestCustomResource.class)
+ .withNamespacesInheritedFromController(context)
+ .build(), context);
+
+ return EventSourceUtils.nameEventSources(configMapES);
+ }
+
+}
+```
+
+As seen in the above code snippet, the informer will have the initial namespaces inherited from
+controller, but also will adjust the target namespaces if it changes for the controller.
+
+See also
+the [integration test](https://github.com/operator-framework/java-operator-sdk/tree/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/changenamespace)
+for this feature.
+
+## DependentResource-level configuration
+
+It is possible to define custom annotations to configure custom `DependentResource` implementations. In order to provide
+such a configuration mechanism for your own `DependentResource` implementations, they must be annotated with the
+`@Configured` annotation. This annotation defines 3 fields that tie everything together:
+
+- `by`, which specifies which annotation class will be used to configure your dependents,
+- `with`, which specifies the class holding the configuration object for your dependents and
+- `converter`, which specifies the `ConfigurationConverter` implementation in charge of converting the annotation
+ specified by the `by` field into objects of the class specified by the `with` field.
+
+`ConfigurationConverter` instances implement a single `configFrom` method, which will receive, as expected, the
+annotation instance annotating the dependent resource instance to be configured, but it can also extract information
+from the `DependentResourceSpec` instance associated with the `DependentResource` class so that metadata from it can be
+used in the configuration, as well as the parent `ControllerConfiguration`, if needed. The role of
+`ConfigurationConverter` implementations is to extract the annotation information, augment it with metadata from the
+`DependentResourceSpec` and the configuration from the parent controller on which the dependent is defined, to finally
+create the configuration object that the `DependentResource` instances will use.
+
+However, one last element is required to finish the configuration process: the target `DependentResource` class must
+implement the `ConfiguredDependentResource` interface, parameterized with the annotation class defined by the
+`@Configured` annotation `by` field. This interface is called by the framework to inject the configuration at the
+appropriate time and retrieve the configuration, if it's available.
+
+For example, `KubernetesDependentResource`, a core implementation that the framework provides, can be configured via the
+`@KubernetesDependent` annotation. This set up is configured as follows:
+
+```java
+
+@Configured(
+ by = KubernetesDependent.class,
+ with = KubernetesDependentResourceConfig.class,
+ converter = KubernetesDependentConverter.class)
+public abstract class KubernetesDependentResource
+ extends AbstractEventSourceHolderDependentResource>
+ implements ConfiguredDependentResource> {
+ // code omitted
+}
+```
+
+The `@Configured` annotation specifies that `KubernetesDependentResource` instances can be configured by using the
+`@KubernetesDependent` annotation, which gets converted into a `KubernetesDependentResourceConfig` object by a
+`KubernetesDependentConverter`. That configuration object is then injected by the framework in the
+`KubernetesDependentResource` instance, after it's been created, because the class implements the
+`ConfiguredDependentResource` interface, properly parameterized.
+
+For more information on how to use this feature, we recommend looking at how this mechanism is implemented for
+`KubernetesDependentResource` in the core framework, `SchemaDependentResource` in the samples or `CustomAnnotationDep`
+in the `BaseConfigurationServiceTest` test class.
+
+## EventSource-level configuration
+
+TODO
diff --git a/docs/content/en/docs/documentation/dependent-resource-and-workflows/_index.md b/docs/content/en/docs/documentation/dependent-resource-and-workflows/_index.md
new file mode 100644
index 0000000000..9446f7ceca
--- /dev/null
+++ b/docs/content/en/docs/documentation/dependent-resource-and-workflows/_index.md
@@ -0,0 +1,9 @@
+---
+title: Dependent resources and workflows
+weight: 70
+---
+
+Dependent resources and workflows are features sometimes referenced as higher
+level abstractions. These two related concepts provides an abstraction
+over reconciliation of a single resource (Dependent resource) and the
+orchestration of such resources (Workflows).
\ No newline at end of file
diff --git a/docs/content/en/docs/dependent-resources/_index.md b/docs/content/en/docs/documentation/dependent-resource-and-workflows/dependent-resources.md
similarity index 97%
rename from docs/content/en/docs/dependent-resources/_index.md
rename to docs/content/en/docs/documentation/dependent-resource-and-workflows/dependent-resources.md
index 205c03ac1c..7416949869 100644
--- a/docs/content/en/docs/dependent-resources/_index.md
+++ b/docs/content/en/docs/documentation/dependent-resource-and-workflows/dependent-resources.md
@@ -1,10 +1,8 @@
---
-title: Dependent Resources
-weight: 60
+title: Dependent resources
+weight: 75
---
-# Dependent Resources
-
## Motivations and Goals
Most operators need to deal with secondary resources when trying to realize the desired state
@@ -135,13 +133,9 @@ Deleted (or set to be garbage collected). The following example shows how to cre
```java
-@KubernetesDependent(labelSelector = WebPageManagedDependentsReconciler.SELECTOR)
+@KubernetesDependent(informer = @Informer(labelSelector = SELECTOR))
class DeploymentDependentResource extends CRUDKubernetesDependentResource {
- public DeploymentDependentResource() {
- super(Deployment.class);
- }
-
@Override
protected Deployment desired(WebPage webPage, Context context) {
var deploymentName = deploymentName(webPage);
@@ -180,9 +174,10 @@ JOSDK will take the appropriate steps to wire everything together and call your
`DependentResource` implementations `reconcile` method before your primary resource is reconciled.
This makes sense in most use cases where the logic associated with the primary resource is
usually limited to status handling based on the state of the secondary resources and the
-resources are not dependent on each other.
+resources are not dependent on each other. As an alternative, you can also invoke reconciliation explicitly,
+event for managed workflows.
-See [Workflows](https://javaoperatorsdk.io/docs/workflows) for more details on how the dependent
+See [Workflows](https://javaoperatorsdk.io/docs/documentation/dependent-resource-and-workflows/workflows/) for more details on how the dependent
resources are reconciled.
This behavior and automated handling is referred to as "managed" because the `DependentResource`
@@ -190,12 +185,14 @@ instances are managed by JOSDK, an example of which can be seen below:
```java
-@ControllerConfiguration(
- labelSelector = SELECTOR,
+@Workflow(
dependents = {
@Dependent(type = ConfigMapDependentResource.class),
@Dependent(type = DeploymentDependentResource.class),
- @Dependent(type = ServiceDependentResource.class)
+ @Dependent(type = ServiceDependentResource.class),
+ @Dependent(
+ type = IngressDependentResource.class,
+ reconcilePrecondition = ExposedIngressCondition.class)
})
public class WebPageManagedDependentsReconciler
implements Reconciler, ErrorStatusHandler {
@@ -210,7 +207,6 @@ public class WebPageManagedDependentsReconciler
webPage.setStatus(createStatus(name));
return UpdateControl.patchStatus(webPage);
}
-
}
```
@@ -224,7 +220,7 @@ It is also possible to wire dependent resources programmatically. In practice th
developer is responsible for initializing and managing the dependent resources as well as calling
their `reconcile` method. However, this makes it possible for developers to fully customize the
reconciliation process. Standalone dependent resources should be used in cases when the managed use
-case does not fit. You can, of course, also use [Workflows](https://javaoperatorsdk.io/docs/workflows) when managing
+case does not fit. You can, of course, also use [Workflows](https://javaoperatorsdk.io/docs/documentation/dependent-resource-and-workflows/workflows/) when managing
resources programmatically.
You can see a commented example of how to do
diff --git a/docs/content/en/docs/workflows/_index.md b/docs/content/en/docs/documentation/dependent-resource-and-workflows/workflows.md
similarity index 97%
rename from docs/content/en/docs/workflows/_index.md
rename to docs/content/en/docs/documentation/dependent-resource-and-workflows/workflows.md
index 620f8c5436..c5ee83a446 100644
--- a/docs/content/en/docs/workflows/_index.md
+++ b/docs/content/en/docs/documentation/dependent-resource-and-workflows/workflows.md
@@ -1,6 +1,6 @@
---
title: Workflows
-weight: 70
+weight: 80
---
## Overview
@@ -12,12 +12,12 @@ depends on the state of other resources or cannot be processed until these other
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](https://javaoperatorsdk.io/docs/dependent-resources) feature.
+[dependent resources](https://javaoperatorsdk.io/docs/documentation/dependent-resource-and-workflows/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.
Workflows describe how as a set of
-[dependent resources](https://javaoperatorsdk.io/docs/dependent-resources) (DR) depend on one
+[dependent resources](https://javaoperatorsdk.io/docs/documentation/dependent-resource-and-workflows/dependent-resources/) (DR) depend on one
another, along with the conditions that need to hold true at certain stages of the
reconciliation process.
@@ -135,7 +135,7 @@ public class SampleWorkflowReconciler implements Reconciler {
+ // reconciler implementation
+}
+```
+
+**Custom retry implementation:**
+
+Specify a custom retry class in the `@ControllerConfiguration` annotation:
+
+```java
+@ControllerConfiguration(retry = MyCustomRetry.class)
+public class MyReconciler implements Reconciler {
+ // reconciler implementation
+}
+```
+
+Your custom retry class must:
+- Provide a no-argument constructor for automatic instantiation
+- Optionally implement `AnnotationConfigurable` for configuration from annotations. See [`GenericRetry`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/retry/GenericRetry.java#)
+ implementation for more details.
+
+### Accessing Retry Information
+
+The [Context](https://github.com/java-operator-sdk/java-operator-sdk/blob/master/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/Context.java) object provides retry state information:
+
+```java
+@Override
+public UpdateControl reconcile(MyResource resource, Context context) {
+ if (context.isLastAttempt()) {
+ // Handle final retry attempt differently
+ resource.getStatus().setErrorMessage("Failed after all retry attempts");
+ return UpdateControl.patchStatus(resource);
+ }
+
+ // Normal reconciliation logic
+ // ...
+}
+```
+
+### Important Retry Behavior Notes
+
+- **Retry limits don't block new events**: When retry limits are reached, new reconciliations still occur for new events
+- **No retry on limit reached**: If an error occurs after reaching the retry limit, no additional retries are scheduled until new events arrive
+- **Event-driven recovery**: Fresh events can restart the retry cycle, allowing recovery from previously failed states
+
+A successful execution resets the retry state.
+
+### Reconciler Error Handler
+
+In order to facilitate error reporting you can override [`updateErrorStatus`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Reconciler.java#L52)
+method in `Reconciler`:
+
+```java
+public class MyReconciler implements Reconciler {
+
+ @Override
+ public ErrorStatusUpdateControl updateErrorStatus(
+ WebPage resource, Context context, Exception e) {
+ return handleError(resource, e);
+ }
+
+}
+```
+
+The `updateErrorStatus` method is called in case an exception is thrown from the `Reconciler`. It is
+also called even if no retry policy is configured, just after the reconciler execution.
+`RetryInfo.getAttemptCount()` is zero after the first reconciliation attempt, since it is not a
+result of a retry (regardless of whether a retry policy is configured).
+
+`ErrorStatusUpdateControl` tells the SDK what to do and how to perform the status
+update on the primary resource, which is always performed as a status sub-resource request. Note that
+this update request will also produce an event and result in a reconciliation if the
+controller is not generation-aware.
+
+This feature is only available for the `reconcile` method of the `Reconciler` interface, since
+there should not be updates to resources that have been marked for deletion.
+
+Retry can be skipped in cases of unrecoverable errors:
+
+```java
+ ErrorStatusUpdateControl.patchStatus(customResource).withNoRetry();
+```
+
+### Correctness and Automatic Retries
+
+While it is possible to deactivate automatic retries, this is not desirable unless there is a particular reason.
+Errors naturally occur, whether it be transient network errors or conflicts
+when a given resource is handled by a `Reconciler` but modified simultaneously by a user in
+a different process. Automatic retries handle these cases nicely and will eventually result in a
+successful reconciliation.
+
+## Retry, Rescheduling and Event Handling Common Behavior
+
+Retry, reschedule, and standard event processing form a relatively complex system, each of these
+functionalities interacting with the others. In the following, we describe the interplay of
+these features:
+
+1. A successful execution resets a retry and the rescheduled executions that were present before
+ the reconciliation. However, the reconciliation outcome can instruct a new rescheduling (`UpdateControl` or `DeleteControl`).
+
+ For example, if a reconciliation had previously been rescheduled for after some amount of time, but an event triggered
+ the reconciliation (or cleanup) in the meantime, the scheduled execution would be automatically cancelled, i.e.
+ rescheduling a reconciliation does not guarantee that one will occur precisely at that time; it simply guarantees that a reconciliation will occur at the latest.
+ Of course, it's always possible to reschedule a new reconciliation at the end of that "automatic" reconciliation.
+
+ Similarly, if a retry was scheduled, any event from the cluster triggering a successful execution in the meantime
+ would cancel the scheduled retry (because there's now no point in retrying something that already succeeded)
+
+2. In case an exception is thrown, a retry is initiated. However, if an event is received
+ meanwhile, it will be reconciled instantly, and this execution won't count as a retry attempt.
+3. If the retry limit is reached (so no more automatic retry would happen), but a new event
+ received, the reconciliation will still happen, but won't reset the retry, and will still be
+ marked as the last attempt in the retry info. The point (1) still holds - thus successful reconciliation will reset the retry - but no retry will happen in case of an error.
+
+The thing to remember when it comes to retrying or rescheduling is that JOSDK tries to avoid unnecessary work. When
+you reschedule an operation, you instruct JOSDK to perform that operation by the end of the rescheduling
+delay at the latest. If something occurred on the cluster that triggers that particular operation (reconciliation or cleanup), then
+JOSDK considers that there's no point in attempting that operation again at the end of the specified delay since there
+is no point in doing so anymore. The same idea also applies to retries.
diff --git a/docs/content/en/docs/documentation/eventing.md b/docs/content/en/docs/documentation/eventing.md
new file mode 100644
index 0000000000..77daeb6fa3
--- /dev/null
+++ b/docs/content/en/docs/documentation/eventing.md
@@ -0,0 +1,327 @@
+---
+title: Event sources and related topics
+weight: 47
+---
+
+## Handling Related Events with Event Sources
+
+See also
+this [blog post](https://csviri.medium.com/java-operator-sdk-introduction-to-event-sources-a1aab5af4b7b)
+.
+
+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.
+
+
+
+There are few interesting points here:
+
+The `CustomResourceEventSource` event source is a special one, responsible for handling events
+pertaining to changes affecting our primary resources. This `EventSource` is always registered
+for every controller automatically by the SDK. It is important to note that events always relate
+to a given primary resource. Concurrency is still handled for you, even in the presence of
+`EventSource` implementations, and the SDK still guarantees that there is no concurrent execution of
+the controller for any given primary resource (though, of course, concurrent/parallel executions
+of events pertaining to other primary resources still occur as expected).
+
+### Caching and Event Sources
+
+Kubernetes resources are handled in a declarative manner. The same also holds true for event
+sources. For example, if we define an event source to watch for changes of a Kubernetes Deployment
+object using an `InformerEventSource`, we always receive the whole associated object from the
+Kubernetes API. This object might be needed at any point during our reconciliation process and
+it's best to retrieve it from the event source directly when possible instead of fetching it
+from the Kubernetes API since the event source guarantees that it will provide the latest
+version. Not only that, but many event source implementations also cache resources they handle
+so that it's possible to retrieve the latest version of resources without needing to make any
+calls to the Kubernetes API, thus allowing for very efficient controller implementations.
+
+Note after an operator starts, caches are already populated by the time the first reconciliation
+is processed for the `InformerEventSource` implementation. However, this does not necessarily
+hold true for all event source implementations (`PerResourceEventSource` for example). The SDK
+provides methods to handle this situation elegantly, allowing you to check if an object is
+cached, retrieving it from a provided supplier if not. See
+related [method](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/polling/PerResourcePollingEventSource.java#L146)
+.
+
+### Registering Event Sources
+
+To register event sources, your `Reconciler` has to override the `prepareEventSources` and return
+list of event sources to register. One way to see this in action is
+to look at the
+[WebPage example](https://github.com/operator-framework/java-operator-sdk/blob/main/sample-operators/webpage/src/main/java/io/javaoperatorsdk/operator/sample/WebPageReconciler.java)
+(irrelevant details omitted):
+
+```java
+
+import java.util.List;
+
+@ControllerConfiguration
+public class WebappReconciler
+ implements Reconciler, Cleaner, EventSourceInitializer {
+ // ommitted code
+
+ @Override
+ public List> prepareEventSources(EventSourceContext context) {
+ InformerEventSourceConfiguration configuration =
+ InformerEventSourceConfiguration.from(Deployment.class, Webapp.class)
+ .withLabelSelector(SELECTOR)
+ .build();
+ return List.of(new InformerEventSource<>(configuration, context));
+ }
+}
+```
+
+In the example above an `InformerEventSource` is configured and registered.
+`InformerEventSource` is one of the bundled `EventSource` implementations that JOSDK provides to
+cover common use cases.
+
+### Managing Relation between Primary and Secondary Resources
+
+Event sources let your operator know when a secondary resource has changed and that your
+operator might need to reconcile this new information. However, in order to do so, the SDK needs
+to somehow retrieve the primary resource associated with which ever secondary resource triggered
+the event. In the `Webapp` example above, when an event occurs on a tracked `Deployment`, the
+SDK needs to be able to identify which `Webapp` resource is impacted by that change.
+
+Seasoned Kubernetes users already know one way to track this parent-child kind of relationship:
+using owner references. Indeed, that's how the SDK deals with this situation by default as well,
+that is, if your controller properly set owner references on your secondary resources, the SDK
+will be able to follow that reference back to your primary resource automatically without you
+having to worry about it.
+
+However, owner references cannot always be used as they are restricted to operating within a
+single namespace (i.e. you cannot have an owner reference to a resource in a different namespace)
+and are, by essence, limited to Kubernetes resources so you're out of luck if your secondary
+resources live outside of a cluster.
+
+This is why JOSDK provides the `SecondaryToPrimaryMapper` interface so that you can provide
+alternative ways for the SDK to identify which primary resource needs to be reconciled when
+something occurs to your secondary resources. We even provide some of these alternatives in the
+[Mappers](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/Mappers.java)
+class.
+
+Note that, while a set of `ResourceID` is returned, this set usually consists only of one
+element. It is however possible to return multiple values or even no value at all to cover some
+rare corner cases. Returning an empty set means that the mapper considered the secondary
+resource event as irrelevant and the SDK will thus not trigger a reconciliation of the primary
+resource in that situation.
+
+Adding a `SecondaryToPrimaryMapper` is typically sufficient when there is a one-to-many relationship
+between primary and secondary resources. The secondary resources can be mapped to its primary
+owner, and this is enough information to also get these secondary resources from the `Context`
+object that's passed to your `Reconciler`.
+
+There are however cases when this isn't sufficient and you need to provide an explicit mapping
+between a primary resource and its associated secondary resources using an implementation of the
+`PrimaryToSecondaryMapper` interface. This is typically needed when there are many-to-one or
+many-to-many relationships between primary and secondary resources, e.g. when the primary resource
+is referencing secondary resources.
+See [PrimaryToSecondaryIT](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/primarytosecondary/PrimaryToSecondaryIT.java)
+integration test for a sample.
+
+### Built-in EventSources
+
+There are multiple event-sources provided out of the box, the following are some more central ones:
+
+#### `InformerEventSource`
+
+[InformerEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerEventSource.java)
+is probably the most important `EventSource` implementation to know about. When you create an
+`InformerEventSource`, JOSDK will automatically create and register a `SharedIndexInformer`, a
+fabric8 Kubernetes client class, that will listen for events associated with the resource type
+you configured your `InformerEventSource` with. If you want to listen to Kubernetes resource
+events, `InformerEventSource` is probably the only thing you need to use. It's highly
+configurable so you can tune it to your needs. Take a look at
+[InformerEventSourceConfiguration](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/informer/InformerEventSourceConfiguration.java)
+and associated classes for more details but some interesting features we can mention here is the
+ability to filter events so that you can only get notified for events you care about. A
+particularly interesting feature of the `InformerEventSource`, as opposed to using your own
+informer-based listening mechanism is that caches are particularly well optimized preventing
+reconciliations from being triggered when not needed and allowing efficient operators to be written.
+
+#### `PerResourcePollingEventSource`
+
+[PerResourcePollingEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/polling/PerResourcePollingEventSource.java)
+is used to poll external APIs, which don't support webhooks or other event notifications. It
+extends the abstract
+[ExternalResourceCachingEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/ExternalResourceCachingEventSource.java)
+to support caching.
+See [MySQL Schema sample](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/sample-operators/mysql-schema/src/main/java/io/javaoperatorsdk/operator/sample/MySQLSchemaReconciler.java)
+for usage.
+
+#### `PollingEventSource`
+
+[PollingEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/polling/PollingEventSource.java)
+is similar to `PerResourceCachingEventSource` except that, contrary to that event source, it
+doesn't poll a specific API separately per resource, but periodically and independently of
+actually observed primary resources.
+
+#### Inbound event sources
+
+[SimpleInboundEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/inbound/SimpleInboundEventSource.java)
+and
+[CachingInboundEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/inbound/CachingInboundEventSource.java)
+are used to handle incoming events from webhooks and messaging systems.
+
+#### `ControllerResourceEventSource`
+
+[ControllerResourceEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/controller/ControllerResourceEventSource.java)
+is a special `EventSource` implementation that you will never have to deal with directly. It is,
+however, at the core of the SDK is automatically added for you: this is the main event source
+that listens for changes to your primary resources and triggers your `Reconciler` when needed.
+It features smart caching and is really optimized to minimize Kubernetes API accesses and avoid
+triggering unduly your `Reconciler`.
+
+More on the philosophy of the non Kubernetes API related event source see in
+issue [#729](https://github.com/java-operator-sdk/java-operator-sdk/issues/729).
+
+
+## InformerEventSource Multi-Cluster Support
+
+It is possible to handle resources for remote cluster with `InformerEventSource`. To do so,
+simply set a client that connects to a remote cluster:
+
+```java
+
+InformerEventSourceConfiguration configuration =
+ InformerEventSourceConfiguration.from(SecondaryResource.class, PrimaryResource.class)
+ .withKubernetesClient(remoteClusterClient)
+ .withSecondaryToPrimaryMapper(Mappers.fromDefaultAnnotations());
+
+```
+
+You will also need to specify a `SecondaryToPrimaryMapper`, since the default one
+is based on owner references and won't work across cluster instances. You could, for example, use the provided implementation that relies on annotations added to the secondary resources to identify the associated primary resource.
+
+See related [integration test](https://github.com/operator-framework/java-operator-sdk/tree/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/informerremotecluster).
+
+
+## Generation Awareness and Event Filtering
+
+A best practice when an operator starts up is to reconcile all the associated resources because
+changes might have occurred to the resources while the operator was not running.
+
+When this first reconciliation is done successfully, the next reconciliation is triggered if either
+dependent resources are changed or the primary resource `.spec` field is changed. If other fields
+like `.metadata` are changed on the primary resource, the reconciliation could be skipped. This
+behavior is supported out of the box and reconciliation is by default not triggered if
+changes to the primary resource do not increase the `.metadata.generation` field.
+Note that changes to `.metada.generation` are automatically handled by Kubernetes.
+
+To turn off this feature, set `generationAwareEventProcessing` to `false` for the `Reconciler`.
+
+
+## Max Interval Between Reconciliations
+
+When informers / event sources are properly set up, and the `Reconciler` implementation is
+correct, no additional reconciliation triggers should be needed. However, it's
+a [common practice](https://github.com/java-operator-sdk/java-operator-sdk/issues/848#issuecomment-1016419966)
+to have a failsafe periodic trigger in place, just to make sure resources are nevertheless
+reconciled after a certain amount of time. This functionality is in place by default, with a
+rather high time interval (currently 10 hours) after which a reconciliation will be
+automatically triggered even in the absence of other events. See how to override this using the
+standard annotation:
+
+```java
+@ControllerConfiguration(maxReconciliationInterval = @MaxReconciliationInterval(
+ interval = 50,
+ timeUnit = TimeUnit.MILLISECONDS))
+public class MyReconciler implements Reconciler {}
+```
+
+The event is not propagated at a fixed rate, rather it's scheduled after each reconciliation. So the
+next reconciliation will occur at most within the specified interval after the last reconciliation.
+
+This feature can be turned off by setting `maxReconciliationInterval`
+to [`Constants.NO_MAX_RECONCILIATION_INTERVAL`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Constants.java#L20-L20)
+or any non-positive number.
+
+The automatic retries are not affected by this feature so a reconciliation will be re-triggered
+on error, according to the specified retry policy, regardless of this maximum interval setting.
+
+## Rate Limiting
+
+It is possible to rate limit reconciliation on a per-resource basis. The rate limit also takes
+precedence over retry/re-schedule configurations: for example, even if a retry was scheduled for
+the next second 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.
+
+Rate limiting is by default turned **off**, since correct configuration depends on the reconciler
+implementation, in particular, on how long a typical reconciliation takes.
+(The parallelism of reconciliation itself can be
+limited [`ConfigurationService`](https://github.com/java-operator-sdk/java-operator-sdk/blob/ce4d996ee073ebef5715737995fc3d33f4751275/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L120-L120)
+by configuring the `ExecutorService` appropriately.)
+
+A default rate limiter implementation is provided, see:
+[`PeriodRateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/ce4d996ee073ebef5715737995fc3d33f4751275/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/PeriodRateLimiter.java#L14-L14)
+.
+Users can override it by implementing their own
+[`RateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/ce4d996ee073ebef5715737995fc3d33f4751275/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/RateLimiter.java)
+and specifying this custom implementation using the `rateLimiter` field of the
+`@ControllerConfiguration` annotation. Similarly to the `Retry` implementations,
+`RateLimiter` implementations must provide an accessible, no-arg constructor for instantiation
+purposes and can further be automatically configured from your own, provided annotation provided
+your `RateLimiter` implementation also implements the `AnnotationConfigurable` interface,
+parameterized by your custom annotation type.
+
+To configure the default rate limiter use the `@RateLimited` annotation on your
+`Reconciler` class. The following configuration limits each resource to reconcile at most twice
+within a 3 second interval:
+
+```java
+
+@RateLimited(maxReconciliations = 2, within = 3, unit = TimeUnit.SECONDS)
+@ControllerConfiguration
+public class MyReconciler implements Reconciler {
+
+}
+```
+
+Thus, if a given resource was reconciled twice in one second, no further reconciliation for this
+resource will happen before two seconds have elapsed. Note that, since rate is limited on a
+per-resource basis, other resources can still be reconciled at the same time, as long, of course,
+that they stay within their own rate limits.
+
+## Optimizing Caches
+
+One of the ideas around the operator pattern is that all the relevant resources are cached, thus reconciliation is
+usually very fast (especially if no resources are updated in the process) since the operator is then mostly working with
+in-memory state. However for large clusters, caching huge amount of primary and secondary resources might consume lots
+of memory. JOSDK provides ways to mitigate this issue and optimize the memory usage of controllers. While these features
+are working and tested, we need feedback from real production usage.
+
+### Bounded Caches for Informers
+
+Limiting caches for informers - thus for Kubernetes resources - is supported by ensuring that resources are in the cache
+for a limited time, via a cache eviction of least recently used resources. This means that when resources are created
+and frequently reconciled, they stay "hot" in the cache. However, if, over time, a given resource "cools" down, i.e. it
+becomes less and less used to the point that it might not be reconciled anymore, it will eventually get evicted from the
+cache to free up memory. If such an evicted resource were to become reconciled again, the bounded cache implementation
+would then fetch it from the API server and the "hot/cold" cycle would start anew.
+
+Since all resources need to be reconciled when a controller start, it is not practical to set a maximal cache size as
+it's desirable that all resources be cached as soon as possible to make the initial reconciliation process on start as
+fast and efficient as possible, avoiding undue load on the API server. It's therefore more interesting to gradually
+evict cold resources than try to limit cache sizes.
+
+See usage of the related implementation using [Caffeine](https://github.com/ben-manes/caffeine) cache in integration
+tests
+for [primary resources](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/caffeine-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/AbstractTestReconciler.java).
+
+See
+also [CaffeineBoundedItemStores](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/caffeine-bounded-cache-support/src/main/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeineBoundedItemStores.java)
+for more details.
\ No newline at end of file
diff --git a/docs/content/en/docs/documentation/features.md b/docs/content/en/docs/documentation/features.md
new file mode 100644
index 0000000000..8c8909c8b2
--- /dev/null
+++ b/docs/content/en/docs/documentation/features.md
@@ -0,0 +1,55 @@
+---
+title: Other Features
+weight: 57
+---
+
+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](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/deployment) for an example of reconciling deployments.
+
+```java
+public class DeploymentReconciler
+ implements Reconciler, TestExecutionInfoProvider {
+
+ @Override
+ public UpdateControl reconcile(
+ Deployment resource, Context context) {
+ // omitted code
+ }
+}
+```
+
+## Leader Election
+
+Operators are typically deployed with a single active instance. However, you can deploy multiple instances where only one (the "leader") processes events. This is achieved through "leader election."
+
+While all instances run and start their event sources to populate caches, only the leader processes events. If the leader crashes, other instances are already warmed up and ready to take over when a new leader is elected.
+
+See sample configuration in the [E2E test](https://github.com/java-operator-sdk/java-operator-sdk/blob/8865302ac0346ee31f2d7b348997ec2913d5922b/sample-operators/leader-election/src/main/java/io/javaoperatorsdk/operator/sample/LeaderElectionTestOperator.java#L21-L23).
+
+## Automatic CRD Generation
+
+**Note:** This feature is provided by the [Fabric8 Kubernetes Client](https://github.com/fabric8io/kubernetes-client), not JOSDK itself.
+
+To automatically generate CRD manifests from your annotated Custom Resource classes, add this dependency to your project:
+
+```xml
+
+
+ io.fabric8
+ crd-generator-apt
+ provided
+
+```
+
+The CRD will be generated in `target/classes/META-INF/fabric8` (or `target/test-classes/META-INF/fabric8` for test scope) with the CRD name suffixed by the generated spec version.
+
+For example, a CR using the `java-operator-sdk.io` group with a `mycrs` plural form will result in these files:
+- `mycrs.java-operator-sdk.io-v1.yml`
+- `mycrs.java-operator-sdk.io-v1beta1.yml`
+
+**Note for Quarkus users:** If you're using the `quarkus-operator-sdk` extension, you don't need to add any extra dependency for CRD generation - the extension handles this automatically.
diff --git a/docs/content/en/docs/documentation/observability.md b/docs/content/en/docs/documentation/observability.md
new file mode 100644
index 0000000000..27a68086d5
--- /dev/null
+++ b/docs/content/en/docs/documentation/observability.md
@@ -0,0 +1,112 @@
+---
+title: Observability
+weight: 55
+---
+
+## Runtime Info
+
+[RuntimeInfo](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/RuntimeInfo.java#L16-L16)
+is used mainly to check the actual health of event sources. Based on this information it is easy to implement custom
+liveness probes.
+
+[stopOnInformerErrorDuringStartup](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L168-L168)
+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](https://github.com/java-operator-sdk/java-operator-sdk/blob/3e2e7c4c834ef1c409d636156b988125744ca911/sample-operators/webpage/src/main/java/io/javaoperatorsdk/operator/sample/WebPageOperator.java#L38-L43)
+
+## Contextual Info for Logging with MDC
+
+Logging is enhanced with additional contextual information using
+[MDC](http://www.slf4j.org/manual.html#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](https://www.baeldung.com/mdc-in-log4j-2-logback).
+
+## 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](https://micrometer.io)-based implementation is also provided.
+
+You can use a different implementation by overriding the default one provided by the default `ConfigurationService`, as
+follows:
+
+```java
+Metrics metrics; // initialize your metrics implementation
+Operator operator = new Operator(client, o -> o.withMetrics(metrics));
+```
+
+### Micrometer implementation
+
+The micrometer implementation is typically created using one of the provided factory methods which, depending on which
+is used, will return either a ready to use instance or a builder allowing users to customized how the implementation
+behaves, in particular when it comes to the granularity of collected metrics. It is, for example, possible to collect
+metrics on a per-resource basis via tags that are associated with meters. This is the default, historical behavior but
+this will change in a future version of JOSDK because this dramatically increases the cardinality of metrics, which
+could lead to performance issues.
+
+To create a `MicrometerMetrics` implementation that behaves how it has historically behaved, you can just create an
+instance via:
+
+```java
+MeterRegistry registry; // initialize your registry implementation
+Metrics metrics = new MicrometerMetrics(registry);
+```
+
+Note, however, that this constructor is deprecated and we encourage you to use the factory methods instead, which either
+return a fully pre-configured instance or a builder object that will allow you to configure more easily how the instance
+will behave. You can, for example, configure whether or not the implementation should collect metrics on a per-resource
+basis, whether or not associated meters should be removed when a resource is deleted and how the clean-up is performed.
+See the relevant classes documentation for more details.
+
+For example, the following will create a `MicrometerMetrics` instance configured to collect metrics on a per-resource
+basis, deleting the associated meters after 5 seconds when a resource is deleted, using up to 2 threads to do so.
+
+```java
+MicrometerMetrics.newPerResourceCollectingMicrometerMetricsBuilder(registry)
+ .withCleanUpDelayInSeconds(5)
+ .withCleaningThreadNumber(2)
+ .build();
+```
+
+### Operator SDK metrics
+
+The micrometer implementation records the following metrics:
+
+| Meter name | Type | Tag names | Description |
+|-------------------------------------------------------------|----------------|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
+| operator.sdk.reconciliations.executions.`` | gauge | group, version, kind | Number of executions of the named reconciler |
+| operator.sdk.reconciliations.queue.size.`` | gauge | group, version, kind | How many resources are queued to get reconciled by named reconciler |
+| operator.sdk.`
+
+Java Operator SDK is a CNCF project as part of [Operator Framework](https://github.com/operator-framework).
+
## Documentation
Documentation can be found on the **[JOSDK WebSite](https://javaoperatorsdk.io/)**.
@@ -43,13 +47,13 @@ It makes it easy to implement best practices and patterns for an Operator. Featu
* Easy to use Error Handling
* ... and everything that a batteries included framework needs
-For all features and their usage see the [related section on the website](https://javaoperatorsdk.io/docs/features).
+For all features and their usage see the [related sections on the website](https://javaoperatorsdk.io/docs/documentation/).
## Related Projects
* Quarkus Extension: https://github.com/quarkiverse/quarkus-operator-sdk
* Spring Boot Starter: https://github.com/java-operator-sdk/operator-framework-spring-boot-starter
-* Kubernetes Glue Operator: https://github.com/csviri/kubernetes-glue-operator
+* Kubernetes Glue Operator: https://github.com/java-operator-sdk/kubernetes-glue-operator
Meta-operator that builds upon to use JOSDK Workflows and Dependent Resources features and
allows to create operators by simply applying a custom resource, thus, is a language independent way.
* Kubernetes Webhooks Framework: https://github.com/java-operator-sdk/kubernetes-webooks-framework
@@ -63,6 +67,7 @@ projects want to advertise that fact here. For this reason, we ask that if you'd
to be featured in this section, please open a PR, adding a link to and short description of your
project, as shown below:
+- [kroxylicious](https://github.com/kroxylicious/kroxylicious/tree/main/kroxylicious-operator) Kafka proxy operator
- [ExposedApp operator](https://github.com/halkyonio/exposedapp-rhdblog): a sample operator
written to illustrate JOSDK concepts and its Quarkus extension in the ["Write Kubernetes
Operators in Java with the Java Operator SDK" blog series](https://developers.redhat.com/articles/2022/02/15/write-kubernetes-java-java-operator-sdk#).
diff --git a/bootstrapper-maven-plugin/pom.xml b/bootstrapper-maven-plugin/pom.xml
index fd69aa63af..c306dcea35 100644
--- a/bootstrapper-maven-plugin/pom.xml
+++ b/bootstrapper-maven-plugin/pom.xml
@@ -5,7 +5,7 @@