Annotated integration test classes

Signed-off-by: Attila Mészáros <[email protected]>

Author: csviri

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/ConcurrencyIT.java

@@ -10,6 +10,7 @@
 import org.slf4j.LoggerFactory;
 
 import io.fabric8.kubernetes.api.model.ConfigMap;
+import io.javaoperatorsdk.annotation.Sample;
 import io.javaoperatorsdk.operator.baseapi.simple.TestCustomResource;
 import io.javaoperatorsdk.operator.baseapi.simple.TestReconciler;
 import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
@@ -18,6 +19,13 @@
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.awaitility.Awaitility.await;
 
+@Sample(
+    tldr = "Concurrent Reconciliation of Multiple Resources",
+    description =
+        "Demonstrates the operator's ability to handle concurrent reconciliation of multiple"
+            + " resources. The test creates, updates, and deletes many resources simultaneously to"
+            + " verify proper handling of concurrent operations, ensuring thread safety and correct"
+            + " resource state management under load.")
 class ConcurrencyIT {
   public static final int NUMBER_OF_RESOURCES_CREATED = 50;
   public static final int NUMBER_OF_RESOURCES_DELETED = 30;

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/builtinresourcecleaner/BuiltInResourceCleanerIT.java

@@ -8,13 +8,21 @@
 import org.slf4j.LoggerFactory;
 
 import io.fabric8.kubernetes.api.model.Service;
+import io.javaoperatorsdk.annotation.Sample;
 import io.javaoperatorsdk.operator.ReconcilerUtils;
 import io.javaoperatorsdk.operator.dependent.standalonedependent.StandaloneDependentResourceIT;
 import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.awaitility.Awaitility.await;
 
+@Sample(
+    tldr = "Cleanup handler for built-in Kubernetes resources",
+    description =
+        "Demonstrates how to implement cleanup handlers (finalizers) for built-in Kubernetes"
+            + " resources like Service and Pod. These resources don't use generation the same way"
+            + " as custom resources, so this sample shows the proper approach to handle their"
+            + " lifecycle and cleanup logic.")
 class BuiltInResourceCleanerIT {
 
   private static final Logger log = LoggerFactory.getLogger(BuiltInResourceCleanerIT.class);

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/changenamespace/ChangeNamespaceIT.java

@@ -14,13 +14,22 @@
 import io.fabric8.kubernetes.api.model.NamespaceBuilder;
 import io.fabric8.kubernetes.api.model.ObjectMetaBuilder;
 import io.fabric8.kubernetes.client.KubernetesClient;
+import io.javaoperatorsdk.annotation.Sample;
 import io.javaoperatorsdk.operator.RegisteredController;
 import io.javaoperatorsdk.operator.api.reconciler.Constants;
 import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.awaitility.Awaitility.await;
 
+@Sample(
+    tldr = "Dynamically Changing Watched Namespaces",
+    description =
+        "Demonstrates how to dynamically change the set of namespaces that an operator watches at"
+            + " runtime. This feature allows operators to add or remove namespaces from their watch"
+            + " list, including switching between specific namespaces and watching all namespaces."
+            + " The test verifies that resources in newly added namespaces are reconciled and"
+            + " resources in removed namespaces are no longer watched.")
 class ChangeNamespaceIT {
 
   public static final String TEST_RESOURCE_NAME_1 = "test1";

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/cleanerforreconciler/CleanerForReconcilerIT.java

@@ -4,11 +4,21 @@
 import org.junit.jupiter.api.extension.RegisterExtension;
 
 import io.fabric8.kubernetes.api.model.ObjectMeta;
+import io.javaoperatorsdk.annotation.Sample;
 import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.awaitility.Awaitility.await;
 
+@Sample(
+    tldr = "Implementing Cleanup Logic with Cleaner Interface",
+    description =
+        "Demonstrates how to implement cleanup logic for custom resources using the Cleaner"
+            + " interface. When a reconciler implements Cleaner, the framework automatically adds a"
+            + " finalizer to resources and calls the cleanup method when the resource is deleted."
+            + " This pattern is useful for cleaning up external resources or performing custom"
+            + " deletion logic. The test verifies finalizer handling, cleanup execution, and the"
+            + " ability to reschedule cleanup operations.")
 class CleanerForReconcilerIT {
 
   public static final String TEST_RESOURCE_NAME = "cleaner-for-reconciler-test1";

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/createupdateeventfilter/CreateUpdateInformerEventSourceEventFilterIT.java

@@ -7,12 +7,20 @@
 
 import io.fabric8.kubernetes.api.model.ConfigMap;
 import io.fabric8.kubernetes.api.model.ObjectMeta;
+import io.javaoperatorsdk.annotation.Sample;
 import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
 
 import static io.javaoperatorsdk.operator.baseapi.createupdateeventfilter.CreateUpdateEventFilterTestReconciler.CONFIG_MAP_TEST_DATA_KEY;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.awaitility.Awaitility.await;
 
+@Sample(
+    tldr = "Event filtering for create and update operations",
+    description =
+        "Shows how to configure event filters on informer event sources to control which create and"
+            + " update events trigger reconciliation. This is useful for preventing unnecessary"
+            + " reconciliation loops when dependent resources are modified by the controller"
+            + " itself.")
 class CreateUpdateInformerEventSourceEventFilterIT {
 
   @RegisterExtension

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/deployment/KubernetesResourceStatusUpdateIT.java

@@ -17,12 +17,21 @@
 import io.fabric8.kubernetes.api.model.PodTemplateSpec;
 import io.fabric8.kubernetes.api.model.apps.Deployment;
 import io.fabric8.kubernetes.api.model.apps.DeploymentSpec;
+import io.javaoperatorsdk.annotation.Sample;
 import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
 
 import static io.javaoperatorsdk.operator.baseapi.deployment.DeploymentReconciler.STATUS_MESSAGE;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.awaitility.Awaitility.await;
 
+@Sample(
+    tldr = "Reconciling Non-Custom Kubernetes Resources with Status Updates",
+    description =
+        "Demonstrates how to reconcile standard Kubernetes resources (like Deployments) instead of"
+            + " custom resources, and how to update their status subresource. This pattern is"
+            + " useful when building operators that manage native Kubernetes resources rather than"
+            + " custom resource definitions. The test verifies that the operator can watch,"
+            + " reconcile, and update the status of a Deployment resource.")
 class KubernetesResourceStatusUpdateIT {
 
   @RegisterExtension

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/errorstatushandler/ErrorStatusHandlerIT.java

@@ -6,12 +6,20 @@
 import org.junit.jupiter.api.extension.RegisterExtension;
 
 import io.fabric8.kubernetes.api.model.ObjectMetaBuilder;
+import io.javaoperatorsdk.annotation.Sample;
 import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
 import io.javaoperatorsdk.operator.processing.retry.GenericRetry;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.awaitility.Awaitility.await;
 
+@Sample(
+    tldr = "Error Status Handler for Failed Reconciliations",
+    description =
+        "Demonstrates how to implement error status handlers that update resource status when"
+            + " reconciliations fail. The test verifies that error messages are properly recorded"
+            + " in the resource status after each failed retry attempt. This provides visibility"
+            + " into reconciliation failures and helps with debugging operator issues.")
 class ErrorStatusHandlerIT {
 
   public static final int MAX_RETRY_ATTEMPTS = 3;

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/event/EventSourceIT.java

@@ -6,12 +6,20 @@
 import org.junit.jupiter.api.extension.RegisterExtension;
 
 import io.fabric8.kubernetes.api.model.ObjectMetaBuilder;
+import io.javaoperatorsdk.annotation.Sample;
 import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
 import io.javaoperatorsdk.operator.support.TestUtils;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.awaitility.Awaitility.await;
 
+@Sample(
+    tldr = "Custom Event Source for Periodic Reconciliation",
+    description =
+        "Demonstrates how to implement custom event sources that trigger reconciliation on a"
+            + " periodic basis. The test verifies that reconciliations are triggered at regular"
+            + " intervals by a timer-based event source. This enables operators to perform periodic"
+            + " checks or updates independent of resource changes.")
 class EventSourceIT {
 
   @RegisterExtension

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/filter/FilterIT.java

@@ -6,12 +6,20 @@
 import org.junit.jupiter.api.extension.RegisterExtension;
 
 import io.fabric8.kubernetes.api.model.ObjectMetaBuilder;
+import io.javaoperatorsdk.annotation.Sample;
 import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
 
 import static io.javaoperatorsdk.operator.baseapi.filter.FilterTestReconciler.CONFIG_MAP_FILTER_VALUE;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.awaitility.Awaitility.await;
 
+@Sample(
+    tldr = "Filtering Events for Primary and Secondary Resources",
+    description =
+        "Demonstrates how to implement event filters for both primary custom resources and"
+            + " secondary dependent resources. The test verifies that resource updates matching"
+            + " specific filter criteria are ignored and don't trigger reconciliation. This helps"
+            + " reduce unnecessary reconciliation executions and improve operator efficiency.")
 class FilterIT {
 
   public static final String RESOURCE_NAME = "test1";

operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/generickubernetesresourcehandling/GenericKubernetesResourceHandlingIT.java

@@ -3,10 +3,19 @@
 import org.junit.jupiter.api.extension.RegisterExtension;
 
 import io.fabric8.kubernetes.api.model.ObjectMetaBuilder;
+import io.javaoperatorsdk.annotation.Sample;
 import io.javaoperatorsdk.operator.dependent.generickubernetesresource.GenericKubernetesDependentSpec;
 import io.javaoperatorsdk.operator.dependent.generickubernetesresource.GenericKubernetesDependentTestBase;
 import io.javaoperatorsdk.operator.junit.LocallyRunOperatorExtension;
 
+@Sample(
+    tldr = "Working with GenericKubernetesResource for Dynamic Resource Types",
+    description =
+        "Demonstrates how to use GenericKubernetesResource to work with Kubernetes resources"
+            + " dynamically without requiring compile-time type definitions. This approach is"
+            + " useful when building operators that need to manage arbitrary Kubernetes resources"
+            + " or when the resource types are not known at compile time. The test shows how to"
+            + " handle generic resources as dependent resources in a reconciler.")
 public class GenericKubernetesResourceHandlingIT
     extends GenericKubernetesDependentTestBase<GenericKubernetesResourceHandlingCustomResource> {