Merge branch 'main' into next

# Conflicts:
#	micrometer-support/pom.xml
#	operator-framework-core/pom.xml
#	operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ControllerConfiguration.java
#	operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ControllerConfigurationOverrider.java
#	operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/DefaultControllerConfiguration.java
#	operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ControllerConfiguration.java
#	operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/Controller.java
#	operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventSourceManager.java
#	operator-framework-core/src/test/java/io/javaoperatorsdk/operator/ControllerManagerTest.java
#	operator-framework-core/src/test/java/io/javaoperatorsdk/operator/processing/event/source/ResourceEventFilterTest.java
#	operator-framework-junit5/pom.xml
#	operator-framework/pom.xml
#	operator-framework/src/main/java/io/javaoperatorsdk/operator/config/runtime/AnnotationConfiguration.java
#	pom.xml
#	sample-operators/mysql-schema/pom.xml
#	sample-operators/pom.xml
#	sample-operators/tomcat-operator/pom.xml
#	sample-operators/webpage/pom.xml
#	smoke-test-samples/common/pom.xml
#	smoke-test-samples/pom.xml
#	smoke-test-samples/pure-java/pom.xml
#	smoke-test-samples/spring-boot-plain/pom.xml

Author: csviri

.github/workflows/pr.yml

@@ -11,27 +11,48 @@ on:
     branches: [ main, v1, next ]
   workflow_dispatch:
 jobs:
-  build:
+  check_format_and_unit_tests:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        java: [ 11, 17 ]
-        distribution: [ temurin ]
-        kubernetes: [ 'v1.17.13','v1.18.20','v1.19.14','v1.20.10','v1.21.4', 'v1.22.1', 'v1.23.0' ]
     steps:
       - uses: actions/checkout@v2
       - name: Set up Java and Maven
         uses: actions/setup-java@v2
         with:
-          distribution: ${{ matrix.distribution }}
-          java-version: ${{ matrix.java }}
+          distribution: temurin
+          java-version: 17
           cache: 'maven'
       - name: Check code format
         run: |
           ./mvnw ${MAVEN_ARGS} formatter:validate -Dconfigfile=$PWD/contributing/eclipse-google-style.xml --file pom.xml
           ./mvnw ${MAVEN_ARGS} impsort:check --file pom.xml
       - name: Run unit tests
         run: ./mvnw ${MAVEN_ARGS} -B test --file pom.xml
+
+  integration_tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        java: [ 11, 17 ]
+        kubernetes: [ 'v1.17.13','v1.18.20','v1.19.14','v1.20.10','v1.21.4', 'v1.22.1', 'v1.23.0' ]
+        exclude:
+          - java: 11
+            kubernetes: 'v1.18.20'
+          - java: 11
+            kubernetes: 'v1.19.14'
+          - java: 11
+            kubernetes: 'v1.20.10'
+          - java: 11
+            kubernetes: 'v1.21.4'
+          - java: 11
+            kubernetes: 'v1.22.1'
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Java and Maven
+        uses: actions/setup-java@v2
+        with:
+          distribution: temurin
+          java-version: ${{ matrix.java }}
+          cache: 'maven'
       - name: Set up Minikube
         uses: manusa/[email protected]
         with:

.github/workflows/sonar.yml

@@ -15,6 +15,7 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    if: ${{ ( github.event_name == 'push' ) || ( github.event_name == 'pull_request' && github.event.pull_request.head.repo.owner.login == 'java-operator-sdk' ) }}
     steps:
       - uses: actions/checkout@v2
       - name: Set up Java and Maven

README.md

@@ -44,5 +44,5 @@ Operator SDK plugin: https://github.com/operator-framework/java-operator-plugins
 
 Quarkus Extension: https://github.com/quarkiverse/quarkus-operator-sdk
 
-
+Spring Boot Starter: https://github.com/java-operator-sdk/operator-framework-spring-boot-starter
 

docs/_includes/hero.html

@@ -5,13 +5,13 @@
       {% endif %}
     <h1 class="uk-heading-hero uk-text-bold uk-text-uppercase uk-text-muted uk-inline " style="font-family: 'Asap', sans-serif"> [ <small class="uk-margin-small-right uk-margin-small-left"> {{ site.title }} </small> ]</h1>
     <div class="links uk-container uk-margin-medium-top">
-      <a class="uk-button uk-button-small uk-border-pill uk-button-secondary uk-margin-small-bottom" href="{{ domain }}{{ link.url }}">
+      <a class="uk-button uk-button-small uk-border-pill uk-button-secondary uk-margin-small-bottom" href="/docs/getting-started">
         Get Started
       </a>
-      <a class="uk-button uk-button-small uk-border-pill uk-button-default uk-margin-small-bottom " href="{{ domain }}{{ link.url }}">
+      <a class="uk-button uk-button-small uk-border-pill uk-button-default uk-margin-small-bottom " href="/docs/contributing">
         <span uk-icon="github"></span> Contribute
       </a>
-      <a class="uk-button uk-button-small uk-border-pill uk-button-default uk-margin-small-bottom" href="{{ domain }}{{ link.url }}">
+      <a class="uk-button uk-button-small uk-border-pill uk-button-default uk-margin-small-bottom" href="https://discord.gg/DacEhAy">
         <span uk-icon="discord"></span> Discord Channel
       </a>
     </div>

docs/documentation/features.md

@@ -137,17 +137,13 @@ mostly for the cases when there is a long waiting period after a delete operatio
 you might want to either schedule a timed event to make sure
 `cleanup` is executed again or use event sources to get notified about the state changes of a deleted resource.
 
-## Generation Awareness and Automatic Observed Generation Handling
+## Automatic Observed Generation Handling
 
 Having `.observedGeneration` value on the status of the resource is a best practice to indicate the last generation of
 the resource reconciled successfully by the controller. This helps the users / administrators to check if the custom
-resource was reconciled, but it is used to decide if a reconciliation should happen or not. Filtering events based on
-generation is supported by the framework and turned on by default. There are two modes.
+resource was reconciled.
 
-### Primary (preferred) Mode
-
-The first and the **preferred** one is to check after a resource event received, if the generation of the resource is
-larger than the `.observedGeneration` field on status. In order to have this feature working:
+In order to have this feature working:
 
 - the **status class** (not the resource) must implement the
   [`ObservedGenerationAware`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/ObservedGenerationAware.java)
@@ -160,9 +156,7 @@ larger than the `.observedGeneration` field on status. In order to have this fea
   .
 
 If these conditions are fulfilled and generation awareness not turned off, the observed generation is automatically set
-by the framework after the `reconcile` method is called. There is just one exception, when the reconciler returns
-with `UpdateControl.updateResource`, in this case the status is not updated, just the custom resource - however, this
-update will lead to a new reconciliation. Note that the observed generation is updated also
+by the framework after the `reconcile` method is called. Note that the observed generation is updated also
 when `UpdateControl.noUpdate()` is returned from the reconciler. See this feature working in
 the [WebPage example](https://github.com/java-operator-sdk/java-operator-sdk/blob/b91221bb54af19761a617bf18eef381e8ceb3b4c/sample-operators/webpage/src/main/java/io/javaoperatorsdk/operator/sample/WebPageStatus.java#L5)
 .
@@ -191,15 +185,18 @@ public class WebPage extends CustomResource<WebPageSpec, WebPageStatus>
 }
 ```
 
-### The Second (Fallback) Mode
+## Generation Awareness and Event Filtering
+
+On an operator startup, the best practice is to reconcile all the resources. Since while operator was down, changes
+might have made both to custom resource and dependent resources. 
 
-The second, fallback mode is (when the conditions from above are not met to handle the observed generation automatically
-in status) to handle generation filtering in memory. Thus, if an event is received, the generation of the received
-resource is compared with the resource in the cache.
+When the first reconciliation is done successfully, the next reconciliation is triggered if either the dependent 
+resources are changed or the custom resource `.spec` is changed. If other fields like `.metadata` is changed on the 
+custom resource, the reconciliation could be skipped. This is supported out of the box, thus the reconciliation by 
+default is not triggered if the change to the main custom resource does not increase the `.metadata.generation` field.
+Note that the increase of `.metada.generation`  is handled automatically by Kubernetes.
 
-Note that the **first approach has significant benefits** in the situation when the operator is restarted and there is
-no cached resource anymore. In case two this leads to a reconciliation of every resource, event if the resource is not
-changed while the operator was not running.
+To turn on this feature set `generationAwareEventProcessing` to `false` for the `Reconciler`.
 
 ## Support for Well Known (non-custom) Kubernetes Resources
 
@@ -223,6 +220,30 @@ public class DeploymentReconciler
   }
 ```
 
+## Max Interval Between Reconciliations
+
+In case informers are all in place and reconciler is implemented correctly, there is no need for additional triggers. 
+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 the resources are reconciled after certain time. This functionality is in place by default, there
+is quite high interval (currently 10 hours) while the reconciliation is triggered. See how to override this using 
+the standard annotation:
+
+```java
+@ControllerConfiguration(finalizerName = NO_FINALIZER,
+        reconciliationMaxInterval = @ReconciliationMaxInterval(
+                interval = 50,
+                timeUnit = TimeUnit.MILLISECONDS))
+```
+
+The event is not propagated in a fixed rate, rather it's scheduled after each reconciliation. So the 
+next reconciliation will after at most within the specified interval after last reconciliation.
+
+This feature can be turned off by setting `reconciliationMaxInterval` to [`Constants.NO_RECONCILIATION_MAX_INTERVAL`](https://github.com/java-operator-sdk/java-operator-sdk/blob/442e7d8718e992a36880e42bd0a5c01affaec9df/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Constants.java#L8-L8)
+or any non-positive number.
+
+The automatic retries are not affected by this feature, in case of an error no schedule is set by this feature. 
+
 ## Automatic Retries on Error
 
 When an exception is thrown from a controller, the framework will schedule an automatic retry of the reconciliation. The

docs/documentation/patterns-best-practices.md

@@ -7,22 +7,79 @@ permalink: /docs/patterns-best-practices
 
 # Patterns and Best Practices
 
-This document describes patters and best practices, to build and run operators, and how to implement them in terms
-of Java Operator SDK.
+This document describes patterns and best practices, to build and run operators, and how to implement them in terms of
+Java Operator SDK.
+
+See also best practices in [Operator SDK](https://sdk.operatorframework.io/docs/best-practices/best-practices/).
 
 ## Implementing a Reconciler
 
+### Reconcile All The Resources All the Time
+
+The reconciliation can be triggered by events from multiple sources. It could be tempting to check the events and
+reconcile just the related resource or subset of resources that the controller manages. However, this is **considered as
+an anti-pattern** in operators. If triggered, all resources should be reconciled. Usually this means only comparing the
+target state with the current state in the cache for most of the resource. The reason behind this is events not reliable
+In general, this means events can be lost. In addition to that the operator can crash and while down will miss events.
+
+In addition to that such approach might even complicate implementation logic in the `Reconciler`, since parallel
+execution of the reconciler is not allowed for the same custom resource, there can be multiple events received for the
+same resource or dependent resource during an ongoing execution, ordering those events could be also challenging.
+
+Since there is a consensus regarding this in the industry, from v2 the events are not even accessible for
+the `Reconciler`.
+
+### EventSources and Caching
+
+As mentioned above during a reconciliation best practice is to reconcile all the dependent resources managed by the
+controller. This means that we want to compare a target state with the actual state of the cluster. Reading the actual
+state of a resource from the Kubernetes API Server directly all the time would mean a significant load. Therefore, it's
+a common practice to instead create a watch for the dependent resources and cache their latest state. This is done
+following the Informer pattern. In Java Operator SDK, informer is wrapped into an EventSource, to integrate it with the
+eventing system of the framework, resulting in `InformerEventSource`.
+
+A new event that triggers the reconciliation is propagated when the actual resource is already in cache. So in
+reconciler what should be just done is to compare the target calculated state of a dependent resource of the actual
+state from the cache of the event source. If it is changed or not in the cache it needs to be created, respectively
+updated.
+
 ### Idempotency
 
-### Sync of Async Way of Resource Handling
+Since all the resources are reconciled during an execution and an execution can be triggered quite often, also retries
+of a reconciliation can happen naturally in operators, the implementation of a `Reconciler`
+needs to be idempotent. Luckily, since operators are usually managing already declarative resources, this is trivial to
+do in most cases.
 
-## Why to Have Automated Retries?
+### Sync or Async Way of Resource Handling
 
-## Managing State
+In an implementation of reconciliation there can be a point when reconciler needs to wait a non-insignificant amount of
+time while a resource gets up and running. For example, reconciler would do some additional step only if a Pod is ready
+to receive requests. This problem can be approached in two ways synchronously or asynchronously.
 
-## Dependent Resources
+The async way is just return from the reconciler, if there are informers properly in place for the target resource,
+reconciliation will be triggered on change. During the reconciliation the pod can be read from the cache of the informer
+and a check on it's state can be conducted again. The benefit of this approach is that it will free up the thread, so it
+can be used to reconcile other resources.
 
-### EventSources and Caching
+The sync way would be to periodically poll the cache of the informer for the pod's state, until the target state is
+reached. This would block the thread until the state is reached, which in some cases could take quite long.
+
+## Why to Have Automated Retries?
+
+Automatic retries are in place by default, it can be fine-tuned, but in general it's not advised to turn of automatic
+retries. One of the reasons is that issues like network error naturally happen and are usually solved by a retry.
+Another typical situation is for example when a dependent resource or the custom resource is updated, during the update
+usually there is optimistic version control in place. So if someone updated the resource during reconciliation, maybe
+using `kubectl` or another process, the update would fail on a conflict. A retry solves this problem simply by executing
+the reconciliation again.
+
+## Managing State
 
-### Why are Events Irrelevant?
+When managing only kubernetes resources an explicit state is not necessary about the resources. The state can be
+read/watched, also filtered using labels. Or just following some naming convention. However, when managing external
+resources, there can be a situation for example when the created resource can only be addressed by an ID generated when
+the resource was created. This ID needs to be stored, so on next reconciliation it could be used to addressing the
+resource. One place where it could go is the status sub-resource. On the other hand by definition status should be just
+the result of a reconciliation. Therefore, it's advised in general, to put such state into a separate resource usually a
+Kubernetes Secret or ConfigMap or a dedicated CustomResource, where the structure can be also validated.
 

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/Operator.java

@@ -180,7 +180,8 @@ public synchronized void stop() {
 
     public synchronized void add(Controller controller) {
       final var configuration = controller.getConfiguration();
-      final var resourceTypeName = configuration.getResourceTypeName();
+      final var resourceTypeName = ReconcilerUtils
+          .getResourceTypeNameWithVersion(configuration.getResourceClass());
       final var existing = controllers.get(resourceTypeName);
       if (existing != null) {
         throw new OperatorException("Cannot register controller '" + configuration.getName()

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/ReconcilerUtils.java

@@ -40,9 +40,13 @@ public void setApiVersion(String s) {
     return Constants.NO_FINALIZER.equals(finalizer) || validator.isFinalizerValid(finalizer);
   }
 
-  public static String getResourceTypeName(Class<? extends HasMetadata> resourceClass) {
-    // todo: use fabric8 method when 5.12 is released
-    // return HasMetadata.getFullResourceName(resourceClass);
+  public static String getResourceTypeNameWithVersion(Class<? extends HasMetadata> resourceClass) {
+    final var version = HasMetadata.getVersion(resourceClass);
+    return getResourceTypeName(resourceClass) + "/" + version;
+  }
+
+  public static String getResourceTypeName(
+      Class<? extends HasMetadata> resourceClass) {
     final var group = HasMetadata.getGroup(resourceClass);
     final var plural = HasMetadata.getPlural(resourceClass);
     return (group == null || group.isEmpty()) ? plural : plural + "." + group;

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/ObservedGenerationAware.java

@@ -6,9 +6,7 @@
 
 /**
  * If the custom resource's status implements this interface, the observed generation will be
- * automatically handled. The last observed generation will be updated on status. In addition to
- * that, controller configuration will be checked if is set to be generation aware. If generation
- * aware config is turned off, this interface is ignored.
+ * automatically handled. The last observed generation will be updated on status.
  * <p>
  * In order for this automatic handling to work the status object returned by
  * {@link CustomResource#getStatus()} should not be null.

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ControllerConfiguration.java

@@ -1,7 +1,11 @@
 package io.javaoperatorsdk.operator.api.config;
 
+import java.lang.reflect.ParameterizedType;
+import java.time.Duration;
 import java.util.Collections;
 import java.util.List;
+import java.util.Optional;
+import java.util.Set;
 
 import io.fabric8.kubernetes.api.model.HasMetadata;
 import io.javaoperatorsdk.operator.ReconcilerUtils;
@@ -55,4 +59,8 @@ default List<DependentResourceConfiguration> getDependentResources() {
   default DependentResourceControllerFactory<R> dependentFactory() {
     return new DependentResourceControllerFactory<>() {};
   }
+
+  default Optional<Duration> reconciliationMaxInterval() {
+    return Optional.of(Duration.ofHours(10L));
+  }
 }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ControllerConfigurationOverrider.java

@@ -1,5 +1,6 @@
 package io.javaoperatorsdk.operator.api.config;
 
+import java.time.Duration;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
@@ -16,6 +17,7 @@ public class ControllerConfigurationOverrider<R extends HasMetadata> {
   private String labelSelector;
   private ResourceEventFilter<R> customResourcePredicate;
   private final ControllerConfiguration<R> original;
+  private Duration reconciliationMaxInterval;
 
   private ControllerConfigurationOverrider(ControllerConfiguration<R> original) {
     finalizer = original.getFinalizer();
@@ -24,7 +26,9 @@ private ControllerConfigurationOverrider(ControllerConfiguration<R> original) {
     retry = original.getRetryConfiguration();
     labelSelector = original.getLabelSelector();
     customResourcePredicate = original.getEventFilter();
+    reconciliationMaxInterval = original.reconciliationMaxInterval().orElse(null);
     this.original = original;
+
   }
 
   public ControllerConfigurationOverrider<R> withFinalizer(String finalizer) {
@@ -74,6 +78,12 @@ public ControllerConfigurationOverrider<R> withCustomResourcePredicate(
     return this;
   }
 
+  public ControllerConfigurationOverrider<R> withReconciliationMaxInterval(
+      Duration reconciliationMaxInterval) {
+    this.reconciliationMaxInterval = reconciliationMaxInterval;
+    return this;
+  }
+
   public ControllerConfiguration<R> build() {
     return new DefaultControllerConfiguration<>(
         original.getAssociatedReconcilerClassName(),
@@ -86,6 +96,7 @@ public ControllerConfiguration<R> build() {
         labelSelector,
         customResourcePredicate,
         original.getResourceClass(),
+        reconciliationMaxInterval,
         original.getConfigurationService(),
         original.getDependentResources());
   }