Eventing Manager Module Documentation (#226)

* Add the docs for contributor

* User documentation

* Add automatically generated CRD documentation

* Small improvements

* Replace link

* Apply review comments

* Add review comments

* Fix typo

* Add review comments

Makefile

@@ -89,6 +89,7 @@ help: ## Display this help.
 .PHONY: manifests
 manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
 	$(CONTROLLER_GEN) rbac:roleName=eventing-manager crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+	$(MAKE) crd-docs-gen
 
 .PHONY: generate
 generate: go-gen controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
@@ -314,3 +315,15 @@ e2e-eventing-peerauthentications:
 # e2e will run the whole suite of end-to-end tests for eventing-manager.
 .PHONY: e2e
 e2e: e2e-setup e2e-eventing-setup e2e-eventing e2e-cleanup
+
+TABLE_GEN ?= $(LOCALBIN)/table-gen
+TABLE_GEN_VERSION ?= v0.0.0-20230523174756-3dae9f177ffd
+
+.PHONY: tablegen
+tablegen: $(TABLE_GEN) ## Download table-gen locally if necessary.
+$(TABLE_GEN): $(LOCALBIN)
+	test -s $(TABLE_GEN) || GOBIN=$(LOCALBIN) go install github.com/kyma-project/kyma/hack/table-gen@$(TABLE_GEN_VERSION)
+
+.PHONY: crd-docs-gen
+crd-docs-gen: tablegen ## Generates CRD spec into docs folder
+	${TABLE_GEN} --crd-filename ./config/crd/bases/operator.kyma-project.io_eventings.yaml --md-filename ./docs/user/02-configuration.md

docs/contributor/development.md

@@ -0,0 +1,22 @@
+# Setup
+
+Eventing Manager follows the [Kubernetes operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) and is scaffolded using [Kubebuilder](https://book.kubebuilder.io/).
+
+Projects created by Kubebuilder contain a Makefile with tooling that must be locally executed before pushing (for example, `git push`) to the repository. Refer to [Governance](./governance.md) for further details.
+
+## Prerequisites
+
+- [Go](https://go.dev/)
+- [Docker](https://www.docker.com/)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/)
+- [Kubebuilder](https://book.kubebuilder.io/)
+- [kustomize](https://kustomize.io/)
+- [golangci-lint](https://golangci-lint.run/)
+
+## Available commands
+Commands are available for easier development and installation of Eventing Manager.
+To find out which commands are available and for some more details about each command, run:
+
+```bash
+make help
+```

docs/contributor/governance.md

@@ -0,0 +1,45 @@
+# Governance
+
+Some quality aspects are covered by automated verification, so you must execute tooling locally before a commit.
+This document guides you through the development flow.
+
+## Modifying the API definitions
+
+This project uses the [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html) tool provided by [Kubebuilder](https://book.kubebuilder.io/).
+To modify the API definitions, you must adapt the ["marker comments"](https://book.kubebuilder.io/reference/markers.html) in the Go code.
+
+Additionally, this project uses [validation markers](https://book.kubebuilder.io/reference/markers/crd-validation.html) to provide CRD validation and defaulting with [OpenAPI v3 schemas](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schemaObject).
+The rules are written using the [Common Expression Language](https://github.com/google/cel-spec).
+For further information and examples, look to the [Kubernetes documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation) of validation rules and the CEL [language definition](https://github.com/google/cel-spec/blob/v0.10.0/doc/langdef.md).
+
+After the modifications, run the following command to generate the new manifests, such as custom resources (CRs) and CustomResourceDefinitions (CRDs):
+```sh
+make manifests
+```
+
+If changes to the `runtime.Object` interface were made, the `DeepCopy` functions must be updated as well.
+The generation is controlled by [Kubebuilder markers](https://book.kubebuilder.io/reference/markers/object.html?highlight=deep#objectdeepcopy).
+```sh
+make generate
+```
+
+## Source code linting
+
+The quality of this project is ensured by source code linting using [golangci-lint](https://golangci-lint.run/).
+
+To fix common lint issues, run the following command:
+
+```sh
+make imports-local
+make fmt
+```
+
+To run thorough lint checking, execute the following command:
+
+```sh
+make lint-thoroughly
+```
+
+If necessary, lint warnings can be ignored. However, if this is desired you must provide a comment explaining the reason. Use the following format:
+
+`//no-lint:<LINTER> // <REASON>`

docs/contributor/installation.md

@@ -0,0 +1,164 @@
+# Installation and uninstallation
+
+There are several ways to install Eventing Manager.
+For development, you must run some make targets beforehand.
+For information about the prerequisites, refer to [Development](./development.md) and for a detailed guide to the development flow, visit [Governance](./governance.md).
+
+## Run the manager on a (k3d) cluster using a Docker image
+
+### Installation
+
+1. Ensure you have a k3d cluster ready.
+   ```sh
+   k3d create cluster <clusterName>
+   ```
+
+    > **NOTE:** Alternatively to a k3d cluster, the Kubecontext can also point to any existing Kubernetes cluster.
+
+2. Install the CRD of Eventing Manager.
+
+   ```sh
+   make install
+   ```
+
+3. Export the target registry.
+
+   If you are using Docker, `<container-registry>` is your username.
+
+      ```sh
+      export IMG=<container-registry>/<image>:<tag>
+      ```
+
+4. Build and push your image to the registry.
+
+   ```sh
+   make docker-build docker-push IMG=$IMG
+   ```
+
+   > **NOTE:** For MacBook M1 devices, run:
+   >
+   >   ```sh
+   >   make docker-buildx IMG=$IMG
+   >   ```
+
+5. Deploy the controller to the k3d cluster.
+
+   ```sh
+   make deploy IMG=$IMG
+   ```
+
+6. To start the reconciliation process, apply the Eventing custom resource (CR).
+This step depends on your desired backend: NATS or EventMesh.
+
+    - **Backend: NATS**
+
+      For NATS Backend you can apply the default CR using the following command:  
+
+      ```sh
+      kubectl apply -f config/samples/default.yaml
+      ```
+
+      The `spec.backend.type` needs to be set to `NATS`. You can configure the backend using the `NATS` related field in `spec.backend.config`.
+
+      ```sh
+      spec:
+        backend:
+          type: NATS
+          config:
+            natsStreamStorageType: File
+            natsStreamReplicas: 3
+            natsStreamMaxSize: 700M
+            natsMaxMsgsPerTopic: 1000000
+      ```
+
+    - **Backend: EventMesh**
+
+      For EventMesh Backend you can apply the default CR using the following command:
+
+      ```sh
+      kubectl apply -f config/samples/default_eventmesh.yaml
+      ```
+
+      - `spec.backend.type`: set to `EventMesh`
+      - `spec.backend.config.eventMeshSecret`: set it to the `<namespace>/<name>` where you applied the secret
+      - `spec.backend.config.eventTypePrefix`: change to your desired value or leave as is
+      - `spec.backend.config.domain`: set to the cluster public domain
+
+      If the Kyma Kubernetes cluster is managed by Gardener, Eventing Manager reads the cluster public domain automatically from the ConfigMap `kube-system/shoot-info`.
+      Otherwise, you need to additionally set `spec.backend.config.domain` in the configuration. 
+
+      ```sh
+      spec:
+        backend:
+          type: "EventMesh"
+          config:
+            eventMeshSecret: "<namespace>/<name>"
+            eventTypePrefix: "<prefix>"
+            domain: "<example.domain.com>"
+      ```
+
+7. Check the `status` section to see if deployment was successful.
+
+   ```shell
+   kubectl get <resourceName> -n <namespace> -o yaml
+   ```
+
+   >**Note:** Usually, the default values are as follows:
+   >
+   >  ```shell
+   >  kubectl get eventings.operator.kyma-project.io -n kyma-system -o yaml
+   >  ```
+
+### Uninstallation
+
+1. Remove the controller.
+
+   ```sh
+   make undeploy
+   ```
+
+2. Remove the resources.
+
+   ```sh
+   make uninstall
+   ```
+
+## Run Eventing Manager on a cluster using the Go runtime environment
+
+### Installation
+
+1. Ensure you have the Kubecontext pointing to an existing Kubernetes cluster.
+
+2. Clone Eventing Manager project.
+
+3. Download Go packages.
+
+   ```sh
+   go mod vendor && go mod tidy
+   ```
+
+4. Install the CRD of Eventing Manager.
+
+   ```sh
+   make install
+   ```
+
+5. Run Eventing Manager locally.
+
+   ```sh
+   make run
+   ```
+
+### Uninstallation
+
+Remove the resources.
+
+   ```sh
+   make uninstall
+   ```
+
+## Run Eventing Manager using Kyma's Lifecycle Manager
+
+[Kyma's Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager) helps manage the lifecycle of each module in the cluster and can be used to install Eventing Manager.
+
+To run Eventing Manager, follow the steps detailed in the [Lifecycle Manager documentation](https://github.com/kyma-project/lifecycle-manager/tree/main/docs).