update documentation

Author: cbarbian-sap

pkg/component/types.go

@@ -14,7 +14,7 @@ import (
 
 // Component is the central interface that component operators have to implement.
 // Besides being a conroller-runtime client.Object, the implementing type has to expose accessor
-// methods for the deployment's target namespace and name, and for the components's spec and status.
+// methods for the deployment's target namespace and name, and for the components's spec and status,
 // via methods GetSpec() and GetStatus().
 type Component interface {
 	client.Object
@@ -26,10 +26,10 @@ type Component interface {
 	// This is the value that will be passed to Generator.Generator() as name.
 	GetDeploymentName() string
 	// Return a read-only accessor to the component's spec.
-	// Which, as a consequence, obviously has to implement the types.Unstructurable interface.
+	// The returned value has to implement the types.Unstructurable interface.
 	GetSpec() types.Unstructurable
 	// Return a read-write (usually a pointer) accessor to the component's status,
-	// resp. to the corresponding sub-struct if the status extends component.Status.
+	// resp. to the corresponding substruct if the status extends component.Status.
 	GetStatus() *Status
 }
 

website/content/en/_index.html

@@ -6,12 +6,12 @@
 
 {{< blocks/cover title="component-operator-runtime" image_anchor="top" height="full" color="blue" >}}
 <div class="mx-auto">
-	<span class="font-weight-bold">A Framework for Kubernetes Component Operators</span><br><br><br>
-	<a class="btn btn-lg btn-primary mr-3 mb-4" href="{{< relref "/docs" >}}">
-		Documentation <i class="fas fa-arrow-alt-circle-right ml-2"></i>
-	</a>
-	<a class="btn btn-lg btn-secondary mr-3 mb-4" href="https://github.com/sap/component-operator-runtime">
-		Source Repository <i class="fab fa-github ml-2 "></i>
-	</a>
+  <span class="font-weight-bold">A Kubernetes Component Operator Framework</span><br><br><br>
+  <a class="btn btn-lg btn-primary mr-3 mb-4" href="{{< relref "/docs" >}}">
+    Documentation <i class="fas fa-arrow-alt-circle-right ml-2"></i>
+  </a>
+  <a class="btn btn-lg btn-secondary mr-3 mb-4" href="https://github.com/sap/component-operator-runtime">
+    Source Repository <i class="fab fa-github ml-2 "></i>
+  </a>
 </div>
 {{< /blocks/cover >}}

website/content/en/docs/_index.md

@@ -12,17 +12,16 @@ on such components that are or contain Kubernetes operators themselves.
 It can therefore serve as a starting point to develop [SAP Kyma module operators](https://github.com/kyma-project/template-operator), 
 but can also be used independently of Kyma.
 
-Regarding its mission statement, this project could be compared with the [Operator Lifecycle Manager (OLM)](https://olm.operatorframework.io/).
+Regarding its mission statement, this project can be compared with the [Operator Lifecycle Manager (OLM)](https://olm.operatorframework.io/).
 However, other than OLM, which follows a generic modelling approach, component-operator-runtime encourages the development of opinionated,
 concretely modeled, component-specific operators. This makes the resulting logic much more explicit, and also allows to react better on
 specific lifecycle needs of the managed component.
 
 Of course, components might equally be managed by using generic Kustomization or Helm chart deployers (such as provided by [ArgoCD](https://argoproj.github.io/) or [FluxCD](https://fluxcd.io/flux/)).
 However, these tools have certain weaknesses when it is about to deploy other operators, i.e. components which extend the Kubernetes API,
-e.g. by adding custom resource definitions, aggregated API servers, according controllers, and admission webhooks.
-For example these generic controllers tend to produce race conditions or dead locks upon first installation or deletion of the managed components.
+e.g. by adding custom resource definitions, aggregated API servers, according controllers, or admission webhooks.
+For example these generic solutions tend to produce race conditions or dead locks upon first installation or deletion of the managed components.
 This is where component-operator-runtime tries to act in a smarter and more robust way.
 
-This website provides the full technical documentation for the project, and can be
-used as a reference; if you feel that there's anything missing, please let us know
-or [raise a PR](https://github.com/sap/component-operator-runtime/pulls) to add it.
+If you want to report bugs, or request new features or enhancements, please [open an issue](https://github.com/sap/component-operator-runtime/issues)
+or [raise a pull request](https://github.com/sap/component-operator-runtime/pulls).

website/content/en/docs/concepts/_index.md

@@ -12,5 +12,6 @@ Usually (but not necessarily) the managed component contains one or multiple oth
 
 Other than existing tools addressing this case, such as the [Operator Lifecycle Manager (OLM)](https://olm.operatorframework.io/),
 this project proposes a more opinionated programming model. That is, the idea is to represent the managed component by an own custom resource type,
-which (usually) would be instantiated only once in the cluster. We feel encouraged to go this way, as many community projects (e.g. Istio), are following the same pattern.
-The component-operator-runtime framework now provides a generic controller, implemented as [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) reonciler, to facilitate the development of the according controller logic for the custom resource type modeling the component.
+which (usually) will be instantiated only once in the cluster. We feel encouraged to go this way, as many community projects are following the pattern of providing dedicated lifecycle operators.
+
+The component-operator-runtime framework plugs into the [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) SDK by implementing the controller-runtime `Reconciler` interface.

website/content/en/docs/concepts/dependents.md

@@ -17,7 +17,7 @@ To be more precise, assume for example, that the managed component contains some
 Then, if the component resource would be deleted, none of the component's dependent objects would be touched as long as there exist foreign
 instances of the managed custom resource definition in the cluster.
 
-In some special situations however, it is desirable to have more control on the lifecycle of the dependent objects.
+In some special situations, it is desirable to have even more control on the lifecycle of the dependent objects.
 To support such cases, the `Generator` implementation can set the following annotations in the manifests of the dependents:
 - `mycomponent-operator.mydomain.io/reconcile-policy`: defines how the object is reconciled; can be one of:
   - `on-object-change` (which is the default): the object will be reconciled whenever its generated manifest changes
@@ -26,8 +26,8 @@ To support such cases, the `Generator` implementation can set the following anno
 - `mycomponent-operator.mydomain.io/update-policy`: defines how the object (if existing) is updated; can be one of:
   - `default` (which is the default): a regular update (i.e. PUT) call will be made to the Kubernetes API server
   - `recreate`: if the object would be updated, it will be deleted and recreated instead
-- `mycomponent-operator.mydomain.io/order`: the order at which this object will be reconciled; dependents will be reconciled order by order; that is, objects of the same order will be deployed in the canonical order, and the controller will only proceed to the next order if all objects of previous orders are ready; specified orders can be negative or positive numbers between -32768 and 32767, objects with no explicit order set are treated as order 0.
-- `mycomponent-operator.mydomain.io/purge-order`: (optional) the order after which this object will be purged
+- `mycomponent-operator.mydomain.io/order`: the order at which this object will be reconciled; dependents will be reconciled order by order; that is, objects of the same order will be deployed in the canonical order, and the controller will only proceed to the next order if all objects of previous orders are ready; specified orders can be negative or positive numbers between -32768 and 32767, objects with no explicit order set are treated as if they would specify order 0.
+- `mycomponent-operator.mydomain.io/purge-order`: (optional) the order by which this object will be purged
 
 Note that, in the above paragraph, `mycomponent-operator.mydomain.io` has to be replaced with whatever was passed as `name` when calling `NewReconciler()`.
 

website/content/en/docs/concepts/reconciler.md

@@ -7,11 +7,11 @@ description: >
   Reconciliation logic for dependent objects
 ---
 
-Dependent objects are - by definition - the resources returned by the `Generate()` method of the provided resource generator.
+Dependent objects are - by definition - the resources returned by the `Generate()` method of the used resource generator.
 Whenever a component resource (that is, an instance of the component's custom resource type) is created, udpated, or deleted,
 the set of dependent object probably changes, and the cluster state has to be synchronized with that new declared state.
 
-This happens in the reconciler which is instantiated by calling the following constructor:
+This is the job of the reconciler which is instantiated by calling the following constructor:
 
 ```go
 package component
@@ -20,27 +20,31 @@ func NewReconciler[T Component](
   name              string,
   client            client.Client,
   discoveryClient   discovery.DiscoveryInterface,
-  recorder          record.EventRecorder,
+  eventRecorder     record.EventRecorder,
   scheme            *runtime.Scheme,
   resourceGenerator manifests.Generator
 ) *Reconciler[T]
 ```
 
-The passed type parameter `T Component` would be the concrete runtime type of the custom resource type. Furthermore,
+The passed type parameter `T Component` is the concrete runtime type of the component's custom resource type. Furthermore,
 - `name` is supposed to be a unique name (typically a DNS name) uniquely identifying this component operator in the cluster; ìt will be used in annotations, labels, for leader election, ...
-- `client` is a controller-runtime `client.Client`, having all the needed privileges to manage the dependent objects (probably it will have cluster-admin rights); the `client` must bypass informer caches for the following types:
+- `client`, `discoveryClient`, `eventRecorder` and `scheme` are deprecated and will be removed in future releases; they can be passed as `nil`
+- `resourceGenerator` is an implementation of the `Generator` interface, describing how the dependent objects are rendered from the component's spec.
+
+The object returned by `NewReconciler` implements the controller-runtime `Reconciler` interface, and can therefore be used as a drop-in
+in kubebuilder managed projects. After creation, the reconciler  has to be registered with the responsible controller-runtime manager instance by calling
+
+```go
+func (r *Reconciler[T]) SetupWithManager(mgr ctrl.Manager) error
+```
+
+The used manager `mgr` has to fulfill a few requirements:
+- its client must bypass informer caches for the following types:
   - the type `T` itself
   - the type `CustomResourceDefinition` from the `apiextensions.k8s.io/v1` group
   - the type `APIService` from the `apiregistration.k8s.io/v1` group
-- `discoveryClient` is a normal discovery client as provided by client-go
-- `recorder` is a standard event recorder
-- `scheme` is a `runtime.Scheme` which must recognize at least the following types:
+- its scheme must recognize at least the following types:
   - the types in the API group defined in this repository
   - the core group  (`v1`)
   - group `apiextensions.k8s.io/v1`
-  - group `apiregistration.k8s.io/v1`
-  - all concrete (i.e. non-unstructured) types returned by the `Generate()` method of the passed resource generator
-- `resourceGenerator` is an implementation of the `Generator` interface, describing how the dependent objects are rendered from the component's spec.
-
-The object returned by `NewReconciler` implements the controller-runtime `Reconciler` interface, and can therefore be used as a drop-in
-in kubebuilder managed projects.
+  - group `apiregistration.k8s.io/v1`.