docs: Create a new folder structure (#1905)

* Create a new folder structure

* Apply Chris's suggestions

* Formatting fix

* Revert "Formatting fix"

This reverts commit 2f9aac7.

* remove whitespace

---------

Co-authored-by: Christoph Schwägerl <c.schwaegerl@sap.com>

README.md

@@ -1,66 +1,33 @@
-<!-- markdown-link-check-disable-next-line -->
-[![REUSE status](https://api.reuse.software/badge/github.com/kyma-project/lifecycle-manager)](https://api.reuse.software/info/github.com/kyma-project/lifecycle-manager)
 # Lifecycle Manager
 
-Kyma is an opinionated set of Kubernetes-based modular building blocks that includes the necessary capabilities to develop and run enterprise-grade cloud-native applications. Kyma's Lifecycle Manager is a tool that manages the lifecycle of these modules in your cluster.
-
-## Modularization
-
-Lifecycle Manager was introduced along with the concept of Kyma modularization. With Kyma's modular approach, you can install just the modules you need, giving you more flexibility and reducing the footprint of your Kyma cluster. Lifecycle Manager manages clusters using the [Kyma](api/v1beta2/kyma_types.go) custom resource (CR). The CR defines the desired state of modules in a cluster. With the CR you can enable and disable modules. Lifecycle Manager installs or uninstalls modules and updates their statuses. For more details, read about the [modularization concept in Kyma](https://github.com/kyma-project/community/tree/main/concepts/modularization).
-
-## Basic Concepts
-
-See the list of basic concepts relating to Lifecycle Manager to understand its workflow better.
-
-- Kyma custom resource (CR) - represents Kyma installation in a cluster. It contains the list of modules and their state.
-- ModuleTemplate CR - contains modules' metadata with links to their images and manifests. ModuleTemplate CR represents a module in a particular version. Based on this resource Lifecycle Manager enables or disables modules in your cluster.
-- Manifest CR - represents resources that make up a module and are to be installed by Lifecycle Manager. The Manifest CR is a rendered module enabled on a particular cluster.
-- Module CR, such as Keda CR - allows you to configure the behavior of a module. This is a per-module CR.
-
-For the worklow details, read the [Architecture](docs/technical-reference/architecture.md) document.
-
-## Quick Start
-
-Follow this quick start guide to set up the environment and use Lifecycle Manager to add modules.
-
-### Prerequisites
-
-To use Lifecycle Manager in a local setup, install the following:
-
-- [k3d](https://k3d.io/)
-- [istioctl](https://istio.io/latest/docs/setup/install/istioctl/)
-- [Kyma CLI](https://kyma-project.io/docs/kyma/latest/04-operation-guides/operations/01-install-kyma-CLI)
-
-### Steps
-
-1. To set up the environment, provision a local k3d cluster and install Kyma. Run:
+<!-- markdown-link-check-disable-next-line -->
+[![REUSE status](https://api.reuse.software/badge/github.com/kyma-project/lifecycle-manager)](https://api.reuse.software/info/github.com/kyma-project/lifecycle-manager)
 
-  ```bash
-  k3d registry create kyma-registry --port 5001
-  k3d cluster create kyma --kubeconfig-switch-context -p 80:80@loadbalancer -p 443:443@loadbalancer --registry-use kyma-registry
-  kubectl create ns kyma-system
-  kyma alpha deploy
-  ```
+## Overview
 
-2. Apply a ModuleTemplate CR. Run the following kubectl command:
+Lifecycle Manager is an operator based on the [Kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) framework. It extends Kubernetes API by providing multiple Custom Resource Definitions, which allow you to manage their resources through custom resources (CR). For more information, see [Lifecycle Manager Resources](./docs/contributor/resources/README.md).
 
-  ```bash
-  kubectl apply -f {MODULE_TEMPLATE.yaml}
-  ```
+Lifecycle Manager manages the lifecycle of [Kyma Modules](https://help.sap.com/docs/btp/sap-business-technology-platform/kyma-modules) in a cluster. It was introduced along with the concept of Kyma [modularizaion](https://github.com/kyma-project/community/tree/main/concepts/modularization).
 
-**TIP:** You can use any deployment-ready ModuleTemplates, such as [cluster-ip](https://github.com/pbochynski/) or [keda](https://github.com/kyma-project/keda-manager).
+For more information on the Lifecycle Manager's workflow, see the [Architecture](docs/contributor/01-architecture.md) document.
 
-3. Enable a module. Run:
+## Usage
 
-  ```bash
-  kyma alpha add module {MODULE_NAME}
-  ```
+If you are a Kyma end user, see the [user documentation](./docs/user/README.md).
 
-**TIP:** Check the [modular Kyma interactive tutorial](https://killercoda.com/kyma-project/scenario/modular-kyma) to play with enabling and disabling Kyma modules in both terminal and Busola.
+## Development
 
-## Read More
+If you want to provide new features for Lifecycle Manager, develop a module, or are part of the SRE team, visit the [contributor](/docs/contributor/) folder. You will find the following documents:
 
-Go to the [`Table of Contents`](/docs/README.md) in the `/docs` directory to find the complete list of documents on Lifecycle Manager. Read those to learn more about Lifecycle Manager and its functionalities.
+* [Architecture](/docs/contributor/01-architecture.md)
+* [Controllers](/docs/contributor/02-controllers.md)
+* [Provide Credentials for Private OCI Registry Authentication](/docs/contributor/03-config-private-registry.md)
+* [Local Test Setup in the Control Plane Mode Using k3d](/docs/contributor/04-local-test-setup.md)
+* [Resources](/docs/contributor/resources/README.md)
+  * [Kyma](/docs/contributor/resources/01-kyma.md)
+  * [Manifest](/docs/contributor/resources/02-manifest.md)
+  * [ModuleTemplate](/docs/contributor/resources/03-moduletemplate.md)
+  * [Watcher](/docs/contributor/resources/04-watcher.md)
 
 ## Contributing
 

docs/technical-reference/architecture.md → docs/contributor/01-architecture.md

@@ -12,7 +12,7 @@ Lifecycle Manager:
 
 The diagram shows a sample deployment of KCP in interaction with a Kyma runtime.
 
-![Lifecycle Manager Architecture](/docs/assets/lifecycle-manager-architecture.svg)
+![Lifecycle Manager Architecture](./assets/lifecycle-manager-architecture.svg)
 
 To run, Lifecycle Manager uses the following workflow:
 

docs/developer-tutorials/local-test-setup.md → docs/contributor/04-local-test-setup.md

@@ -1,4 +1,4 @@
-# Local test Setup in the control-plane Mode Using k3d
+# Local Test Setup in the Control Plane Mode Using k3d
 
 > ### Supported Versions
 > * Golang: `v1.22.5`

docs/technical-reference/api/kyma-cr.md → docs/contributor/resources/01-kyma.md

@@ -1,4 +1,12 @@
-# Kyma Custom Resource
+# Kyma
+
+The `kymas.operator.kyma-project.io` Custom Resource Definition (CRD) defines the structure and format used to manage a cluster and its desired state. It contains the list of added modules and their state.
+
+To get the latest CRD in the YAML format, run the following command:
+
+```bash
+kubectl get crd kymas.operator.kyma-project.io -o yaml
+```
 
 The [Kyma custom resource (CR)](../../../api/v1beta2/kyma_types.go) is used to declare the desired state of a cluster. **.spec.channel**, **.spec.modules[].channel**, and **.spec.modules** are the basic fields that are used together to define the cluster state.
 

docs/technical-reference/api/manifest-cr.md → docs/contributor/resources/02-manifest.md

@@ -1,6 +1,14 @@
-# Manifest Custom Resource
+# Manifest
 
-The [Manifest custom resource (CR)](../../../api/v1beta2/manifest_types.go) is our internal representation of what results from the resolution of a ModuleTemplate CR in the context of a single cluster represented by a Kyma CR. Thus, a lot of configuration elements are similar or entirely equivalent to the data layer found in a ModuleTemplate CR.
+The `manifests.operator.kyma-project.io` Custom Resource Definition (CRD) defines the structure and format used to configure the Manifest resource.
+
+The Manifest custom resource (CR) represent resources that make up a module and are to be installed by Lifecycle Manager. The Manifest CR is a rendered module added to a particular cluster.
+
+To get the latest CRD in the YAML format, run the following command:
+
+```bash
+kubectl get crd manifests.operator.kyma-project.io -o yaml
+```
 
 ## Patching
 
@@ -10,7 +18,7 @@ The [Runner](../../../pkg/module/sync/runner.go) is responsible for creating and
 2. The Manifest CR channel differs from the Kyma CR's module status channel.
 3. The Manifest CR state differs from the Kyma CR's module status state.
 
->[!NOTE] 
+>[!NOTE]
 >The module status is not present in the Kyma CR for mandatory modules, hence their Manifest CR is updated using SSA in every reconcile loop.
 
 ## Configuration
@@ -102,12 +110,12 @@ The resource is the default data that should be initialized for the module and i
 
 ### **.status**
 
-The Manifest CR status is set based on the following logic, managed by the manifest reconciler: 
+The Manifest CR status is set based on the following logic, managed by the manifest reconciler:
 
-- If the module defined in the Manifest CR is successfully applied and the deployed module is up and running, the status of the Manifest CR is set to `Ready`.
-- While the manifest is being applied and the Deployment is still starting, the status of the Manifest CR is set to `Processing`.
-- If the Deployment cannot start (for example, due to an `ImagePullBackOff` error) or if the application of the manifest fails, the status of the Manifest CR is set to `Error`.
-- If the Manifest CR is marked for deletion, the status of the Manifest CR is set to `Deleting`.
+* If the module defined in the Manifest CR is successfully applied and the deployed module is up and running, the status of the Manifest CR is set to `Ready`.
+* While the manifest is being applied and the Deployment is still starting, the status of the Manifest CR is set to `Processing`.
+* If the Deployment cannot start (for example, due to an `ImagePullBackOff` error) or if the application of the manifest fails, the status of the Manifest CR is set to `Error`.
+* If the Manifest CR is marked for deletion, the status of the Manifest CR is set to `Deleting`.
 
 This status provides a reliable way to track the state of the Manifest CR and the associated module. It offers insights into the deployment process and any potential issues while being decoupled from the module's business logic.
 

docs/technical-reference/api/moduleTemplate-cr.md → docs/contributor/resources/03-moduletemplate.md

@@ -1,6 +1,14 @@
-# ModuleTemplate Custom Resource
+# ModuleTemplate
 
-The core of our modular discovery is the [ModuleTemplate custom resource (CR)](../../../api/v1beta2/moduletemplate_types.go). It is used to initialize and resolve modules.
+The `moduletemplates.operator.kyma-project.io` Custom Resource Definition (CRD) defines the structure and format used to configure the ModuleTemplate resource.
+
+The ModuleTemplate custom resource (CR) defines a module, in a particular version, that can be added to or deleted from the module list in the Kyma CR. Each ModuleTemplate CR represents one module.
+
+To get the latest CRD in the YAML format, run the following command:
+
+```bash
+kubectl get crd moduletemplates.operator.kyma-project.io -o yaml
+```
 
 ## Configuration
 

docs/contributor/resources/04-watcher.md

@@ -0,0 +1,11 @@
+# Watcher
+
+The `watchers.operator.kyma-project.io` Custom Resource Definition (CRD) defines the structure and format used to configure the Watcher resource.
+
+The Watcher custom resource (CR) defines the callback functionality for synchronized Kyma runtime clusters, that allows lower latencies before the Kyma Control Plane cluster detects any changes.
+
+To get the latest CRD in the YAML format, run the following command:
+
+```bash
+kubectl get crd watchers.operator.kyma-project.io -o yaml
+```

docs/technical-reference/api/README.md → docs/contributor/resources/README.md

@@ -1,22 +1,11 @@
-# Lifecycle Manager API
+# Lifecycle Manager Resources
 
-## Overview
+The API of Lifecycle Manager is based on Kubernetes Custom Resource Definitions (CRDs), which extend the Kubernetes API with custom additions. The CRDs allow Lifecycle Manager to manage clusters and modules. To inspect the specification of the Lifecycle Manager resources, see:
 
-The Lifecycle Manager API types consist of three major custom resources (CRs). Each CR deals with a specific aspect of reconciling modules into their corresponding states.
-
-1. [Kyma CR](/api/v1beta2/kyma_types.go) that introduces a single entry point CustomResourceDefinition to control a cluster and it's desired state.
-2. [Manifest CR](/api/v1beta2/manifest_types.go) that introduces a single entry point CustomResourceDefinition to control a module and it's desired state.
-3. [ModuleTemplate CR](/api/v1beta2/moduletemplate_types.go) that contains all reference data for the modules to be installed correctly. It is a standardized desired state for a module available in a given release channel.
-
-Additionally, we maintain the [Watcher CR](/api/v1beta2/watcher_types.go) to define the callback functionality for synchronized remote clusters that allows lower latencies before the Control Plane detects any changes.
-
-## Custom Resource Definitions
-
-Read more about the custom resource definitions (CRDs) in the respective documents:
-
-* [Kyma CR](kyma-cr.md)
-* [Manifest CR](manifest-cr.md)
-* [ModuleTemplate CR](moduleTemplate-cr.md)
+* [Kyma CRD](01-kyma.md)
+* [Manifest CRD](02-manifest.md)
+* [ModuleTemplateCRD](03-moduletemplate.md)
+* [Watcher CRD](04-watcher.md)
 
 ## Synchronization of Module Catalog with Remote Clusters
 
@@ -36,7 +25,7 @@ By default, without any labels configured on Kyma and ModuleTemplate CRs, a Modu
 
 **NOTE:** Disabling synchronization for already synchronized ModuleTemplates CRs doesn't remove them from remote clusters. The CRs remain as they are, but any subsequent changes to these ModuleTemplate CRs in the Control Plane are not synchronized.
 
-For details, read about [the Kyma CR synchronization labels](kyma-cr.md#operatorkyma-projectio-labels) and [the ModuleTemplate CR synchronization labels](moduleTemplate-cr.md#operatorkyma-projectio-labels).
+For more information, see [the Kyma CR synchronization labels](kyma-cr.md#operatorkyma-projectio-labels) and [the ModuleTemplate CR synchronization labels](moduleTemplate-cr.md#operatorkyma-projectio-labels).
 
 ## Stability
 
@@ -48,3 +37,5 @@ See the list of CRs involved in Lifecycle Manager's workflow and their stability
 | v1beta2 | [ModuleTemplate](/api/v1beta2/moduletemplate_types.go)     | Beta-Grade - no breaking changes without API incrementation. Use for automation and watch upstream as close as possible for deprecations or new versions. Alpha API is deprecated and converted via webhook. |
 | v1beta2 | [Manifest](/api/v1beta2/manifest_types.go)                 | Beta-Grade - no breaking changes without API incrementation. Use for automation and watch upstream as close as possible for deprecations or new versions. Alpha API is deprecated and converted via webhook. |
 | v1beta2 | [Watcher](/api/v1beta2/watcher_types.go)                   | Beta-Grade - no breaking changes without API incrementation. Use for automation and watch upstream as close as possible for deprecations or new versions. Alpha API is deprecated and converted via webhook. |
+
+For more information on changes introduced by an API version, see [API Changelog](../api-changelog.md).