From 4f8d425098d31b932a98920d32b604743be7aac1 Mon Sep 17 00:00:00 2001 From: csviri Date: Wed, 1 Mar 2023 13:57:18 +0100 Subject: [PATCH 1/2] docs: better explain `noFinalizerRemoval` use case --- .../operator/api/reconciler/Cleaner.java | 7 ++++--- .../operator/api/reconciler/DeleteControl.java | 14 ++++++++++++++ 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java index 2a53d5730b..642f9786ab 100644 --- a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java +++ b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java @@ -21,9 +21,10 @@ public interface Cleaner

{ * @param resource the resource that is marked for deletion * @param context the context with which the operation is executed * @return {@link DeleteControl#defaultDelete()} - so the finalizer is automatically removed after - * the call. {@link DeleteControl#noFinalizerRemoval()} if you don't want to remove the - * finalizer to indicate that the resource should not be deleted after all, in which case - * the controller should restore the resource's state appropriately. + * the call. User {@link DeleteControl#noFinalizerRemoval()} if you don't want to remove + * the finalizer, thus to wait asynchronously for a resource to be deleted. In that case + * if EventSources are in place this method will be triggered again if the state of the + * resource changed, and it is safe remove finalizer is already delete. */ DeleteControl cleanup(P resource, Context

context); diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DeleteControl.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DeleteControl.java index e27698c989..5becc99803 100644 --- a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DeleteControl.java +++ b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DeleteControl.java @@ -1,5 +1,7 @@ package io.javaoperatorsdk.operator.api.reconciler; +import io.fabric8.kubernetes.api.model.HasMetadata; + public class DeleteControl extends BaseControl { private final boolean removeFinalizer; @@ -8,10 +10,22 @@ private DeleteControl(boolean removeFinalizer) { this.removeFinalizer = removeFinalizer; } + /** + * @return delete control that will remove finalizer. + */ public static DeleteControl defaultDelete() { return new DeleteControl(true); } + /** + * In some corner cases it might take some time while some secondary resources are cleaned up, in + * that case delete can be instructed and return for {@link Cleaner#cleanup(HasMetadata, Context)} + * method, that will be triggered again by an EventSource when the secondary resource is deleted. + * After all resources are cleaned up such async way it is safe to remove the finalizer, thus + * return defaultDelete from cleanup method. + * + * @return delete control that will not remove finalizer. + */ public static DeleteControl noFinalizerRemoval() { return new DeleteControl(false); } From e6ca756668f34a0f246d051c93a1633b3cdc80b6 Mon Sep 17 00:00:00 2001 From: Chris Laprun Date: Fri, 3 Mar 2023 10:40:17 +0100 Subject: [PATCH 2/2] fix: improve wording and typos [skip ci] --- .../operator/api/reconciler/Cleaner.java | 11 ++++++----- .../operator/api/reconciler/DeleteControl.java | 15 ++++++++------- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java index 642f9786ab..1e75764f80 100644 --- a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java +++ b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java @@ -6,7 +6,7 @@ public interface Cleaner

{ /** * This method turns on automatic finalizer usage. - * + *

* The implementation should delete the associated component(s). This method is called when an * object is marked for deletion. After it's executed the custom resource finalizer is * automatically removed by the framework; unless the return value is @@ -21,10 +21,11 @@ public interface Cleaner

{ * @param resource the resource that is marked for deletion * @param context the context with which the operation is executed * @return {@link DeleteControl#defaultDelete()} - so the finalizer is automatically removed after - * the call. User {@link DeleteControl#noFinalizerRemoval()} if you don't want to remove - * the finalizer, thus to wait asynchronously for a resource to be deleted. In that case - * if EventSources are in place this method will be triggered again if the state of the - * resource changed, and it is safe remove finalizer is already delete. + * the call. Use {@link DeleteControl#noFinalizerRemoval()} when you don't want to remove + * the finalizer immediately but rather wait asynchronously until all secondary resources + * are deleted, thus allowing you to keep the primary resource around until you are sure + * that it can be safely deleted. + * @see DeleteControl#noFinalizerRemoval() */ DeleteControl cleanup(P resource, Context

context); diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DeleteControl.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DeleteControl.java index 5becc99803..7160e70830 100644 --- a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DeleteControl.java +++ b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DeleteControl.java @@ -1,7 +1,5 @@ package io.javaoperatorsdk.operator.api.reconciler; -import io.fabric8.kubernetes.api.model.HasMetadata; - public class DeleteControl extends BaseControl { private final boolean removeFinalizer; @@ -18,11 +16,14 @@ public static DeleteControl defaultDelete() { } /** - * In some corner cases it might take some time while some secondary resources are cleaned up, in - * that case delete can be instructed and return for {@link Cleaner#cleanup(HasMetadata, Context)} - * method, that will be triggered again by an EventSource when the secondary resource is deleted. - * After all resources are cleaned up such async way it is safe to remove the finalizer, thus - * return defaultDelete from cleanup method. + * In some corner cases it might take some time for secondary resources to be cleaned up. In such + * situation, the reconciler shouldn't remove the finalizer until it is safe for the primary + * resource to be deleted (because, e.g., secondary resources being removed might need its + * information to proceed correctly). Using this method will instruct the reconciler to leave the + * finalizer in place, presumably to wait for a new reconciliation triggered by event sources on + * the secondary resources (e.g. when they are effectively deleted/cleaned-up) to check whether it + * is now safe to delete the primary resource and therefore, remove its finalizer by returning + * {@link #defaultDelete()} then. * * @return delete control that will not remove finalizer. */