improve documentation structure

Taskfile.yaml

@@ -5,4 +5,5 @@ includes:
     taskfile: hack/common/Taskfile_library.yaml
     flatten: true
     vars:
-      CODE_DIRS: '{{.ROOT_DIR}}/pkg/...'
+      CODE_DIRS: '{{.ROOT_DIR}}/pkg/...'
+      GENERATE_DOCS_INDEX: "true"

docs/README.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file, as it is auto-generated!-->
+# Documentation Index
+
+## Libraries
+
+- [Connecting to Kubernetes Clusters](libs/clusters.md)
+- [Collections](libs/collections.md)
+- [Controller Utility Functions](libs/controller.md)
+- [Custom Resource Definitions](libs/crds.md)
+- [Error Handling](libs/errors.md)
+- [Logging](libs/logging.md)
+- [Readiness Checks](libs/readiness.md)
+- [Kubernetes Resource Management](libs/resource.md)
+- [Kubernetes Resource Status Updating](libs/status.md)
+- [Testing](libs/testing.md)
+- [Thread Management](libs/threads.md)
+- [Webhooks](libs/webhooks.md)
+

docs/libs/.docnames

@@ -0,0 +1,3 @@
+{
+  "header": "Libraries"
+}

docs/libs/clusters.md

@@ -0,0 +1,23 @@
+# Connecting to Kubernetes Clusters
+
+Both, the `pkg/clientconfig` and the `pkg/clusters` package, provide library functions that help with constructing clients for interacting with kubernetes clusters. The former one is more low-level, while the latter one tries to hide most of the boilerplate coding related to client creation.
+
+## clientconfig
+
+The `pkg/clientconfig` package provides helper functions for creating Kubernetes clients using multiple connection methods. It defines a `Config` struct that encapsulates a Kubernetes API target and supports various authentication methods like kubeconfig file and a Service Account.
+
+### Noteworthy Functions
+
+- `GetRESTConfig` generates a `*rest.Config` for interacting with the Kubernetes API. It supports using a kubeconfig string, a kubeconfig file path, a secret reference that contains a kubeconfig file or a Service Account.
+- `GetClient` creates a client.Client for managing Kubernetes resources.
+
+## clusters
+
+The `pkg/clusters` package helps with loading kubeconfigs and creating clients for multiple clusters.
+```go
+foo := clusters.New("foo") // initializes a new cluster with id 'foo'
+foo.RegisterConfigPathFlag(cmd.Flags()) // adds a '--foo-cluster' flag to the flag set for passing in a kubeconfig path
+foo.InitializeRESTConfig() // loads the kubeconfig using the 'LoadKubeconfig' function from the 'controller' package
+foo.InitializeClient(myScheme) // initializes the 'Client' and 'Cluster' interfaces from the controller-runtime
+```
+You can then use the different getter methods for working with the cluster.

docs/libs/collections.md

@@ -0,0 +1,5 @@
+# Collections
+
+The `pkg/collections` package contains multiple interfaces for collections, modelled after the Java Collections Framework. The only actual implementation currently contained is a `LinkedList`, which fulfills the `List` and `Queue` interfaces.
+
+The package also contains further packages that contain some auxiliary functions for working with slices and maps in golang, e.g. for filtering.

docs/libs/controller.md

@@ -0,0 +1,11 @@
+# Controller Utility Functions
+
+The `pkg/controller` package contains useful functions for setting up and running k8s controllers.
+
+### Noteworthy Functions
+
+- `LoadKubeconfig` creates a REST config for accessing a k8s cluster. It can be used with a path to a kubeconfig file, or a directory containing files for a trust relationship. When called with an empty path, it returns the in-cluster configuration.
+  - See also the [`clusters`](#clusters) package, which uses this function internally, but provides some further tooling around it.
+- There are some functions useful for working with annotations and labels, e.g. `HasAnnotationWithValue` or `EnsureLabel`.
+- There are multiple predefined predicates to help with filtering reconciliation triggers in controllers, e.g. `HasAnnotationPredicate` or `DeletionTimestampChangedPredicate`.
+- The `K8sNameHash` function can be used to create a hash that can be used as a name for k8s resources.

docs/libs/crds.md

@@ -0,0 +1,3 @@
+# Custom Resource Definitions
+
+The `pkg/init/crds` package allows user to deploy CRDs from yaml files to a target cluster. It uses `embed.FS` to provide the files for deployment.

docs/libs/errors.md

@@ -0,0 +1,10 @@
+# Error Handling
+
+The `pkg/errors` package contains the `ReasonableError` type, which combines a normal `error` with a reason string. This is useful for errors that happen during reconciliation for updating the resource's status with a reason for the error later on.
+
+### Noteworthy Functions:
+
+- `WithReason(...)` can be used to wrap a standard error together with a reason into a `ReasonableError`.
+- `Errorf(...)` can be used to wrap an existing `ReasonableError` together with a new error, similarly to how `fmt.Errorf(...)` does it for standard errors.
+- `NewReasonableErrorList(...)` or `Join(...)` can be used to work with lists of errors. `Aggregate()` turns them into a single error again.
+

docs/libs/logging.md

@@ -0,0 +1,11 @@
+# Logging
+
+This package contains the logging library from the [Landscaper controller-utils module](https://github.com/gardener/landscaper/tree/master/controller-utils/pkg/logging).
+
+The library provides a wrapper around `logr.Logger`, exposing additional helper functions. The original `logr.Logger` can be retrieved by using the `Logr()` method. Also, it notices when multiple values are added to the logger with the same key - instead of simply overwriting the previous ones (like `logr.Logger` does it), it appends the key with a `_conflict(x)` suffix, where `x` is the number of times this conflict has occurred.
+
+### Noteworthy Functions
+
+- `GetLogger()` is a singleton-style getter function for a logger.
+- There are several `FromContext...` functions for retrieving a logger from a `context.Context` object.
+- `InitFlags(...)` can be used to add the configuration flags for this logger to a cobra `FlagSet`.

docs/libs/readiness.md

@@ -0,0 +1,26 @@
+# Readiness Checks
+
+The `pkg/readiness` package provides a simple way to check if a kubernetes resource is ready.
+The meaning of readiness depends on the resource type.
+
+### Examples
+
+```go
+deployment := &appsv1.Deployment{}
+err := r.Client.Get(ctx, types.NamespacedName{
+  Name:      "my-deployment",
+  Namespace: "my-namespace",
+}, deployment)
+
+if err != nil {
+  return err
+}
+
+readiness := readiness.CheckDeployment(deployment)
+
+if readiness.IsReady() {
+  fmt.Println("Deployment is ready")
+} else {
+  fmt.Printf("Deployment is not ready: %s\n", readiness.Message())
+}
+```

docs/libs/resource.md

@@ -0,0 +1,74 @@
+# Kubernetes Resource Management
+
+The `pkg/resource` package contains some useful functions for working with Kubernetes resources. The `Mutator` interface can be used to modify resources in a generic way. It is used by the `Mutate` function, which takes a resource and a mutator and applies the mutator to the resource.
+The package also contains convenience types for the most common resource types, e.g. `ConfigMap`, `Secret`, `ClusterRole`, `ClusterRoleBinding`, etc. These types implement the `Mutator` interface and can be used to modify the corresponding resources.
+
+### Examples
+
+Create or update a `ConfigMap`, a `ServiceAccount` and a `Deployment` using the `Mutator` interface:
+
+```go
+type myDeploymentMutator struct {
+}
+
+var _ resource.Mutator[*appsv1.Deployment] = &myDeploymentMutator{}
+
+func newDeploymentMutator() resources.Mutator[*appsv1.Deployment] {
+	return &MyDeploymentMutator{}
+}
+
+func (m *MyDeploymentMutator) String() string {
+	return "deployment default/test"
+}
+
+func (m *MyDeploymentMutator) Empty() *appsv1.Deployment {
+	return &appsv1.Deployment{
+		ObjectMeta: metav1.ObjectMeta{	
+			Name:      "test",
+			Namespace: "default",
+		},
+	}
+}
+
+func (m *MyDeploymentMutator) Mutate(deployment *appsv1.Deployment) error {
+	// create one container with an image
+	deployment.Spec.Template.Spec.Containers = []corev1.Container{
+		{
+			Name:  "test",
+			Image: "test-image:latest",
+		},
+	}
+	return nil
+}
+
+
+func ReconcileResources(ctx context.Context, client client.Client) error {
+	configMapResource := resource.NewConfigMap("my-configmap", "my-namespace", map[string]string{
+		"label1": "value1",
+		"label2": "value2",
+	}, nil)
+
+	serviceAccountResource := resource.NewServiceAccount("my-serviceaccount", "my-namespace", nil, nil)
+
+	myDeploymentMutator := newDeploymentMutator()
+
+	var err error
+
+	err = resources.CreateOrUpdateResource(ctx, client, configMapResource)
+	if err != nil {
+		return err
+	}
+
+	resources.CreateOrUpdateResource(ctx, client, serviceAccountResource)
+	if err != nil {
+		return err
+	}
+
+	err = resources.CreateOrUpdateResource(ctx, client, myDeploymentMutator)
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
+```