From b2e09126541872016a4a5a8ef21611598ae72d8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C5=82gorzata=20=C5=9Awieca?= Date: Fri, 23 Feb 2024 15:36:35 +0100 Subject: [PATCH] docs: Update Lifecycle Manager docu (#1339) * docs: Update Lifecycle Manager docu * Upload the diagram * Update architecture.md * Apply Iwona's reveiw suggestions * Apply Chris's suggestions from code review --- .../assets/lifecycle-manager-architecture.svg | 4 +- docs/technical-reference/api/kyma-cr.md | 43 ++++++++++--------- docs/technical-reference/api/manifest-cr.md | 35 +++++++-------- .../api/moduleTemplate-cr.md | 10 +++-- docs/technical-reference/architecture.md | 19 ++++---- docs/technical-reference/controllers.md | 29 ++++--------- .../01-10-control-plane-quick-start.md | 9 ++-- ...nage-module-with-custom-resource-policy.md | 5 ++- internal/manifest/README.md | 11 ++--- 9 files changed, 84 insertions(+), 81 deletions(-) diff --git a/docs/assets/lifecycle-manager-architecture.svg b/docs/assets/lifecycle-manager-architecture.svg index 6d78bd6060..ae0f89e3d8 100644 --- a/docs/assets/lifecycle-manager-architecture.svg +++ b/docs/assets/lifecycle-manager-architecture.svg @@ -1,4 +1,4 @@ - + -
Kyma Control Plane
Kyma Control Plane
Kyma Runtime
Kyma Runtime
kyma-system
kyma-system
kcp-system
kcp-system
Runtime Admin
Runtime Admin
ModuleTemplate CR(s)
ModuleTemplate CR...
synchronize
synchronize
ModuleTemplate CR(s)
ModuleTemplate CR...
Module Catalog
Module Catalog
Kyma CR
Kyma CR
Kyma CR
Kyma CR
synchronize
synchronize
reconciles
reconciles
reconciles
reconciles
creates / updates
creates / updates
reads
reads
reads
reads
Lifecycle Manager
Lifecycle Manager
Kubeconfig Secret
Kubeconfig Secr...
Manifest CR
Manifest CR
reconciles
reconciles
Module Manager, e.g. Keda Manager
Module Manager,...
Module CR, e.g. Keda CR
Module CR, e.g....
Module, e.g. Keda
Module, e.g. Ke...
adds / removes modules
a...
1
1
2
2
3
3
2
2
4
4Text is not SVG - cannot display \ No newline at end of file +
Kyma Control Plane
Kyma Control Plane
Kyma Runtime
Kyma Runtime
kyma-system
kyma-system
kcp-system
kcp-system
Runtime Admin
Runtime Admin
ModuleTemplate CR(s)
ModuleTemplate CR...
synchronize
synchronize
ModuleTemplate CR(s)
ModuleTemplate CR...
Module Catalog
Module Catalog
Kyma CR(s)
Kyma CR(s)
Kyma CR
Kyma CR
synchronize
synchronize
reconciles
reconciles
reconciles
reconciles
creates / updates
creates / updates
reads
reads
reads
reads
Lifecycle Manager
Lifecycle Manager
Kubeconfig Secret(s)
Kubeconfig Secr...
Manifest CR(s)
Manifest CR(s)
reconciles
reconciles
Module Manager, e.g. Keda Manager
Module Manager,...
Module CR, e.g. Keda CR
Module CR, e.g....
Module, e.g. Keda
Module, e.g. Ke...
adds / deletes modules
a...
1
1
2
2
3
3
2
2
4
4
5
5Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/technical-reference/api/kyma-cr.md b/docs/technical-reference/api/kyma-cr.md index 3c7c28ca64..a8438cad57 100644 --- a/docs/technical-reference/api/kyma-cr.md +++ b/docs/technical-reference/api/kyma-cr.md @@ -1,12 +1,15 @@ # Kyma Custom Resource -The [Kyma custom resource (CR)](/api/v1beta2/kyma_types.go) contains 3 fields that are together used to declare the desired state of a cluster: +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. -1. **.spec.channel** and **.spec.modules[].channel**: The Release Channel that should be used by default for all modules that are to be installed in the cluster. -2. **.spec.modules**: The modules that should be installed into the cluster. Each module contains a name serving as a link to the ModuleTemplate CR. -Additionally, you can add a specific channel (if `.spec.channel`) should not be used. -On top of that, you can specify a `controller`, which serves as a Multi-Tenant Enabler. -It can be used to only listen to ModuleTemplate CRs provided under the same controller name. Last but not least, it includes a `customResourcePolicy` which can be used for specifying defaulting behavior when initializing modules in a cluster. +- **.spec.channel** - defines a release channel that should be used by default for all modules that are to be installed in the cluster. +- **.spec.modules[].channel** - defines a release channel other than the default channel (**.spec.channel**) for a given module that is to be installed in the cluster. +- **.spec.modules** - specifies modules that should be added to the cluster. Each module contains a name serving as a link to the ModuleTemplate CR. +Additionally, you can add a specific channel if **.spec.channel** should not be used. +On top of that, you can specify a **controller**, which serves as a Multi-Tenant Enabler. +It can be used to only listen to ModuleTemplate CRs provided under the same controller name. Last but not least, it includes a **customResourcePolicy** which can be used for specifying default behavior when initializing modules in a cluster. + +## Configuration ### **.spec.channel** and **.spec.modules[].channel** @@ -22,7 +25,7 @@ spec: - name: serverless ``` -will attempt to look up the modules `keda` and `serverless` in the `alpha` release channel. +attempts to look up the Keda and Serverless modules in the `alpha` release channel. However, if you specify channels using the **.spec.modules[].channel** attribute, the latter one is used instead. @@ -35,11 +38,11 @@ spec: - name: serverless ``` -In this case, the relevant channel will be `regular` for `keda`, but not for `serverless`. +In this case, `regular` is the relevant channel for Keda, but not for Serverless. ### **.spec.modules** -The module list is used to define the desired set of all modules. This is mainly derived from the **.spec.modules[].name** attribute which is resolved in one of 3 ways. +The module list is used to define the desired set of all modules. This is mainly derived from the **.spec.modules[].name** attribute which is resolved in one of 3 ways. Let's take a look at this simplified ModuleTemplate CR: @@ -61,7 +64,7 @@ spec: The module mentioned above can be referenced in one of the following ways: -1. The label value of `operator.kyma-project.io/module-name`: +- The label value of `operator.kyma-project.io/module-name`: ```yaml spec: @@ -70,7 +73,7 @@ The module mentioned above can be referenced in one of the following ways: - name: module-name-from-label ``` -2. The Name or Namespace/Name of a ModuleTemplate CR: +- The name or namespace/name of a ModuleTemplate CR: ```yaml spec: @@ -88,7 +91,7 @@ The module mentioned above can be referenced in one of the following ways: - name: default/moduletemplate-sample ``` -3. The fully qualified name of the descriptor as located in **.spec.descriptor.component.name**: +- The fully qualified name of the descriptor as located in **.spec.descriptor.component.name**: ```yaml spec: @@ -100,18 +103,18 @@ The module mentioned above can be referenced in one of the following ways: ### **.spec.modules[].customResourcePolicy** In addition to this very flexible way of referencing modules, there is also another flag that can be important for users requiring more flexibility during module initialization. The `customResourcePolicy` flag is used to define one of `CreateAndDelete` and `Ignore`. -While `CreateAndDelete` will cause the ModuleTemplate's **.spec.data** to be created and deleted to initialize a module with preconfigured defaults, `Ignore` can be used to only initialize the operator without initializing any default data. +While `CreateAndDelete` causes the ModuleTemplate CR's **.spec.data** to be created and deleted to initialize a module with preconfigured defaults, `Ignore` can be used to only initialize the operator without initializing any default data. This allows users to be fully flexible in regard to when and how to initialize their module. ### **.status.state** -The **state** attribute is a simple representation of the state of the entire Kyma CR installation. It is defined as an aggregated status that is either `Ready`, `Processing`, `Error`, or `Deleting`, based on the status of _all_ Manifest CRs on top of the validity/integrity of the synchronization to a remote cluster if enabled. +The **state** attribute is a simple representation of the state of the entire Kyma CR installation. It is defined as an aggregated status that is either `Ready`, `Processing`, `Warning`, `Error`, or `Deleting`, based on the status of all Manifest CRs on top of the validity/integrity of the synchronization to a remote cluster if enabled. -The **state** will always be reported based on the last reconciliation loop of the [Kyma controller](../../../internal/controller/kyma_controller.go). It will be set to `Ready` only if all installations were successfully executed and are consistent at the time of the reconciliation. +The **state** is always reported based on the last reconciliation loop of the [Kyma controller](../../../internal/controller/kyma_controller.go). It will be set to `Ready` only if all installations were successfully executed and are consistent at the time of the reconciliation. ### **.status.conditions** -The conditions represent individual elements of the reconciliation that can either be `true` or `false`, for example representing the readiness of all modules (Manifest CR). For more details on how conditions are aggregated and built, take a look at [KEP-1623: Standardize Conditions](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1623-standardize-conditions), which is our reference documentation for conditions. +The conditions represent individual elements of the reconciliation that can either be `true` or `false`, for example, representing the readiness of all modules (Manifest CRs). For more details on how conditions are aggregated and built, take a look at [KEP-1623: Standardize Conditions](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1623-standardize-conditions), which is our reference documentation for conditions. Currently, we maintain conditions for: @@ -119,7 +122,7 @@ Currently, we maintain conditions for: - Module Catalog (ModuleTemplate CR) synchronization - Watcher Installation Consistency -We also calculate **.status.state** readiness based on all the conditions available. +We also calculate the **.status.state** readiness based on all the conditions available. ### **.status.modules** @@ -160,9 +163,9 @@ The same is done for the ModuleTemplate CR. The actual one that is used as a tem To observe not only how the state of the `synchronization` but the entire reconciliation is working, as well as to check on latency and the last observed change, we also introduce the **lastOperation** field. This contains not only a timestamp of the last change (which allows you to view the time since the module was last reconciled by Lifecycle Manager), but also a message that either contains a process message or an error message in case of an `Error` state. Thus, to get more details of any potential issues, it is recommended to check **lastOperation**. -In addition, we also regularly issue `Events` for important things happening at specific time intervals, e.g. critical errors that ease observability. +In addition, we also regularly issue Events for important things happening at specific time intervals, e.g. critical errors that ease observability. -### `operator.kyma-project.io` labels +## `operator.kyma-project.io` labels Various overarching features can be enabled/disabled or provided as hints to the reconciler by providing a specific label key and value to the Kyma CR and its related resources. For better understanding, use the matching [API label reference](/api/shared/operator_labels.go). @@ -173,7 +176,7 @@ The most important labels include, but are not limited to: - `operator.kyma-project.io/signature`: An identifier that can be set on a Secret to identify correct signature X.509 Secrets that contain a key called `key` which contains a X.509 PKIX PublicKey or an PKCS1 Public Key. Used in conjunction with the label-value for templates signed with a signature in the descriptor. - `operator.kyma-project.io/skip-reconciliation`: A label that can be used with the value `true` to completely disable reconciliation for a Kyma CR. Can also be used on the Manifest CR to disable a specific module. This will avoid all reconciliations for the entire Kyma or Manifest CRs. Note that even though reconciliation for the Kyma CR might be disabled, the Manifest CR in a Kyma can still get reconciled normally if not adjusted to have the label set as well. - `operator.kyma-project.io/managed-by`: A cache limitation label that must be set to `lifecycle-manager` to have the resources picked up by the cache. Hard-coded but will be made dynamic to allow for multi-tenant deployments that have non-conflicting caches -- `operator.kyma-project.io/purpose`: Can be used to identify resources by their intended purpose inside Lifecycle Manager. Useful meta information for cluster managers. +- `operator.kyma-project.io/purpose`: Can be used to identify resources by their intended purpose inside Lifecycle Manager. Useful meta-information for cluster managers. - `operator.kyma-project.io/sync`: A boolean value. If set to `false`, the Module Catalog synchronization is disabled for a given Kyma CR, and for the related remote cluster (Managed Kyma Runtime). The default value is `true`. - `operator.kyma-project.io/internal`: A boolean value. If set to `true`, the ModuleTemplate CRs labeled with the same label, so-called `internal` modules, are also synchronized with the remote cluster. The default value is `false`. - `operator.kyma-project.io/beta`: A boolean value. If set to `true`, the ModuleTemplate CRs labeled with the same label, so-called `beta` modules are also synchronized with the remote cluster. The default value is `false`. diff --git a/docs/technical-reference/api/manifest-cr.md b/docs/technical-reference/api/manifest-cr.md index bdb37b5a25..691efd2813 100644 --- a/docs/technical-reference/api/manifest-cr.md +++ b/docs/technical-reference/api/manifest-cr.md @@ -1,12 +1,14 @@ # Manifest Custom Resource -The [Manifest](/api/v1beta1/manifest_types.go) is our internal representation of what results from the resolution of a `ModuleTemplate` in the context of a single cluster represented through `Kyma`. Thus, a lot of configuration elements are similar or entirely equivalent to the layer data found in the `ModuleTemplate` and it is currently being considered for specification rework. +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. -### `.spec.remote` +## Configuration -This flag determines wether the given module should be installed in the remote cluster target or not. If it should, then it will attempt a lookup of the cluster by searching for a secret with a label `operator.kyma-project.io/kyma-name` having the same value as the `operator.kyma-project.io/kyma-name` label on the `Manifest`. +### **.spec.remote** -Thus a Manifest like +This parameter determines whether or not the given module should be installed in a remote cluster. If it should, then in the KCP cluster, it attempts to search for a Secret having the same `operator.kyma-project.io/kyma-name` label and value as in the Manifest CR. + +Thus a Manifest CR like ```yaml apiVersion: operator.kyma-project.io/v1beta2 @@ -20,13 +22,13 @@ spec: remote: true ``` -will use the value `kyma-sample` to lookup a secret with the same value `kyma-sample`. +looks for a Secret with the same `operator.kyma-project.io/kyma-name` label and value `kyma-sample`. -### `.spec.config` +### **.spec.config** -The config reference uses an image layer reference that contains configuration data that can be used to further influence any potential rendering process while the resources are processed by the [declarative library](/internal/declarative/README.md#resource-rendering). It is resolved through a translation of the `ModuleTemplate` to the `Manifest` during the [resolution of the modules](/pkg/module/parse/template_to_module.go) in the `Kyma` control loop. +The config reference uses an image layer reference that contains configuration data that can be used to further influence any potential rendering process while the resources are processed by the [declarative library](../../../internal/declarative/README.md#resource-rendering). It is resolved through a translation of the ModuleTemplate CR to the Manifest CR during the [resolution of the modules](../../../pkg/module/parse/template_to_module.go) in the Kyma CR control loop. -There can be at most one config layer, and it is referenced by the name `config` with type `yaml` as `localOciBlob` or `OCIBlob`: +There can be at most one config layer, and it is referenced by the **name** `config` with **type** `yaml` as `localOciBlob` or `OCIBlob`: ```yaml spec: @@ -49,9 +51,9 @@ spec: version: 0.0.1-6cd5086 ``` -### `.spec.install` +### **.spec.install** -The install layer contains the relevant data required to determine the resources for the [renderer during the manifest reconciliation](/internal/declarative/README.md#resource-rendering). +The installation layer contains the relevant data required to determine the resources for the [renderer during the manifest reconciliation](../../../internal/declarative/README.md#resource-rendering). It is mapped from an access type layer in the descriptor: @@ -77,17 +79,16 @@ install: type: oci-ref ``` -The [internal spec resolver](/internal/manifest/spec_resolver.go) will use this layer to resolve the correct specification style and renderer type from the layer data. +The [internal spec resolver](../../../internal/manifest/spec_resolver.go) uses this layer to resolve the correct specification style and renderer type from the data layer. -### `.spec.resource` +### **.spec.resource** -The resource is the default data that should be initialized for the module and is directly copied from `.spec.data` of the `ModuleTemplate` after normalizing it with the `namespace` for the synchronized module. +The resource is the default data that should be initialized for the module and is directly copied from **.spec.data** of the ModuleTemplate CR after normalizing it with the **namespace** for the synchronized module. -### `.status` +### **.status** -The Manifest status is an unmodified version of the [declarative status](/internal/declarative/README.md#resource-tracking), so the tracking process of the library applies. There is no custom API for this. +The Manifest CR status is an unmodified version of the [declarative status](../../../internal/declarative/README.md#resource-tracking), so the tracking process of the library applies. There is no custom API for this. -### `.metadata.labels` +### **.metadata.labels** * `operator.kyma-project.io/skip-reconciliation`: A label that can be used with the value `true` to disable reconciliation for a module. This will avoid all reconciliations for the Manifest CR. - diff --git a/docs/technical-reference/api/moduleTemplate-cr.md b/docs/technical-reference/api/moduleTemplate-cr.md index f72236b429..78f8f96ae8 100644 --- a/docs/technical-reference/api/moduleTemplate-cr.md +++ b/docs/technical-reference/api/moduleTemplate-cr.md @@ -1,6 +1,8 @@ # ModuleTemplate Custom Resource -The core of our modular discovery, the [ModuleTemplate custom resource (CR)](/api/v1beta2/moduletemplate_types.go) contains 3 main parts that are used to initialize and resolve modules. +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. + +## Configuration ### **.spec.channel** @@ -52,6 +54,7 @@ The `.spec.customStateCheck` field in Kyma Lifecycle Manager is primarily design Imagine a scenario where a module's health is indicated by `status.health` in its CR. In such cases, users can employ the customStateCheck configuration to map the health states to Lifecycle Manager states. Here's an example of YAML configuration: + ```yaml spec: customStateCheck: @@ -68,6 +71,7 @@ In this example, when the module's CR is in the green health state, the correspo The valid mappedState values are defined in the [Kyma CR API](https://github.com/kyma-project/lifecycle-manager/blob/main/api/v1beta2/kyma_types.go#L225-L245). Furthermore, this field supports complex mappings. For instance, if multiple states are needed to determine the `Ready` state, users can define the following customStateCheck: + ```yaml spec: customStateCheck: @@ -87,12 +91,12 @@ The core of any ModuleTemplate CR, the descriptor can be one of the schemas ment By default, it will most likely be easiest to use [Kyma CLI](https://github.com/kyma-project/cli/tree/main) and its `create module` command to create a template with a valid descriptor, but it can also be generated manually, for example using [OCM CLI](https://github.com/open-component-model/ocm/tree/main/cmds/ocm). -### `.spec.mandatory` +### **.spec.mandatory** The `mandatory` field indicates whether the module is installed in all runtime clusters without any interaction from the user. Mandatory modules do not appear in the Kyma CR `.status` and `.spec.modules`, furthermore they have the same configuration across all runtime clusters. -### `operator.kyma-project.io` labels +## `operator.kyma-project.io` labels These are the synchronization labels available on the ModuleTemplate CR: diff --git a/docs/technical-reference/architecture.md b/docs/technical-reference/architecture.md index bd3891c223..09ae63dbca 100644 --- a/docs/technical-reference/architecture.md +++ b/docs/technical-reference/architecture.md @@ -6,10 +6,9 @@ You can compare it with [Operator Lifecycle Manager](https://olm.operatorframewo Lifecycle Manager: -- manages operators free of dependency trees -- reconciles many clusters in Kyma Control Plane (KCP) at a time -- centralizes the effort on managed Runtimes by providing the reconciliation mechanism -- uses the release channels concept to manage operators delivery +- manages a set of independent operators +- reconciles many remote clusters at a time while operating in Kyma Control Plane (KCP) +- uses the release channels concept to manage operators' delivery The diagram shows a sample deployment of KCP in interaction with a Kyma runtime. @@ -19,15 +18,17 @@ To run, Lifecycle Manager uses the following workflow: 1. Each module consists of its manager and custom resource. For example, Keda Manager and a Keda CR represent Keda module. -2. A runtime Admin adds and/or removes modules using a Kyma CR. The Kyma CR repersents Kyma installation on a cluster. It includes a list of installed modules and their statuses. Lifecycle Manager watches the CR and uses the synchronization mechanism to update it on a cluster. Together with the Kyma CR, Lifecycle Manager reads also the kubeconfig Secret to access the Kyma Runtime. +2. A runtime Admin adds and/or removes modules using a Kyma CR. The Kyma CR represents Kyma installation on a cluster. It includes a list of installed modules and their statuses. Lifecycle Manager watches the CR and uses the synchronization mechanism to update it on a cluster. Together with the Kyma CR, Lifecycle Manager reads also the kubeconfig Secret to access the Kyma runtime. -3. To manage a module, Lifecycle Manager requires a ModuleTemplate CR. ModuleTemplate CR contains module's metadata. It represents a module in a particular version. All ModuleTemplate CRs exist in Kyma Control Plane which is the central cluster with Kyma infrastructure. Lifecycle Manager uses those ModuleTemplate CRs to create a Module Catalog with ModuleTemplate CRs available for a particluar Kyma rutime. Lifecycle Manager creates the Module Catalog based on labels, such as `internal`, or `beta`, and uses the synchronization mechanism to update the the Module Catalog porfolio. +3. To manage a module, Lifecycle Manager requires a ModuleTemplate CR. ModuleTemplate CR contains the module's metadata. It represents a module in a particular version. All ModuleTemplate CRs exist in Kyma Control Plane which is the central cluster with Kyma infrastructure. Lifecycle Manager uses those ModuleTemplate CRs to create a Module Catalog with ModuleTemplate CRs available for a particular Kyma runtime. Lifecycle Manager creates the Module Catalog based on labels, such as `internal`, or `beta`, and uses the synchronization mechanism to update the Module Catalog portfolio. -4. Lifecycle Manager reads a ModuleTemplate CR and creates a Manifest CR. The Manifest CR represents resources that make up a module and are to be installed by Lifecycle Manager. The Manifest CR is a rendered module installed on a particular cluster. +4. Lifecycle Manager reads a ModuleTemplate CR and creates a Manifest CR. The Manifest CR represents resources that make up a module and are to be installed on a remote cluster by Lifecycle Manager. + +5. Lifecycle Manager reconciles, namely watches and updates, a set of resources that make up a module. This process lasts until a module is listed in the remote cluster Kyma CR. ## Controllers -Apart from the custom resources, Lifecycle Manager uses also Kyma, Manifest and Watcher controllers: +Apart from the custom resources, Lifecycle Manager uses also Kyma, Manifest, and Watcher controllers: - [Kyma controller](../../internal/controller/kyma_controller.go) - reconciles the Kyma CR which means creating Manifest CRs for each Kyma module enabled in the Kyma CR and deleting them when modules are disabled in the Kyma CR. It is also responsible for synchronising ModuleTemplate CRs between KCP and Kyma runtimes. - [Manifest controller](../../internal/controller/manifest_controller.go) - reconciles the Manifest CRs created by the Kyma controller, which means, installing components specified in the Manifest CR on the target SKR cluster and removing them when the Manifest CRs are flagged for deletion. @@ -35,7 +36,7 @@ Apart from the custom resources, Lifecycle Manager uses also Kyma, Manifest and For more details about Lifecycle Manager controllers, read the [Controllers](controllers.md) document. -## Read more +## Read More The architecture is based on Kubernetes API and resources, and on best practices for building Kubernetes operators. To learn more, read the following: diff --git a/docs/technical-reference/controllers.md b/docs/technical-reference/controllers.md index 1eb347f458..75664a498f 100644 --- a/docs/technical-reference/controllers.md +++ b/docs/technical-reference/controllers.md @@ -4,48 +4,37 @@ This document describes the controllers used by Lifecycle Manager. ## Kyma Controller -[Kyma Controller](../../internal/controller/kyma_controller.go) is dealing with the introspection, interpretation and status update of the [Kyma custom resource (CR)](/api/v1beta2/kyma_types.go). +[Kyma Controller](../../internal/controller/kyma_controller.go) deals with the introspection, interpretation, and status update of the [Kyma custom resource (CR)](../../api/v1beta2/kyma_types.go). Its main responsibilities are: -1. Interpret the `.spec.modules` list and use the correct [ModuleTemplate CR](/api/v1beta2/moduletemplate_types.go) for a module. -2. Translate the ModuleTemplate CR into a [Manifest CR](/api/v1beta2/manifest_types.go) and create it with an OwnerReference to the Kyma CR where the module was listed. +1. Interpret the **.spec.modules** list and use the correct [ModuleTemplate CR](../../api/v1beta2/moduletemplate_types.go) for a module. +2. Translate the ModuleTemplate CR into a [Manifest CR](../../api/v1beta2/manifest_types.go) and create it with an OwnerReference to the Kyma CR where the module was listed. 3. Propagate changes from ModuleTemplate CR updates (e.g. updates to the Module Layers contained in the OCI Descriptor) into the correct Manifest CR and process upgrades, but prohibit downgrades. 4. Track all created Manifest CRs and aggregate the status into a `State`, that reflects the integrity of the Kyma installation managed by Lifecycle Manager. 5. Synchronize all the above changes to the Kyma CR Status as well as available ModuleTemplate CRs into a remote cluster. To determine the cluster to sync to, fields in **.spec.remote** are evaluated. -This allows the use of ModuleTemplate CRs in a cluster managed by Lifecycle Manager -while Kyma Control Plane is in a different cluster. +This allows the use of ModuleTemplate CRs in a cluster managed by Lifecycle Manager while Kyma Control Plane is in a different cluster. ### Remote Synchronization -In order to synchronize remote clusters, the Kyma controller uses the concept of a _virtual_ resource. -The virtual resource is a superset of the specification of the control plane and runtime data of a module. -The synchronization of these is kept up-to-date with every reconciliation, -and will only be triggered if `operator.kyma-project.io/sync=true` label is set to Kyma CR. - -In this case, a so called `SyncContext` is initialized. -Every time the Kyma on the control plane is enqueued for synchronization, -it's spec is merged with the remote specification through our [custom synchronization handlers](/pkg/remote/kyma_synchronization_context.go). -These are not only able to synchronize the Kyma resource in the remote, -but they also replace the specification for all further parts of the reconciliation as a _virtual_ Kyma. -For more information, checkout the `ReplaceWithVirtualKyma` function. +The Kyma CR in Kyma Control Plane shows the initial specification and the current status. To install a module, Lifecycle Manager uses the specification from the remote cluster Kyma CR. ## Mandatory Modules Controllers Lifecycle Manager uses two Mandatory Modules Controllers: + - [Mandatory Modules Installation Controller](../../internal/controller/mandatory_modules_installation_controller.go) deals with the reconciliation of mandatory modules - [Mandatory Modules Deletion Controller](../../internal/controller/mandatory_modules_deletion_controller.go) deals with the deletion of mandatory modules -Since the channel concept does not apply to mandatory modules, the Mandatory Modules Installation Controller fetches all the Mandatory ModuleTemplate CRs without any channel filtering. It then translates the ModuleTemplate CR for the mandatory module to a [Manifest CR](/api/v1beta2/manifest_types.go) with an OwnerReference to the Kyma CR. Similarly to the [Kyma Controller](/internal/controller/kyma_controller.go), +Since the channel concept does not apply to mandatory modules, the Mandatory Modules Installation Controller fetches all the Mandatory ModuleTemplate CRs without any channel filtering. It then translates the ModuleTemplate CR for the mandatory module to a [Manifest CR](../../api/v1beta2/manifest_types.go) with an OwnerReference to the Kyma CR. Similarly to the [Kyma Controller](../../internal/controller/kyma_controller.go), it propagates changes from the ModuleTemplate CR to the Manifest CR. The mandatory ModuleTemplate CR is not synchronized to the remote cluster and the module status does not appear in the Kyma CR status. If a mandatory module needs to be removed from all clusters, the corresponding ModuleTemplate CR needs to be deleted. The Mandatory Module Deletion Controller picks this event up and marks all associated Manifest CRs for deletion. To ensure that the ModuleTemplate CR is not removed immediately, the controller adds a finalizer to the ModuleTemplate CR. Once all associated Manifest CRs are deleted, the finalizer is removed and the ModuleTemplate CR is deleted. - ## Manifest Controller [Manifest Controller](../../internal/controller/manifest_controller.go) deals with the reconciliation and installation of data desired through a Manifest CR, a representation of a single module desired in a cluster. -Since it mainly is a delegation to the [declarative reconciliation library](/internal/declarative/README.md) with certain [internal implementation additions](/internal/manifest/README.md) please look at the respective documentation for these parts to understand them more. +Since it mainly is a delegation to the [declarative reconciliation library](../../internal/declarative/README.md) with certain [internal implementation additions](../../internal/manifest/README.md), please look at the respective documentation for these parts to understand them more. ## 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 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. diff --git a/docs/user-tutorials/01-10-control-plane-quick-start.md b/docs/user-tutorials/01-10-control-plane-quick-start.md index 2cbb6e7ae2..f72cc1cf66 100644 --- a/docs/user-tutorials/01-10-control-plane-quick-start.md +++ b/docs/user-tutorials/01-10-control-plane-quick-start.md @@ -18,7 +18,7 @@ To use Lifecycle Manager in a local setup, you need the following prerequisites: ## Procedure -### Provision a KCP cluster +### Provision a KCP Cluster 1. Provision a local k3d cluster as KCP. By default, a cluster named `k3d-kyma` is created. Run: @@ -35,7 +35,7 @@ To use Lifecycle Manager in a local setup, you need the following prerequisites: 3. Lifecycle Manager exposes metrics that are collected by Prometheus Operator in KCP to provide better observability. To simplify the local setup, you only need to deploy the ServiceMonitor CRD using the following command: ```bash - kubectl apply -f https://raw.githubusercontent.com/prometheus-community/helm-charts/main/charts/kube-prometheus-stack/crds/crd-servicemonitors.yaml + kubectl apply -f https://raw.githubusercontent.com/prometheus-community/helm-charts/main/charts/kube-prometheus-stack/charts/crds/crds/crd-servicemonitors.yaml ``` You can also follow the official [Prometheus Operator quick start](https://prometheus-operator.dev/docs/prologue/quick-start/) guide to deploy a full set of Prometheus Operator features into your cluster. @@ -50,12 +50,15 @@ We recommend deploying Lifecycle Manager with the KCP kustomize profile. You mus kyma alpha deploy -k https://github.com/kyma-project/lifecycle-manager/config/control-plane ``` + > [!NOTE] + > The link to the `kustomization.yaml` file works fine with the command but returns 404 when called directly. + If the deployment was successful, you should see all the required resources. For example: - The `klm-controller-manager` Pod in the `kcp-system` Namespace - A Kyma CR that uses the `regular` channel but without any module configured, sync disabled, named `default-kyma` under `kyma-system` Namespace -### Manage modules in the control-plane mode +### Manage Modules in the Control-Plane Mode To manage Kyma modules in the control-plane mode, Lifecycle Manager requires: diff --git a/docs/user-tutorials/02-10-manage-module-with-custom-resource-policy.md b/docs/user-tutorials/02-10-manage-module-with-custom-resource-policy.md index 3b2cf5b018..9e51944e38 100644 --- a/docs/user-tutorials/02-10-manage-module-with-custom-resource-policy.md +++ b/docs/user-tutorials/02-10-manage-module-with-custom-resource-policy.md @@ -1,4 +1,4 @@ -# Manage module enablement with CustomResourcePolicy +# Manage Module Enablement with CustomResourcePolicy ## Context @@ -37,4 +37,5 @@ Lifecycle Manager will create a corresponding Keda CR in your target cluster and To skip this enablement process, you can set the `customResourcePolicy` flag to `Ignore` when you enable the module. This will result in no Keda CR created in your target cluster. It will also prevent Lifecycle Manager from adding any `spec.resource` to the related Manifest CR. -> **CAUTION:** Setting up the flag to 'Ignore' also means that Lifecycle Manager will not monitor or manage any Keda CR's readiness status. Therefore, you should exercise caution and discretion when using the `Ignore` policy for your module CR. +> [!WARNING] +> Setting up the flag to `Ignore` also means that Lifecycle Manager does not monitor or manage any Keda CR's readiness status. Therefore, you should exercise caution and discretion when using the `Ignore` policy for your module CR. diff --git a/internal/manifest/README.md b/internal/manifest/README.md index d8111f757c..e76a6f25f4 100644 --- a/internal/manifest/README.md +++ b/internal/manifest/README.md @@ -1,10 +1,11 @@ # Internal Manifest Library -This package contains internal reference coding that is used for translating and implementing the Manifest Reconciler parts that are not generically solved by the [declarative library](/internal/declarative/README.md). +This package contains internal reference coding that is used for translating and implementing the Manifest Reconciler parts that are not generically solved by the [declarative library](../declarative/README.md). It contains various aspects to: -1. Translate the [Manifest](/api/v1beta1/manifest_types.go) into a [declarative specification](/internal/declarative/v2/spec.go) in a custom [specification resolver](spec_resolver.go). Use [the layer parsing methods](parse.go) to download and resolve OCI image layers from the Manifest to make them accessible to the declarative library. -2. Lookup the correct Client for Single or Dual Cluster Mode based on the [SKR Client Lookup](skr_client_lookup.go) and a [ClusterClient](client.go) to read Secret Data as if they were a kubeconfig -3. Lookup the correct Keychain to access image layers contained in private registries through a [Keychain](/pkg/ocmextensions/cred.go) -4. Interact with Default Data supplied to the `Manifest` for initializing a module with [Pre/Post-Hooks](custom_resource.go) + +1. Translate the [Manifest CR](../../api/v1beta1/manifest_types.go) into a [declarative specification](../declarative/v2/spec.go) in a custom [specification resolver](spec_resolver.go). Use [the layer parsing methods](parse.go) to download and resolve OCI image layers from the Manifest to make them accessible to the declarative library. +2. Look up the correct Client for Single or Dual Cluster Mode based on the [SKR Client Lookup](skr_client_lookup.go) and a [ClusterClient](client.go) to read Secret Data as if they were a kubeconfig +3. Look up the correct Keychain to access image layers contained in private registries through a [Keychain](../../pkg/ocmextensions/cred.go) +4. Interact with Default Data supplied to the Manifest CR for initializing a module with [Pre/Post-Hooks](custom_resource.go) 5. Check for Module Readiness not only by looking at the resources supplied in the chart, but also to introspect the already mentioned CustomResource using a [custom ReadyCheck](ready_check.go)