docs: migrate v5 changes to docsy (#2397)

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

Author: csviri

docsy/content/en/docs/dependent-resources/_index.md

@@ -3,6 +3,8 @@ title: Dependent Resources
 weight: 60
 ---
 
+# Dependent Resources
+
 ## Motivations and Goals
 
 Most operators need to deal with secondary resources when trying to realize the desired state
@@ -96,13 +98,13 @@ and labels, which are ignored by default:
 
 ```java
 public class MyDependentResource extends KubernetesDependentResource<MyDependent, MyPrimary>
-    implements Matcher<MyDependent, MyPrimary> {
-  // your implementation
+        implements Matcher<MyDependent, MyPrimary> {
+    // your implementation
 
-  public Result<MyDependent> match(MyDependent actualResource, MyPrimary primary,
-      Context<MyPrimary> context) {
-    return GenericKubernetesResourceMatcher.match(this, actualResource, primary, context, true);
-  }
+    public Result<MyDependent> match(MyDependent actualResource, MyPrimary primary,
+                                     Context<MyPrimary> context) {
+        return GenericKubernetesResourceMatcher.match(this, actualResource, primary, context, true);
+    }
 }
 ```
 
@@ -136,24 +138,24 @@ Deleted (or set to be garbage collected). The following example shows how to cre
 @KubernetesDependent(labelSelector = WebPageManagedDependentsReconciler.SELECTOR)
 class DeploymentDependentResource extends CRUDKubernetesDependentResource<Deployment, WebPage> {
 
-  public DeploymentDependentResource() {
-    super(Deployment.class);
-  }
-
-  @Override
-  protected Deployment desired(WebPage webPage, Context<WebPage> context) {
-    var deploymentName = deploymentName(webPage);
-    Deployment deployment = loadYaml(Deployment.class, getClass(), "deployment.yaml");
-    deployment.getMetadata().setName(deploymentName);
-    deployment.getMetadata().setNamespace(webPage.getMetadata().getNamespace());
-    deployment.getSpec().getSelector().getMatchLabels().put("app", deploymentName);
-
-    deployment.getSpec().getTemplate().getMetadata().getLabels()
-        .put("app", deploymentName);
-    deployment.getSpec().getTemplate().getSpec().getVolumes().get(0)
-        .setConfigMap(new ConfigMapVolumeSourceBuilder().withName(configMapName(webPage)).build());
-    return deployment;
-  }
+    public DeploymentDependentResource() {
+        super(Deployment.class);
+    }
+
+    @Override
+    protected Deployment desired(WebPage webPage, Context<WebPage> context) {
+        var deploymentName = deploymentName(webPage);
+        Deployment deployment = loadYaml(Deployment.class, getClass(), "deployment.yaml");
+        deployment.getMetadata().setName(deploymentName);
+        deployment.getMetadata().setNamespace(webPage.getMetadata().getNamespace());
+        deployment.getSpec().getSelector().getMatchLabels().put("app", deploymentName);
+
+        deployment.getSpec().getTemplate().getMetadata().getLabels()
+                .put("app", deploymentName);
+        deployment.getSpec().getTemplate().getSpec().getVolumes().get(0)
+                .setConfigMap(new ConfigMapVolumeSourceBuilder().withName(configMapName(webPage)).build());
+        return deployment;
+    }
 }
 ```
 
@@ -189,25 +191,25 @@ instances are managed by JOSDK, an example of which can be seen below:
 ```java
 
 @ControllerConfiguration(
-    labelSelector = SELECTOR,
-    dependents = {
-        @Dependent(type = ConfigMapDependentResource.class),
-        @Dependent(type = DeploymentDependentResource.class),
-        @Dependent(type = ServiceDependentResource.class)
-    })
+        labelSelector = SELECTOR,
+        dependents = {
+                @Dependent(type = ConfigMapDependentResource.class),
+                @Dependent(type = DeploymentDependentResource.class),
+                @Dependent(type = ServiceDependentResource.class)
+        })
 public class WebPageManagedDependentsReconciler
-    implements Reconciler<WebPage>, ErrorStatusHandler<WebPage> {
+        implements Reconciler<WebPage>, ErrorStatusHandler<WebPage> {
 
-  // omitted code
+    // omitted code
 
-  @Override
-  public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> context) {
+    @Override
+    public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> context) {
 
-    final var name = context.getSecondaryResource(ConfigMap.class).orElseThrow()
-        .getMetadata().getName();
-    webPage.setStatus(createStatus(name));
-    return UpdateControl.patchStatus(webPage);
-  }
+        final var name = context.getSecondaryResource(ConfigMap.class).orElseThrow()
+                .getMetadata().getName();
+        webPage.setStatus(createStatus(name));
+        return UpdateControl.patchStatus(webPage);
+    }
 
 }
 ```
@@ -222,104 +224,11 @@ It is also possible to wire dependent resources programmatically. In practice th
 developer is responsible for initializing and managing the dependent resources as well as calling
 their `reconcile` method. However, this makes it possible for developers to fully customize the
 reconciliation process. Standalone dependent resources should be used in cases when the managed use
-case does not fit.
-
-Note that [Workflows](https://javaoperatorsdk.io/docs/workflows) also can be invoked from standalone
-resources.
-
-The following sample is similar to the one above, simply performing additional checks, and
-conditionally creating an `Ingress`:
-
-```java
-
-@ControllerConfiguration
-public class WebPageStandaloneDependentsReconciler
-    implements Reconciler<WebPage>, ErrorStatusHandler<WebPage>,
-    EventSourceInitializer<WebPage> {
-
-  private KubernetesDependentResource<ConfigMap, WebPage> configMapDR;
-  private KubernetesDependentResource<Deployment, WebPage> deploymentDR;
-  private KubernetesDependentResource<Service, WebPage> serviceDR;
-  private KubernetesDependentResource<Service, WebPage> ingressDR;
-
-  public WebPageStandaloneDependentsReconciler(KubernetesClient kubernetesClient) {
-    // 1.
-    createDependentResources(kubernetesClient);
-  }
-
-  @Override
-  public List<EventSource> prepareEventSources(EventSourceContext<WebPage> context) {
-    // 2.  
-    return List.of(
-        configMapDR.initEventSource(context),
-        deploymentDR.initEventSource(context),
-        serviceDR.initEventSource(context));
-  }
-
-  @Override
-  public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> context) {
-
-    // 3.
-    if (!isValidHtml(webPage.getHtml())) {
-      return UpdateControl.patchStatus(setInvalidHtmlErrorMessage(webPage));
-    }
-
-    // 4.  
-    configMapDR.reconcile(webPage, context);
-    deploymentDR.reconcile(webPage, context);
-    serviceDR.reconcile(webPage, context);
-
-    // 5.
-    if (Boolean.TRUE.equals(webPage.getSpec().getExposed())) {
-      ingressDR.reconcile(webPage, context);
-    } else {
-      ingressDR.delete(webPage, context);
-    }
+case does not fit. You can, of course, also use [Workflows](https://javaoperatorsdk.io/docs/workflows) when managing
+resources programmatically.
 
-    // 6.
-    webPage.setStatus(
-        createStatus(configMapDR.getResource(webPage).orElseThrow().getMetadata().getName()));
-    return UpdateControl.patchStatus(webPage);
-  }
-
-  private void createDependentResources(KubernetesClient client) {
-    this.configMapDR = new ConfigMapDependentResource();
-    this.deploymentDR = new DeploymentDependentResource();
-    this.serviceDR = new ServiceDependentResource();
-    this.ingressDR = new IngressDependentResource();
-
-    Arrays.asList(configMapDR, deploymentDR, serviceDR, ingressDR).forEach(dr -> {
-      dr.setKubernetesClient(client);
-      dr.configureWith(new KubernetesDependentResourceConfig()
-          .setLabelSelector(DEPENDENT_RESOURCE_LABEL_SELECTOR));
-    });
-  }
-
-  // omitted code
-}
-```
-
-There are multiple things happening here:
-
-1. Dependent resources are explicitly created and can be access later by reference.
-2. Event sources are produced by the dependent resources, but needs to be explicitly registered in
-   this case by implementing
-   the [`EventSourceInitializer`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/EventSourceInitializer.java)
-   interface.
-3. The input html is validated, and error message is set in case it is invalid.
-4. Reconciliation of dependent resources is called explicitly, but here the workflow
-   customization is fully in the hand of the developer.
-5. An `Ingress` is created but only in case `exposed` flag set to true on custom resource. Tries to
-   delete it if not.
-6. Status is set in a different way, this is just an alternative way to show, that the actual state
-   can be read using the reference. This could be written in a same way as in the managed example.
-
-See the full source code of
-sample [here](https://github.com/operator-framework/java-operator-sdk/blob/main/sample-operators/webpage/src/main/java/io/javaoperatorsdk/operator/sample/WebPageStandaloneDependentsReconciler.java)
-.
-
-Note also the Workflows feature makes it possible to also support this conditional creation use
-case in managed dependent resources.
+You can see a commented example of how to do
+so [here](https://github.com/operator-framework/java-operator-sdk/blob/main/sample-operators/webpage/src/main/java/io/javaoperatorsdk/operator/sample/WebPageStandaloneDependentsReconciler.java).
 
 ## Creating/Updating Kubernetes Resources
 
@@ -352,17 +261,17 @@ Since SSA is a complex feature, JOSDK implements a feature flag allowing users t
 these implementations. See
 in [ConfigurationService](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L332-L358).
 
-It is, however, important to note that these implementations are default, generic 
-implementations that the framework can provide expected behavior out of the box. In many 
-situations, these will work just fine but it is also possible to provide matching algorithms 
+It is, however, important to note that these implementations are default, generic
+implementations that the framework can provide expected behavior out of the box. In many
+situations, these will work just fine but it is also possible to provide matching algorithms
 optimized for specific use cases. This is easily done by simply overriding
-the `match(...)` [method](https://github.com/java-operator-sdk/java-operator-sdk/blob/e16559fd41bbb8bef6ce9d1f47bffa212a941b09/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/kubernetes/KubernetesDependentResource.java#L156-L156). 
+the `match(...)` [method](https://github.com/java-operator-sdk/java-operator-sdk/blob/e16559fd41bbb8bef6ce9d1f47bffa212a941b09/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/kubernetes/KubernetesDependentResource.java#L156-L156).
 
-It is also possible to bypass the matching logic altogether to simply rely on the server-side 
+It is also possible to bypass the matching logic altogether to simply rely on the server-side
 apply mechanism if always sending potentially unchanged resources to the cluster is not an issue.
 JOSDK's matching mechanism allows to spare some potentially useless calls to the Kubernetes API
-server. To bypass the matching feature completely, simply override the `match` method to always 
-return `false`, thus telling JOSDK that the actual state never matches the desired one, making 
+server. To bypass the matching feature completely, simply override the `match` method to always
+return `false`, thus telling JOSDK that the actual state never matches the desired one, making
 it always update the resources using SSA.
 
 WARNING: Older versions of Kubernetes before 1.25 would create an additional resource version for every SSA update
@@ -389,20 +298,25 @@ tests [here](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/op
 
 When dealing with multiple dependent resources of same type, the dependent resource implementation
 needs to know which specific resource should be targeted when reconciling a given dependent
-resource, since there will be multiple instances of that type which could possibly be used, each
-associated with the same primary resource. In order to do this, JOSDK relies on the
-[resource discriminator](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceDiscriminator.java)
-concept. Resource discriminators uniquely identify the target resource of a dependent resource.
-In the managed Kubernetes dependent resources case, the discriminator can be declaratively set
-using the `@KubernetesDependent` annotation:
-
-```java
-
-@KubernetesDependent(resourceDiscriminator = ConfigMap1Discriminator.class)
-public class MultipleManagedDependentResourceConfigMap1 {
-//...
-}
-```
+resource, since there could be multiple instances of that type which could possibly be used, each
+associated with the same primary resource. In this situation, JOSDK automatically selects the appropriate secondary
+resource matching the desired state associated with the primary resource. This makes sense because the desired
+state computation already needs to be able to discriminate among multiple related secondary resources to tell JOSDK how
+they should be reconciled.
+
+There might be casees, though, where it might be problematic to call the `desired` method several times (for example, because it is costly to do so), it is always possible to override this automated discrimination using several means:
+
+- Implement your own `getSecondaryResource` method on your `DependentResource` implementation from scratch.
+- Override the `selectManagedSecondaryResource` method, if your `DependentResource` extends `AbstractDependentResource`.
+  This should be relatively simple to override this method to optimize the matching to your needs. You can see an
+  example of such an implementation in
+  the [`ExternalWithStateDependentResource`](https://github.com/operator-framework/java-operator-sdk/blob/6cd0f884a7c9b60c81bd2d52da54adbd64d6e118/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/externalstate/ExternalWithStateDependentResource.java#L43-L49)
+  class.
+- Override the `managedSecondaryResourceID` method, if your `DependentResource` extends `KubernetesDependentResource`,
+  where it's very often possible to easily determine the `ResourceID` of the secondary resource. This would probably be
+  the easiest solution if you're working with Kubernetes resources.
+
+### Sharing an Event Source Between Dependent Resources
 
 Dependent resources usually also provide event sources. When dealing with multiple dependents of
 the same type, one needs to decide whether these dependent resources should track the same
@@ -418,10 +332,10 @@ would look as follows:
    useEventSourceWithName = "configMapSource")
 ```
 
-A sample is provided as an integration test both
-for [managed](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/MultipleManagedDependentSameTypeIT.java)
-and
-for [standalone](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/MultipleDependentResourceIT.java)
+A sample is provided as an integration test both:
+for [managed](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/MultipleManagedDependentNoDiscriminatorIT.java)
+
+For [standalone](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/MultipleDependentResourceIT.java)
 cases.
 
 ## Bulk Dependent Resources
@@ -484,15 +398,18 @@ also be created, one per dependent resource.
 See [integration test](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/ExternalStateBulkIT.java)
 as a sample.
 
-
 ## GenericKubernetesResource based Dependent Resources
 
-In rare circumstances resource handling where there is no class representation or just typeless handling might be needed.
-Fabric8 Client provides [GenericKubernetesResource](https://github.com/fabric8io/kubernetes-client/blob/main/doc/CHEATSHEET.md#resource-typeless-api)
-to support that. 
+In rare circumstances resource handling where there is no class representation or just typeless handling might be
+needed.
+Fabric8 Client
+provides [GenericKubernetesResource](https://github.com/fabric8io/kubernetes-client/blob/main/doc/CHEATSHEET.md#resource-typeless-api)
+to support that.
 
-For dependent resource this is supported by [GenericKubernetesDependentResource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/kubernetes/GenericKubernetesDependentResource.java#L8-L8)
-. See samples [here](https://github.com/java-operator-sdk/java-operator-sdk/tree/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/generickubernetesresource).
+For dependent resource this is supported
+by [GenericKubernetesDependentResource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/kubernetes/GenericKubernetesDependentResource.java#L8-L8)
+. See
+samples [here](https://github.com/java-operator-sdk/java-operator-sdk/tree/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/generickubernetesresource).
 
 ## Other Dependent Resource Features
 

docsy/content/en/docs/features/_index.md

@@ -3,6 +3,8 @@ title: Features
 weight: 50
 ---
 
+# Features
+
 The Java Operator SDK (JOSDK) is a high level framework and related tooling aimed at
 facilitating the implementation of Kubernetes operators. The features are by default following
 the best practices in an opinionated way. However, feature flags and other configuration options
@@ -62,7 +64,8 @@ and/or re-schedule a reconciliation with a desired time delay:
   @Override
   public UpdateControl<MyCustomResource> reconcile(
      EventSourceTestCustomResource resource, Context context) {
-    ...
+    // omitted code
+    
     return UpdateControl.patchStatus(resource).rescheduleAfter(10, TimeUnit.SECONDS);
   }
 ```
@@ -73,7 +76,8 @@ without an update:
   @Override
   public UpdateControl<MyCustomResource> reconcile(
      EventSourceTestCustomResource resource, Context context) {
-    ...
+    // omitted code
+    
     return UpdateControl.<MyCustomResource>noUpdate().rescheduleAfter(10, TimeUnit.SECONDS);
   }
 ```
@@ -85,17 +89,31 @@ Those are the typical use cases of resource updates, however in some cases there
 the controller wants to update the resource itself (for example to add annotations) or not perform
 any updates, which is also supported.
 
-It is also possible to update both the status and the resource with the
-`updateResourceAndStatus` method. In this case, the resource is updated first followed by the
-status, using two separate requests to the Kubernetes API.
-
-You should always state your intent using `UpdateControl` and let the SDK deal with the actual
-updates instead of performing these updates yourself using the actual Kubernetes client so that
-the SDK can update its internal state accordingly.
-
-Resource updates are protected using optimistic version control, to make sure that other updates
-that might have occurred in the mean time on the server are not overwritten. This is ensured by
-setting the `resourceVersion` field on the processed resources.
+It is also possible to update both the status and the resource with the `patchResourceAndStatus` method. In this case,
+the resource is updated first followed by the status, using two separate requests to the Kubernetes API.
+
+From v5 `UpdateControl` only supports patching the resources, by default
+using [Server Side Apply (SSA)](https://kubernetes.io/docs/reference/using-api/server-side-apply/).
+It is important to understand how SSA works in Kubernetes. Mainly, resources applied using SSA
+should contain only the fields identifying the resource and those the user is interested in (a 'fully specified intent'
+in Kubernetes parlance), thus usually using a resource created from scratch, see
+[sample](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/patchresourcewithssa/PatchResourceWithSSAReconciler.java#L18-L22).
+To contrast, see the same sample, this time [without SSA](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/patchresourceandstatusnossa/PatchResourceAndStatusNoSSAReconciler.java#L16-L16).
+
+Non-SSA based patch is still supported.  
+You can control whether or not to use SSA
+using [`ConfigurationServcice.useSSAToPatchPrimaryResource()`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L385-L385)
+and the related `ConfigurationServiceOverrider.withUseSSAToPatchPrimaryResource` method.
+Related integration test can be
+found [here](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/patchresourceandstatusnossa/PatchResourceAndStatusNoSSAReconciler.java).
+
+Handling resources directly using the client, instead of delegating these updates operations to JOSDK by returning
+an `UpdateControl` at the end of your reconciliation, should work appropriately. However, we do recommend to
+use `UpdateControl` instead since JOSDK makes sure that the operations are handled properly, since there are subtleties
+to be aware of. For example, if you are using a finalizer, JOSDK makes sure to include it in your fully specified intent
+so that it is not unintentionally removed from the resource (which would happen if you omit it, since your controller is
+the designated manager for that field and Kubernetes interprets the finalizer being gone from the specified intent as a
+request for removal).
 
 [`DeleteControl`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DeleteControl.java)
 typically instructs the framework to remove the finalizer after the dependent
@@ -104,7 +122,8 @@ resource are cleaned up in `cleanup` implementation.
 ```java
 
 public DeleteControl cleanup(MyCustomResource customResource,Context context){
-        ...
+        // omitted code
+    
         return DeleteControl.defaultDelete();
         }
 
@@ -163,56 +182,7 @@ You can specify the name of the finalizer to use for your `Reconciler` using the
 [`@ControllerConfiguration`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ControllerConfiguration.java)
 annotation. If you do not specify a finalizer name, one will be automatically generated for you.
 
-## Automatic Observed Generation Handling
-
-Having an `.observedGeneration` value on your resources' status is a best practice to
-indicate the last generation of the resource which was successfully reconciled by the controller.
-This helps users / administrators diagnose potential issues.
-
-In order to have this feature working:
-
-- the **status class** (not the resource itself) 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)
-  interface. See also
-  the [`ObservedGenerationAwareStatus`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/ObservedGenerationAwareStatus.java)
-  convenience implementation that you can extend in your own status class implementations.
-- The other condition is that the `CustomResource.getStatus()` method should not return `null`.
-  So the status should be instantiated when the object is returned using the `UpdateControl`.
-
-If these conditions are fulfilled and generation awareness is activated, the observed generation
-is automatically set by the framework after the `reconcile` method is called. Note that the
-observed generation is also updated even when `UpdateControl.noUpdate()` is returned from the
-reconciler. See this feature at work in
-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
-public class WebPageStatus extends ObservedGenerationAwareStatus {
-
-   private String htmlConfigMap;
-  
-  ...
-}
-```
-
-Initializing status automatically on custom resource could be done by overriding the `initStatus` method
-of `CustomResource`. However, this is NOT advised, since breaks the status patching if you use:
-`UpdateControl.patchStatus`. See
-also [javadocs](https://github.com/java-operator-sdk/java-operator-sdk/blob/3994f5ffc1fb000af81aa198abf72a5f75fd3e97/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/UpdateControl.java#L41-L42)
-.
-
-```java 
-@Group("sample.javaoperatorsdk")
-@Version("v1")
-public class WebPage extends CustomResource<WebPageSpec, WebPageStatus>
-    implements Namespaced {
-
-  @Override
-  protected WebPageStatus initStatus() {
-    return new WebPageStatus();
-  }
-}
-```
+From v5 by default finalizer is added using Served Side Apply. See also UpdateControl in docs.
 
 ## Generation Awareness and Event Filtering
 
@@ -231,9 +201,7 @@ To turn off this feature, set `generationAwareEventProcessing` to `false` for th
 ## Support for Well Known (non-custom) Kubernetes Resources
 
 A Controller can be registered for a non-custom resource, so well known Kubernetes resources like (
-`Ingress`, `Deployment`,...). Note that automatic observed generation handling is not supported
-for these resources, though, in this case, the handling of the observed generation is probably
-handled by the primary controller.
+`Ingress`, `Deployment`,...).
 
 See
 the [integration test](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/deployment/DeploymentReconciler.java)
@@ -243,11 +211,12 @@ for reconciling deployments.
 public class DeploymentReconciler
     implements Reconciler<Deployment>, TestExecutionInfoProvider {
 
-  @Override
-  public UpdateControl<Deployment> reconcile(
-      Deployment resource, Context context) {
-  ...
-  }
+    @Override
+    public UpdateControl<Deployment> reconcile(
+            Deployment resource, Context context) {
+        // omitted code
+    }
+}
 ```
 
 ## Max Interval Between Reconciliations
@@ -265,6 +234,7 @@ standard annotation:
 @ControllerConfiguration(maxReconciliationInterval = @MaxReconciliationInterval(
                 interval = 50,
                 timeUnit = TimeUnit.MILLISECONDS))
+public class MyReconciler implements Reconciler<HasMetadata> {}
 ```
 
 The event is not propagated at a fixed rate, rather it's scheduled after each reconciliation. So the
@@ -487,9 +457,8 @@ related [method](https://github.com/java-operator-sdk/java-operator-sdk/blob/mai
 
 ### Registering Event Sources
 
-To register event sources, your `Reconciler` has to implement the
-[`EventSourceInitializer`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/EventSourceInitializer.java)
-interface and initialize a list of event sources to register. One way to see this in action is
+To register event sources, your `Reconciler` has to override the `prepareEventSources` and return
+list of event sources to register. One way to see this in action is
 to look at the
 [tomcat example](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/sample-operators/tomcat-operator/src/main/java/io/javaoperatorsdk/operator/sample/WebappReconciler.java)
 (irrelevant details omitted):
@@ -499,8 +468,9 @@ to look at the
 @ControllerConfiguration
 public class WebappReconciler
         implements Reconciler<Webapp>, Cleaner<Webapp>, EventSourceInitializer<Webapp> {
-
-    @Override
+   // ommitted code
+    
+   @Override
     public Map<String, EventSource> prepareEventSources(EventSourceContext<Webapp> context) {
         InformerConfiguration<Tomcat> configuration =
                 InformerConfiguration.from(Tomcat.class, context)
@@ -512,7 +482,7 @@ public class WebappReconciler
         return EventSourceInitializer
                 .nameEventSources(new InformerEventSource<>(configuration, context));
     }
-    ...
+  
 }
 ```
 
@@ -656,15 +626,15 @@ registering an associated `Informer` and then calling the `changeNamespaces` met
 
 ```java
 
-public static void main(String[]args)throws IOException{
-        KubernetesClient client=new DefaultKubernetesClient();
-        Operator operator=new Operator(client);
-        RegisteredController registeredController=operator.register(new WebPageReconciler(client));
-        operator.installShutdownHook();
-        operator.start();
+public static void main(String[] args) {
+    KubernetesClient client = new DefaultKubernetesClient();
+    Operator operator = new Operator(client);
+    RegisteredController registeredController = operator.register(new WebPageReconciler(client));
+    operator.installShutdownHook();
+    operator.start();
 
-        // call registeredController further while operator is running
-        }
+    // call registeredController further while operator is running
+}
 
 ```
 
@@ -676,8 +646,7 @@ configured appropriately so that the `followControllerNamespaceChanges` method r
 ```java
 
 @ControllerConfiguration
-public class MyReconciler
-        implements Reconciler<TestCustomResource>, EventSourceInitializer<TestCustomResource> {
+public class MyReconciler implements Reconciler<TestCustomResource> {
 
    @Override
    public Map<String, EventSource> prepareEventSources(
@@ -688,7 +657,7 @@ public class MyReconciler
             .withNamespacesInheritedFromController(context)
             .build(), context);
 
-    return EventSourceInitializer.nameEventSources(configMapES);
+    return EventSourceUtils.nameEventSources(configMapES);
   }
 
 }
@@ -767,8 +736,8 @@ You can use a different implementation by overriding the default one provided by
 follows:
 
 ```java
-Metrics metrics= …;
-Operator operator = new Operator(client, o -> o.withMetrics());
+Metrics metrics; // initialize your metrics implementation
+Operator operator = new Operator(client, o -> o.withMetrics(metrics));
 ```
 
 ### Micrometer implementation
@@ -784,8 +753,8 @@ To create a `MicrometerMetrics` implementation that behaves how it has historica
 instance via:
 
 ```java
-MeterRegistry registry= …;
-Metrics metrics=new MicrometerMetrics(registry)
+MeterRegistry registry; // initialize your registry implementation
+Metrics metrics = new MicrometerMetrics(registry);
 ```
 
 Note, however, that this constructor is deprecated and we encourage you to use the factory methods instead, which either
@@ -801,7 +770,7 @@ basis, deleting the associated meters after 5 seconds when a resource is deleted
 MicrometerMetrics.newPerResourceCollectingMicrometerMetricsBuilder(registry)
         .withCleanUpDelayInSeconds(5)
         .withCleaningThreadNumber(2)
-        .build()
+        .build();
 ```
 
 ### Operator SDK metrics

docsy/content/en/docs/migration/v5-0-migration.md

@@ -0,0 +1,63 @@
+---
+title: Migrating from v4.7 to v5.0
+description: Migrating from v4.7 to v5.0
+---
+
+# Migrating from v4.7 to v5.0
+
+## API Tweaks
+
+1. [Result of managed dependent resources](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/dependent/managed/ManagedDependentResourceContext.java#L55-L57)
+   is not `Optional` anymore. In case you use this result, simply use the result
+   objects directly.
+2. `EventSourceInitializer` is not a separate interface anymore. It is part of the `Reconciler` interface with a
+   default implementation. You can simply remove this interface from your reconciler. The
+   [`EventSourceUtils`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/EventSourceUtils.java#L11-L11)
+   now contains all the utility methods used for event sources naming that were previously defined in
+   the `EventSourceInitializer` interface.
+3. Similarly, the `EventSourceProvider` interface has been remove, replaced by explicit initialization of the associated
+   event source on `DependentResource` via the `
+   Optional<? extends EventSource<R, P>> eventSource(EventSourceContext<P> eventSourceContext)` method.
+4. Event sources are now explicitly named (via the `name` method of the `EventSource` interface). Built-in event sources
+   implementation have been updated to allow you to specify a name when instantiating them. If you don't provide a name
+   for your `EventSource` implementation (for example, by using its default, no-arg constructor), one will be
+   automatically generated. This simplifies the API to define event source to
+   `List<EventSource> prepareEventSources(EventSourceContext<P> context)`.
+   !!! IMPORTANT !!!
+   If you use dynamic registration of event sources, be sure to name your event sources explicitly as letting JOSDK name
+   them automatically might result in duplicated event sources being registered as JOSDK relies on the name to identify
+   event sources and concurrent, dynamic registration might lead to identical event sources having different generated
+   names, thus leading JOSDK to consider them as different and hence, register them multiple times.
+5. Updates through `UpdateControl` now
+   use [Server Side Apply (SSA)](https://kubernetes.io/docs/reference/using-api/server-side-apply/) by default to add
+   the finalizer and for all
+   the patch operations in `UpdateControl`. The update operations were removed. If you do not wish to use SSA, you can
+   deactivate the feature using `ConfigurationService.useSSAToPatchPrimaryResource` and
+   related `ConfigurationServiceOverrider.withUseSSAToPatchPrimaryResource`.
+
+   !!! IMPORTANT !!!
+
+   See known issues with migration from non-SSA to SSA based status updates here:
+   [integration test](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/StatusPatchSSAMigrationIT.java#L71-L82)
+   where it is demonstrated. Also, the related part of
+   a [workaround](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/StatusPatchSSAMigrationIT.java#L110-L116).
+
+6. `ManagedDependentResourceContext` has been renamed to `ManagedWorkflowAndDependentResourceContext` and is accessed
+   via the accordingly renamed `managedWorkflowAndDependentResourceContext` method.
+7. `ResourceDiscriminator` was removed. In most of the cases you can just delete the discriminator, everything should
+   work without it by default. To optimize and handle special cases see the relevant section
+   in [Dependent Resource documentation](/docs/dependent-resources#multiple-dependent-resources-of-same-type).
+8. `ConfigurationService.getTerminationTimeoutSeconds` and associated overriding mechanism have been removed,
+   use `Operator.stop(Duration)` instead.
+9. `Operator.installShutdownHook()` has been removed, use `Operator.installShutdownHook(Duration)` instead
+10. Automated observed generation handling feature was removed (`ObservedGenerationAware` interface
+    and `ObservedGenerationAwareStatus` class were deleted). Manually handling observed generation is fairly easy to do
+    in your reconciler, however, it cannot be done automatically when using SSA. We therefore removed the feature since
+    it would have been confusing to have a different behavior for SSA and non-SSA cases. For an example of how to do
+    observed generation handling manually in your reconciler, see
+    [this sample](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/manualobservedgeneration/ManualObservedGenerationReconciler.java).
+11. `BulkDependentResource` now supports [read-only mode](https://github.com/operator-framework/java-operator-sdk/issues/2233).
+    This also means, that `BulkDependentResource` now does not automatically implement `Creator` and `Deleter` as before.
+    Make sure to implement those interfaces in your bulk dependent resources. You can use also the new helper interface, the
+    [`CRUDBulkDependentResource`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/CRUDBulkDependentResource.java)
+    what also implement `BulkUpdater` interface.

docsy/content/en/docs/workflows/_index.md

@@ -41,10 +41,10 @@ reconciliation process.
   condition holds or not. This is a very useful feature when your operator needs to handle different flavors of the
   platform (e.g. OpenShift vs plain Kubernetes) and/or change its behavior based on the availability of optional
   resources / features (e.g. CertManager, a specific Ingress controller, etc.).
- 
-  Activation condition is semi-experimental at the moment, and it has its limitations. 
-  For example event sources cannot be shared between multiple managed dependent resources which use activation condition. 
-  The intention is to further improve and explore the possibilities with this approach.  
+
+  Activation condition is semi-experimental at the moment, and it has its limitations.
+  For example event sources cannot be shared between multiple managed dependent resources which use activation condition.
+  The intention is to further improve and explore the possibilities with this approach.
 
 ## Defining Workflows
 
@@ -120,7 +120,7 @@ page sample):
 @ControllerConfiguration(
     labelSelector = WebPageDependentsWorkflowReconciler.DEPENDENT_RESOURCE_LABEL_SELECTOR)
 public class WebPageDependentsWorkflowReconciler
-    implements Reconciler<WebPage>, ErrorStatusHandler<WebPage>, EventSourceInitializer<WebPage> {
+    implements Reconciler<WebPage>, ErrorStatusHandler<WebPage> {
 
   public static final String DEPENDENT_RESOURCE_LABEL_SELECTOR = "!low-level";
   private static final Logger log =
@@ -131,7 +131,7 @@ public class WebPageDependentsWorkflowReconciler
   private KubernetesDependentResource<Service, WebPage> serviceDR;
   private KubernetesDependentResource<Ingress, WebPage> ingressDR;
 
-  private Workflow<WebPage> workflow;
+  private final Workflow<WebPage> workflow;
 
   public WebPageDependentsWorkflowReconciler(KubernetesClient kubernetesClient) {
     initDependentResources(kubernetesClient);
@@ -145,7 +145,7 @@ public class WebPageDependentsWorkflowReconciler
 
   @Override
   public Map<String, EventSource> prepareEventSources(EventSourceContext<WebPage> context) {
-    return EventSourceInitializer.nameEventSources(
+    return EventSourceUtils.nameEventSources(
         configMapDR.initEventSource(context),
         deploymentDR.initEventSource(context),
         serviceDR.initEventSource(context),
@@ -198,7 +198,7 @@ demonstrated using examples:
 2. Root nodes, i.e. nodes in the graph that do not depend on other nodes are reconciled first,
    in a parallel manner.
 3. A DR is reconciled if it does not depend on any other DRs, or *ALL* the DRs it depends on are
-   reconciled and ready. If a DR defines a reconcile pre-condition and/or an activation condition, 
+   reconciled and ready. If a DR defines a reconcile pre-condition and/or an activation condition,
    then these condition must become `true` before the DR is reconciled.
 4. A DR is considered *ready* if it got successfully reconciled and any ready post-condition it
    might define is `true`.
@@ -328,10 +328,38 @@ provides such a delete post-condition implementation in the form of
 
 Also, check usage in an [integration test](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/manageddependentdeletecondition/ManagedDependentDefaultDeleteConditionReconciler.java).
 
-In such cases the Kubernetes Dependent Resource should extend `CRUDNoGCKubernetesDependentResource` 
+In such cases the Kubernetes Dependent Resource should extend `CRUDNoGCKubernetesDependentResource`
 and NOT `CRUDKubernetesDependentResource` since otherwise the Kubernetes Garbage Collector would delete the resources.
 In other words if a Kubernetes Dependent Resource depends on another dependent resource, it should not implement
-`GargageCollected` interface, otherwise the deletion order won't be guaranteed. 
+`GargageCollected` interface, otherwise the deletion order won't be guaranteed.
+
+
+## Explicit Managed Workflow Invocation
+
+Managed workflows, i.e. ones that are declared via annotations and therefore completely managed by JOSDK, are reconciled
+before the primary resource. Each dependent resource that can be reconciled (according to the workflow configuration)
+will therefore be reconciled before the primary reconciler is called to reconcile the primary resource. There are,
+however, situations where it would be be useful to perform additional steps before the workflow is reconciled, for
+example to validate the current state, execute arbitrary logic or even skip reconciliation altogether. Explicit
+invocation of managed workflow was therefore introduced to solve these issues.
+
+To use this feature, you need to set the `explicitInvocation` field to `true` on the `@Workflow` annotation and then
+call the `reconcileManagedWorkflow` method from the `
+ManagedWorkflowAndDependentResourceContext` retrieved from the reconciliation `Context` provided as part of your primary
+resource reconciler `reconcile` method arguments.
+
+See
+related [integration test](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/WorkflowExplicitInvocationIT.java)
+for more details.
+
+For `cleanup`, if the `Cleaner` interface is implemented, the `cleanupManageWorkflow()` needs to be called explicitly.
+However, if `Cleaner` interface is not implemented, it will be called implicitly.
+See
+related [integration test](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/WorkflowExplicitCleanupIT.java).
+
+While nothing prevents calling the workflow multiple times in a reconciler, it isn't typical or even recommended to do
+so. Conversely, if explicit invocation is requested but `reconcileManagedWorkflow` is not called in the primary resource
+reconciler, the workflow won't be reconciled at all.
 
 ## Notes and Caveats