@@ -57,7 +57,7 @@ annotation for more details.
5757
5858### When not to Use Finalizers?
5959
60- Typically, automated finalizer handling should be turned off, when ** all** the cleanup of the dependent resources is
60+ Typically, automated finalizer handling should be turned off, in case ** all** the cleanup of the dependent resources is
6161handled by Kubernetes itself. This is handled by
6262Kubernetes [ garbage collection] ( https://kubernetes.io/docs/concepts/architecture/garbage-collection/#owners-dependents ) .
6363Setting the owner reference and related fields are not in the scope of the SDK for now, it's up to the user to have them
@@ -67,7 +67,43 @@ When automatic finalizer handling is turned off, the `ResourceController.deleteR
6767case of a delete event received. So it does not make sense to implement this method and turn off finalizer at the same
6868time.
6969
70- ## Separating ` createOrUpdate ` from ` delete `
70+ ## The ` createOrUpdateResource ` and ` deleteResource ` Methods of ` ResourceController `
71+
72+ The lifecycle of a custom resource can be clearly separated to two phases from a perspective of an operator.
73+ When a custom resource is created or update, or on the other hand when the custom resource is deleted - or rater
74+ marked for deletion in case a finalizer is used.
75+
76+ There is no point to make a distinction between create and update, since the reconciliation
77+ logic typically would be very similar or identical in most of the cases.
78+
79+ This separation related logic is automatically handled by framework. The framework will always call ` createOrUpdateResource `
80+ function, unless the custom resource is
81+ [ marked from deletion] ( https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/#how-finalizers-work ) .
82+ From the point when the custom resource is marked from deletion, only the ` deleteResource ` method is called.
83+
84+ If there is ** no finalizer** in place (see Finalizer Support section), the ` deleteResource ` method is ** not called** .
85+
86+ ### Using ` UpdateControl ` and ` DeleteControl `
87+
88+ These two methods are used to control the outcome or the desired behavior after the reconciliation.
89+
90+ The ` UpdateControl ` can instruct the framework to update the custom resource status sub-resource and/or re-schedule
91+ a reconciliation with a desired time delay. Those are the typical use cases, however in some cases there it can happen
92+ that the controller wants to update the custom resource itself (like adding annotations) or not to do any updates,
93+ which are also supported.
94+
95+ It is also possible to update both the status and the custom resource with ` updateCustomResourceAndStatus ` method.
96+ In this case first the custom resource is updated then the status in two separate requests to K8S API.
97+
98+ Always update the custom resource with ` UpdateControl ` , not with the actual kubernetes client if possible.
99+
100+ The ` DeleteControl ` typically instructs the framework to remove the finalizer after the dependent resource are
101+ cleaned up in ` deleteResource ` implementation.
102+
103+ However, there is a possibility to not remove the finalizer, this
104+ allows to clean up the resources in a more async way, mostly for the cases when there is a long waiting period after a delete
105+ operation is initiated. Note that in this case you might want to either schedule a timed event to make sure the
106+ ` deleteResource ` is executed again or use event sources get notified about the state changes of a deleted resource.
71107
72108## Automatic Retries on Error
73109
0 commit comments