From 098ebe605f8c2b3854b1c843f09429d7a8881076 Mon Sep 17 00:00:00 2001 From: Amritanshu Sikdar Date: Wed, 21 Aug 2024 15:03:50 +0200 Subject: [PATCH 1/2] update technical reference documentation --- docs/technical-reference/controllers.md | 2 +- docs/technical-reference/running-modes.md | 22 +++++++++++----------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/technical-reference/controllers.md b/docs/technical-reference/controllers.md index e9fb60cfb3..7d95726e47 100644 --- a/docs/technical-reference/controllers.md +++ b/docs/technical-reference/controllers.md @@ -42,4 +42,4 @@ Suppose a Kyma CR has been marked for deletion for longer than the grace period ## Watcher Controller -[Watcher controller](../../internal/controller/watcher/controller.go) deals with the update of VirtualService rules derived from the [Watcher CR](../../api/v1beta2/watcher_types.go). This is then used to initialize the Watcher CR from the Kyma Controller in each runtime, a small component initialized to propagate changes from the runtime (remote) clusters back to react to changes that can affect the Manifest CR integrity. +[Watcher controller](../../internal/controller/watcher/controller.go) deals with the changes of VirtualService rules derived from the [Watcher CR](../../api/v1beta2/watcher_types.go). This is then used to initialize the Watcher CR from the Kyma Controller in each runtime. Simply put, it is a small component initialized to propagate changes from the runtime (remote) clusters back to the Kyma Control Plane (KCP), for it to react to the changes accordingly, ensuring the integrity of the affected Manifest CRs. diff --git a/docs/technical-reference/running-modes.md b/docs/technical-reference/running-modes.md index 3f9dd7ccd5..09dd465056 100644 --- a/docs/technical-reference/running-modes.md +++ b/docs/technical-reference/running-modes.md @@ -2,30 +2,30 @@ Lifecycle Manager can run in two modes: -* single-cluster - deployment mode in which Lifecycle Manager is running on the same clutser on which you deploy Kyma. This mode doesn't require Kyma or ModuleTemplate CRs [synchronization](api/README.md#synchronization-of-module-catalog-with-remote-clusters). -* control-plane - deployment mode in which Lifecycle Manager is running on the central Kubernetes cluster that manages multiple remote clusters that are targets for Kyma installations. In this mode, Kyma and ModuleTemplate CRs are synchronized between the central cluster and remote ones. Access to remote clusters is enabled using centrally-managed K8s Secrets with the required connection configuration. +* **single-cluster:** Deployment mode in which Lifecycle Manager is running on the same cluster in which you deploy Kyma. This mode doesn't require [synchronization](api/README.md#synchronization-of-module-catalog-with-remote-clusters) of Kyma CRs or ModuleTemplate CRs. +* **control-plane:** Deployment mode in which Lifecycle Manager is running on the central Kubernetes cluster that manages multiple remote clusters which are targets for Kyma installations. In this mode, Kyma and ModuleTemplate CRs are synchronized between the central cluster and remote ones. Access to remote clusters is enabled using centrally-managed K8s Secrets with the required connection configuration. -To configure the mode for Lifecycle Manager, use the `in-kcp-mode` command-line flag. By default, the flag is set to `false`. If set to `true`, Lifecycle Manager runs in the control-plane mode. +To configure the running-mode for Lifecycle Manager, use the `in-kcp-mode` command-line flag. By default, the flag is set to `false`. If set to `true`, Lifecycle Manager runs in the control-plane mode. -Use the single-cluster mode for local development and testing. For E2E testing, testing of scalability and remote reconciliation, we recommend to use a separate Control Plane cluster. +> Tip: Use the single-cluster mode for local development and testing. For E2E testing, testing of scalability and remote reconciliation, we recommend to use a separate Control Plane cluster. ## Release Lifecycles for Modules -Teams providing module operators should work (and release) independently from lifecycle-manager. In other words, lifecycle-manager should not have hard-coded dependencies to any module operator. +Teams providing module operators should work (and release) independently of lifecycle-manager. In other words, lifecycle-manager should not have hard-coded dependencies to any module operator. As such, all module interactions are abstracted through the [ModuleTemplate](/api/v1beta2/moduletemplate_types.go). -This abstraction of a template is used for generically deploying instances of a module within a Kyma Runtime at a specific Release Group we call `Channel` (for more information, visit the respective Chapter in the [Concept for Modularization](https://github.com/kyma-project/community/tree/main/concepts/modularization#release-channels)). It contains not only a specification of a Module with it's different components through [OCM Component Descriptors](https://github.com/gardener/component-spec/blob/master/doc/proposal/02-component-descriptor.md). +This abstraction of a module template is used for generically deploying instances of a module within a Kyma Runtime at a specific Release Group we call `Channel` (for more information, visit the respective Chapter in the [Concept of Modularization](https://github.com/kyma-project/community/tree/main/concepts/modularization#release-channels)). It not only contains a specification of a Module with its underlying components through [OCM Component Descriptors](https://github.com/gardener/component-spec/blob/master/doc/proposal/02-component-descriptor.md), but also talks in detail about the schemas, labels and other essential resources. -These serve as small-scale BOM's for all contents included in a module and can be interpreted by Lifecycle Manager and [Module Manager](https://github.com/kyma-project/module-manager/) -to correctly install a module. (for more information, please have a look at the respective chapter in the [Kyma Modularization Concept](https://github.com/kyma-project/community/tree/main/concepts/modularization#component-descriptor)) +These serve as small-scale BoM's for all contents included in a module and can be interpreted by Lifecycle Manager and [Module Manager](https://github.com/kyma-project/module-manager/) +to correctly install a module (for more information, please have a look at the respective chapter in the [Kyma Modularization Concept](https://github.com/kyma-project/community/tree/main/concepts/modularization#component-descriptor)). ## Versioning and Releasing -Kyma up to Version 2.x was always a single release. However, the vision of lifecycle-manager is to fully encapsulate individual Modules, with each providing a (possibly fully independent) Release Cycle. -However, Control-Plane deliveries are by design continuously shipped and improved. As a result, even if we will continue to support versioned Module Deliveries, the Lifecycle-Manager and its adjacent infrastructure will be maintained and delivered continously and it is recommended to track upstream as close as possible. +Kyma up to Version 2.x was always a single release. However, the vision of Lifecycle Manager is to fully encapsulate individual Modules, with each providing a (possibly fully independent) Release Cycle. +However, the Control-Plane deliveries are by design continuously shipped and improved. As a result, even if we continue to support versioned Module deliveries, the Lifecycle Manager and its adjacent infrastructure will be maintained and delivered continuously, and it is recommended to track upstream as close as possible. ## Comparison to the Old Reconciler Traditionally, Kyma was installed with the [Kyma Reconciler](https://github.com/kyma-incubator/reconciler), a Control-Plane implementation of our architecture based on polling and a SQL Store for tracking reconciliations. While this worked great for smaller and medium scale deliveries, we had trouble to scale and maintain it when put under significant load. -We chose to replace this with Operator-focused Reconciliation due to various reasons, more details on the reasoning can be found in our [Concept for Operator Reconciliation](https://github.com/kyma-project/community/tree/main/concepts/operator-reconciliation). +We chose to replace this with Operator-focused reconciliation due to various reasons. More details on the reasoning can be found in our [Concept for Operator Reconciliation](https://github.com/kyma-project/community/tree/main/concepts/operator-reconciliation). From 7698de5610621001eb5f46898bb160b297320fdd Mon Sep 17 00:00:00 2001 From: Amritanshu Sikdar Date: Wed, 21 Aug 2024 16:56:37 +0200 Subject: [PATCH 2/2] resolve PR review comments --- docs/technical-reference/running-modes.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/technical-reference/running-modes.md b/docs/technical-reference/running-modes.md index 09dd465056..75514aa6ed 100644 --- a/docs/technical-reference/running-modes.md +++ b/docs/technical-reference/running-modes.md @@ -5,27 +5,27 @@ Lifecycle Manager can run in two modes: * **single-cluster:** Deployment mode in which Lifecycle Manager is running on the same cluster in which you deploy Kyma. This mode doesn't require [synchronization](api/README.md#synchronization-of-module-catalog-with-remote-clusters) of Kyma CRs or ModuleTemplate CRs. * **control-plane:** Deployment mode in which Lifecycle Manager is running on the central Kubernetes cluster that manages multiple remote clusters which are targets for Kyma installations. In this mode, Kyma and ModuleTemplate CRs are synchronized between the central cluster and remote ones. Access to remote clusters is enabled using centrally-managed K8s Secrets with the required connection configuration. -To configure the running-mode for Lifecycle Manager, use the `in-kcp-mode` command-line flag. By default, the flag is set to `false`. If set to `true`, Lifecycle Manager runs in the control-plane mode. +To configure the running mode for Lifecycle Manager, use the `in-kcp-mode` command-line flag. By default, the flag is set to `false`. If set to `true`, Lifecycle Manager runs in the control-plane mode. > Tip: Use the single-cluster mode for local development and testing. For E2E testing, testing of scalability and remote reconciliation, we recommend to use a separate Control Plane cluster. ## Release Lifecycles for Modules -Teams providing module operators should work (and release) independently of lifecycle-manager. In other words, lifecycle-manager should not have hard-coded dependencies to any module operator. +Teams providing module operators should work (and release) independently of Lifecycle Manager. In other words, Lifecycle Manager should not have hard-coded dependencies to any module operator. As such, all module interactions are abstracted through the [ModuleTemplate](/api/v1beta2/moduletemplate_types.go). -This abstraction of a module template is used for generically deploying instances of a module within a Kyma Runtime at a specific Release Group we call `Channel` (for more information, visit the respective Chapter in the [Concept of Modularization](https://github.com/kyma-project/community/tree/main/concepts/modularization#release-channels)). It not only contains a specification of a Module with its underlying components through [OCM Component Descriptors](https://github.com/gardener/component-spec/blob/master/doc/proposal/02-component-descriptor.md), but also talks in detail about the schemas, labels and other essential resources. +This abstraction of a module template is used for generically deploying instances of a module within a Kyma Runtime at a specific Release Group we call `Channel` (for more information, visit the respective Chapter in the [Concept of Modularization](https://github.com/kyma-project/community/tree/main/concepts/modularization#release-channels)). It not only contains a specification of a Module with its underlying components through [OCM Component Descriptors](https://github.com/gardener/component-spec/blob/master/doc/proposal/02-component-descriptor.md), but also talks in detail about the schemas, labels, and other essential resources. These serve as small-scale BoM's for all contents included in a module and can be interpreted by Lifecycle Manager and [Module Manager](https://github.com/kyma-project/module-manager/) to correctly install a module (for more information, please have a look at the respective chapter in the [Kyma Modularization Concept](https://github.com/kyma-project/community/tree/main/concepts/modularization#component-descriptor)). ## Versioning and Releasing -Kyma up to Version 2.x was always a single release. However, the vision of Lifecycle Manager is to fully encapsulate individual Modules, with each providing a (possibly fully independent) Release Cycle. -However, the Control-Plane deliveries are by design continuously shipped and improved. As a result, even if we continue to support versioned Module deliveries, the Lifecycle Manager and its adjacent infrastructure will be maintained and delivered continuously, and it is recommended to track upstream as close as possible. +Kyma up to Version 2.x was always a single release. However, the vision of Lifecycle Manager is to fully encapsulate individual modules, with each providing a (possibly fully independent) release cycle. +By design, the KCP deliveries are continuously shipped and improved. We aim to support versioned module deliveries, so the Lifecycle Manager and its adjacent infrastructure will be maintained as well as delivered continuously, and it is recommended to track upstream as close as possible. ## Comparison to the Old Reconciler Traditionally, Kyma was installed with the [Kyma Reconciler](https://github.com/kyma-incubator/reconciler), a Control-Plane implementation of our architecture based on polling and a SQL Store for tracking reconciliations. While this worked great for smaller and medium scale deliveries, we had trouble to scale and maintain it when put under significant load. -We chose to replace this with Operator-focused reconciliation due to various reasons. More details on the reasoning can be found in our [Concept for Operator Reconciliation](https://github.com/kyma-project/community/tree/main/concepts/operator-reconciliation). +We chose to replace this with operator-focused reconciliation - for details on the reasoning, read [Concept for Operator Reconciliation](https://github.com/kyma-project/community/tree/main/concepts/operator-reconciliation).