diff --git a/docs/documentation/dependent-resources.md b/docs/documentation/dependent-resources.md index 24b32ea0cd..e8f3fbe8fe 100644 --- a/docs/documentation/dependent-resources.md +++ b/docs/documentation/dependent-resources.md @@ -7,21 +7,19 @@ permalink: /docs/dependent-resources # Dependent Resources -DISCLAIMER: The Dependent Resource support is relatively new and, while we strove to cover what we -anticipate will be the most common use cases, the implementation is not simple and might still -evolve. As a result, some APIs could be still a subject of change in the future. However, -non-backwards compatible changes are expected to be trivial to adapt to. +DISCLAIMER: The Dependent Resource support is relatively new feature, while we strove to cover what we anticipate will +be the most common use cases, the implementation is not simple and might still evolve. As a result, some APIs could be a +subject of change in the future. However, non-backwards compatible changes are expected to be trivial to migrate to. ## Motivations and Goals -Most operators need to deal with secondary resources when trying to realize the desired state -described by the primary resource it is in charge of. For example, the Kubernetes-native -`Deployment` controller needs to manage `ReplicaSet` instances as part of a `Deployment`'s -reconciliation process. In this instance, `ReplicatSet` is considered a secondary resource for -the `Deployment` controller. +Most operators need to deal with secondary resources when trying to realize the desired state described by the primary +resource it is in charge of. For example, the Kubernetes-native +`Deployment` controller needs to manage `ReplicaSet` instances as part of a `Deployment`'s reconciliation process. In +this instance, `ReplicatSet` is considered a secondary resource for the `Deployment` controller. -Controllers that deal with secondary resources typically need to perform the following steps, for -each secondary resource: +Controllers that deal with secondary resources typically need to perform the following steps, for each secondary +resource:
`](https://github.com/java-operator-sdk/java-operator-sdk/blob/b82c1f106968cb3eb18835c5e9cd1e4d5c40362e/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java) interface. -In other words, finalizer is added if the `Reconciler` implements `Cleaner` interface. If not, no +To use finalizers the reconciler have to implement [`Cleaner
`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java) interface.
+In other words, finalizer is added only if the `Reconciler` implements `Cleaner` interface. If not, no
finalizer is added and/or removed.
Finalizers are automatically added by the framework as the first step, thus after a custom resource is created, but
@@ -69,7 +69,7 @@ When automatic finalizer handling is turned off, the `Reconciler.cleanup(...)` m
case when a delete event received. So it does not make sense to implement this method and turn off finalizer at the same
time.
-## The `reconcile` and [`cleanup`](https://github.com/java-operator-sdk/java-operator-sdk/blob/b82c1f106968cb3eb18835c5e9cd1e4d5c40362e/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java) Methods on a [`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 [`reconcile`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Reconciler.java#L16) and [`cleanup`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java#L28)
The lifecycle of a custom resource can be clearly separated into two phases from the perspective of an operator. When a
custom resource is created or update, or on the other hand when the custom resource is deleted - or rather marked for
@@ -160,7 +160,7 @@ In order to have this feature working:
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. 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)
+the [WebPage example](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/sample-operators/webpage/src/main/java/io/javaoperatorsdk/operator/sample/WebPageStatus.java#L5)
.
```java
@@ -361,7 +361,7 @@ of requests to Kubernetes API server, and leads to faster reconciliation cycles.
Note that when an operator starts and the first reconciliation is executed the caches are already populated for example
for `InformerEventSource`. Currently, this is not true however for `PerResourceEventSource`, where the cache might or
might not be populated. To handle this situation elegantly methods are provided which checks the object in cache, if
-not found tries to get it from the supplier. See related [method](https://github.com/java-operator-sdk/java-operator-sdk/blob/e7fd79968a238d7e0acc446d949b83a06cea17b5/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/polling/PerResourcePollingEventSource.java#L145)
+not found tries to get it from the supplier. 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
diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/dependent/DependentResource.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/dependent/DependentResource.java
index 761e3d2a64..e562f6f244 100644
--- a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/dependent/DependentResource.java
+++ b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/dependent/DependentResource.java
@@ -23,7 +23,9 @@ public interface DependentResource context);
/**
- * Retrieves the dependent resource associated with the specified primary one
+ * The intention with get resource is to return the actual state of the resource. Usually from a
+ * local cache, what was updated after the reconciliation, or typically from the event source that
+ * caches the resources.
*
* @param primaryResource the primary resource for which we want to retrieve the secondary
* resource