From c00e49487c7778b0262f3d037494152cd3810267 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C5=82gorzata=20=C5=9Awieca?= Date: Thu, 18 May 2023 14:04:55 +0200 Subject: [PATCH] Update API version documentation (#606) * Update API version documentation * Add new labels descriptio * Apply Tomek's review suggestions * Apply Tomek's review suggestions --- docs/technical-reference/api/README.md | 36 +++++- docs/technical-reference/api/changelog.md | 23 ++++ docs/technical-reference/api/kyma-cr.md | 107 ++++++++++-------- .../api/moduleTemplate-cr.md | 30 +++-- docs/technical-reference/running-modes.md | 23 ++-- 5 files changed, 140 insertions(+), 79 deletions(-) create mode 100644 docs/technical-reference/api/changelog.md diff --git a/docs/technical-reference/api/README.md b/docs/technical-reference/api/README.md index 3e44ce6123..cf76193c4e 100644 --- a/docs/technical-reference/api/README.md +++ b/docs/technical-reference/api/README.md @@ -1,15 +1,39 @@ # Lifecycle Manager API -The Lifecycle Manager API types considers three major pillars that each deal with a specific aspect of reconciling modules into their corresponding states. +## Overview -1. The introduction of a single entry point CustomResourceDefinition to control a Cluster and it's desired state: The [Kyma custom resource](v1beta1/kyma_types.go) -2. The introduction of a single entry point CustomResourceDefinition to control a Module and it's desired state: The [Manifest custom resource](v1beta1/manifest_types.go) -3. The [ModuleTemplate custom resource](v1beta1/moduletemplate_types.go) which 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. +The Lifecycle Manager API types consist of three major pillars. Each of these deals with a specific aspect of reconciling modules into their corresponding states. -Additionally, we maintain the [Watcher custom resource](v1beta1/watcher_types.go) to define callback functionality for synchronized remote clusters that allows lower latencies before changes are detected by the control-plane. +1. The introduction of a single entry point CustomResourceDefinition to control a cluster and it's desired state: [Kyma custom resource(CR)](../../../api/v1beta2/kyma_types.go). +2. The introduction of a single entry point CustomResourceDefinition to control a module and it's desired state: [Manifest CR](../../../api/v1beta2/manifest_types.go) +3. The [ModuleTemplate CR](../../../api/v1beta2/moduletemplate_types.go) which 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. -Read more about the custom resource defininitions in the respective documents: +Additionally, we maintain the [Watcher custom resource](../../../api/v1beta2/watcher_types.go) to define the callback functionality for synchronized remote clusters that allows lower latencies before changes are detected by the Control Plane. + +## 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) + +## Synchronization of Module Catalog with remote clusters + +Lifecycle Manager ensures that the Module Catalog is correctly synchronized with users' runtimes. +The Module Catalog consists of all modules, represented by ModuleTemplates CR, that are available for a user. The Module Catalog portfolio may vary for different users. +The synchronization mechanism described below is essential to allow users to enable modules in their clusters. +The mechanism is controlled by the set of labels that are configured on Kyma and ModuleTemplate CRs in the Control Plane. The labels are: `operator.kyma-project.io/sync`, `operator.kyma-project.io/internal`, and `operator.kyma-project.io/beta`. +The v1beta2 API introduces three groups of modules: + +- Default modules, synchronized by default. +- Internal modules, synchronized per-cluster only if configured explicitly on the corresponding Kyma CRs. To mark a ModuleTemplate CR as `internal`, use the `operator.kyma-project.io/internal` label and set it to `true`. +- Beta modules, synchronized per-cluster only if configured explicitly on the corresponding Kyma CRs. To mark a ModuleTemplate CR as `beta`, use the `operator.kyma-project.io/beta` label and set it to `true`. + +By default, without any labels configured on Kyma and ModuleTemplate CRs, a ModuleTemplate CR is synchronized with remote clusters. + +**NOTE:** The ModuleTemplate CRs synchronization is enabled only when Lifecycle Manager runs in the [control-plane mode](../../technical-reference/running-modes). Lifecycle Manager running in the single-cluster mode, doesn't require any CR synchronization. + +**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](../api/kyma-cr.md#operatorkyma-projectio-labels) and [the ModuleTemplate CR synchronization labels](../api/moduleTemplate-cr.md#operatorkyma-projectio-labels). diff --git a/docs/technical-reference/api/changelog.md b/docs/technical-reference/api/changelog.md new file mode 100644 index 0000000000..ede79ad3a3 --- /dev/null +++ b/docs/technical-reference/api/changelog.md @@ -0,0 +1,23 @@ +# API Changelog + +This document represents changes introduced by an API version. + +## v1beta1 to v1beta2 + +The v1beta1 to v1beta2 version change introduced the following changes to Lifecycle Manager's custom resoucres (CRs). + +### Kyma CR + +The main change introduced to the Kyma CRD is the removal of the **.spec.sync** attribute. As a result, the v1beta1 **.spec.sync** sub-attributes handling changes as described: + +- **.sync.enabled** - replaced by the `operator.kyma-project.io/sync` label in a Kyma CR. For details, read the [Kyma CR synchronization labels](link TBD) document. +- **.sync.moduleCatalog** - replaced by a combination the `operator.kyma-project.io/sync`, `operator.kyma-project.io/internal`, and `operator.kyma-project.io/beta` labels in Kyma and ModuleTemplate CRs. For details, read the [Kyma CR synchronization labels](link TBD) document. +- **.sync.strategy** - replaced with **sync-strategy** annotation in a Kyma CR. By default, the value for the **sync.strategy** annotation is `local-secret`, other values are used for testing purposes only. +- **.sync.namespace** - replaced with a `sync-namespace` command-line flag for Lifecycle Manager. It means that a user can no longer configure the Namespace synchronized with a particular Kyma CR. The Namespace is the same for all Kyma CRs in a given Lifecycle Manager instance, and a user can't change it. +- **.sync.noModuleCopy** - removed. Currently the **.spec.modules[]** for a remote Kyma CR is always initialized as empty. + +### ModuleTemplate CR + +In the ModuleTemplate CRD the changes relate to the **sync.target** attribute: + +- `.sync.target` - replaced with a `in-kcp-mode` command-line flag for Lifecycle Manager. It means that a user can no longer configure the ModuleTemplate synchronization. The configuration is the same for all ModuleTemplate CRs in a given Lifecycle Manager instance, and a user can't change it. diff --git a/docs/technical-reference/api/kyma-cr.md b/docs/technical-reference/api/kyma-cr.md index 59882b9e58..a19bf604d5 100644 --- a/docs/technical-reference/api/kyma-cr.md +++ b/docs/technical-reference/api/kyma-cr.md @@ -1,18 +1,18 @@ # Kyma Custom Resource -The [Kyma](../../../api/v1beta1/kyma_types.go) custom resource (CR) 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) contains 3 fields that are together used to declare the desired state of a cluster: -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 (which we will get to later) serving as a link to a `ModuleTemplate`. -Additionally one can add a specific channel (if `.spec.channel`) should not be used. -On Top of that one can specify a `controller`, which serves as a Multi-Tenant Enabler. -It can be used to only listen to ModuleTemplates provided under the same controller-name. Last but not least, it includes a `customResourcePolicy` which can be used for specifying defaulting behavior when initialising modules in a cluster. +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` and `.spec.modules[].channel` +### **.spec.channel** and **.spec.modules[].channel** -The `.spec.channel` attribute is used in conjunction with the [release channels](https://github.com/kyma-project/community/tree/main/concepts/modularization#release-channels). The channel that is used for a Kyma resource will always be used as the default in case no other specific channel is used. +The **.spec.channel** attribute is used in conjunction with the [release channels](https://github.com/kyma-project/community/tree/main/concepts/modularization#release-channels). The channel that is used for the Kyma CR will always be used as the default in case no other specific channel is used. -This means that a Kyma that has the spec +This means that a Kyma CR that has the following spec: ```yaml spec: @@ -24,7 +24,7 @@ spec: will attempt to look up the modules `keda` and `serverless` in the `alpha` release channel. -However, when specifying channels specifically through `.spec.modules[].channel`, the latter one is used instead. +However, if you specify channels using the **.spec.modules[].channel** attribute, the latter one is used instead. ```yaml spec: @@ -35,13 +35,14 @@ spec: - name: serverless ``` -In this case the relevant channel will be `regular` for `keda`, but not for `serverless` +In this case, the relevant channel will be `regular` for `keda`, but not for `serverless`. -### `.spec.modules` +### **.spec.modules** -The module list is used to define the desired set of all modules. This is mainly derived from the attribute `.spec.modules[].name` 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: -Let's take a look at this simplified ModuleTemplate: ```yaml apiVersion: operator.kyma-project.io/v1beta1 kind: ModuleTemplate @@ -58,29 +59,37 @@ spec: name: kyma-project.io/module/sample ``` -The module mentioned above can be referenced in one of 3 ways -1. The label value of `operator.kyma-project.io/module-name` +The module mentioned above can be referenced in one of the following ways: + +1. The label value of `operator.kyma-project.io/module-name`: + ```yaml spec: channel: regular modules: - name: module-name-from-label ``` -2. The Name or Namespace/Name of a ModuleTemplate + +2. The Name or Namespace/Name of a ModuleTemplate CR: + ```yaml spec: channel: regular modules: - name: moduletemplate-sample ``` + or + ```yaml spec: channel: regular modules: - name: default/moduletemplate-sample ``` -3. The Fully Qualified Name of the descriptor as located in `.spec.descriptor.component.name` + +3. The fully qualified name of the descriptor as located in **.spec.descriptor.component.name**: + ```yaml spec: channel: regular @@ -88,32 +97,33 @@ The module mentioned above can be referenced in one of 3 ways - name: kyma-project.io/module/sample ``` -### `.spec.modules[].customResourcePolicy` +### **.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. +This allows users to be fully flexible in regard to when and how to initialize their module. -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: `customResourcePolicy` 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. -This allows users to be fully flexible when and how to initialize their Module. +### **.status.state** -### `.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` is a simple representation of the state of the entire `Kyma` installation. It is defined as an aggregated status that is one of `Ready`, `Processing`, `Error` and `Deleting`, based on the status of _all_ `Manifest` resources 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](../controllers/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` will always be reported based on the last reconciliation loop of the [Kyma controller](../controllers/kyma_controller.go). It will be set to `Ready` only if all installations were succesfully executed and are consistent at the time of the reconciliation. +### **.status.conditions** -### `.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`). 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: -Currently, we maintain conditions for -- Module (`Manifest`) synchronization -- Module Catalog (`ModuleTemplate`) synchronization +- Module (Manifest CR) synchronization +- Module Catalog (ModuleTemplate CR) synchronization - Watcher Installation Consistency -We also calculate `.status.state` readiness based on all the conditions available. +We also calculate **.status.state** readiness based on all the conditions available. -### `.status.modules` +### **.status.modules** -This describes the tracked modules that should be installed within a `Kyma` cluster. Each tracked module is based on one entry in `.spec.modules` and represents the resolved `Manifest` that is based on a given `ModuleTemplate` in a release `channel`: +This describes the tracked modules that should be installed within a Kyma cluster. Each tracked module is based on one entry in **.spec.modules** and represents the resolved Manifest CR that is based on a given ModuleTemplate CR in a release channel: ```yaml apiVersion: operator.kyma-project.io/v1beta1 @@ -142,25 +152,28 @@ status: version: v0.2.3 ``` -As can be seen above, not only is the module name resolved to a unique `fqdn`, it also represents the active `channel`, `version` and `state` which is a direct tracking to the `Manifest` `.status.state`. The Kyma `Ready` state can only be achieved if all tracked modules are in `Ready` themselves. +The above example shows that not only the module name is resolved to a unique `fqdn`, it also represents the active `channel`, `version` and `state` which is a direct tracking to the **.status.state** in the Manifest CR. The Kyma CR `Ready` state can only be achieved if all tracked modules are `Ready` themselves. -The `Manifest` can be directly observed by looking at the `metadata` and `apiVersion` and `kind` which can be used to dynamically resolve the module. +The Manifest CR can be directly observed by looking at the **metadata**, **apiVersion**, and **kind** which can be used to dynamically resolve the module. -The same is done for the `ModuleTemplate`. The actual one that is used as template to initialize and synchronize the module similarly is referenced by `apiVersion`, `kind` and `metadata`. +The same is done for the ModuleTemplate CR. The actual one that is used as a template to initialize and synchronize the module similarly is referenced by **apiVersion**, **kind**, and **metadata**. -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 a new field: `lastOperation`. This contains not only a timestamp of the last change (which allows 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`. +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 to this 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. -### Label-based side-effects from `operator.kyma-project.io` +### `operator.kyma-project.io` labels -There are various overarching features that can be enabled/disabled or provided as hints to the reconciler by providing a specific label key and value to the `Kyma` and it's related resources. To take a look at labels, use the matching [API label reference](v1beta1/operator_labels.go). +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/v1beta2/operator_labels.go). -The most important ones include, but are not limited to: +The most important labels include, but are not limited to: -- `operator.kyma-project.io/Kyma`: the [finalizer](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) set by lifecycle manager to deal with `Kyma` cleanup -- `operator.kyma-project.io/kyma-name`: An identifier that can be set on a secret to identify correct cluster access kubeconfigs to be used during reconciliation. -- `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 value `true` to completely disable reconciliation for a `Kyma` resource. Can also be used on the `Manifest` to disable a specific module. This will avoid all reconciliations for the entire Kyma `Resource` or `Manifest` resource. Note that even though reconciliation for `Kyma` might be disabled, the `Manifest` 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 be 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. \ No newline at end of file +- `operator.kyma-project.io/Kyma`: the [finalizer](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) set by Lifecycle Manager to deal with the Kyma CR cleanup +- `operator.kyma-project.io/kyma-name`: An identifier that can be set on a Secret to identify correct cluster access kubeconfigs to be used during reconciliation. +- `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/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/moduleTemplate-cr.md b/docs/technical-reference/api/moduleTemplate-cr.md index 19843f51e2..5fe09e96a5 100644 --- a/docs/technical-reference/api/moduleTemplate-cr.md +++ b/docs/technical-reference/api/moduleTemplate-cr.md @@ -1,12 +1,12 @@ # ModuleTemplate Custom Resource -The core of our modular discovery, the [ModuleTemplate](../../../api/v1beta1/moduletemplate_types.go) contains 3 main parts that are used to initialize and resolve modules. +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. -### `.spec.channel` +### **.spec.channel** -The channel that the ModuleTemplate is registered in. It is used alongside the channel attributes of the `Kyma` to match up a module and a channel. +The channel that a ModuleTemplate CR is registered in. It is used alongside the channel attributes of the Kyma CR to match up a module and a channel. -For a ModuleTemplate +For the following ModuleTemplate CR: ```yaml apiVersion: operator.kyma-project.io/v1beta1 @@ -17,11 +17,11 @@ spec: channel: regular ``` -the module will be referenced by any Kyma asking for it in the `regular` channel. +the module will be referenced by any Kyma CR asking for it in the `regular` channel. -### `.spec.data` +### **.spec.data** -The data that should be used for initialization of a CustomResource after the module has been installed. It is only used if the `customResourcePolicy` is set to `CreateAndDelete` and it is filled with a valid CustomResource (that can be of any type available in the API-Server _after_ module initialization). If set to `Ignore` by the module specification of `Kyma` it is entirely ignored, even when filled. +The data that should be used for the initialization of a custom resource after the module has been installed. It is only used if the `customResourcePolicy` is set to `CreateAndDelete` and it is filled with a valid custom resource (that can be of any type available in the API-Server _after_ module initialization). If set to `Ignore` by the module specification of the Kyma CR, it is entirely ignored, even when filled. A (partial) example could look like this: @@ -43,10 +43,18 @@ spec: memory: "150Mi" ``` -The `namespace` of the resource mentioned in `.spec.data` will be defaulted to `.metadata.namespace` of the referencing `Kyma` if not filled, otherwise it will be respected. All other attributes (including `.metadata.name` and `apiVersion` and `kind`) are taken over as is. Note that since it behaves similarly to a `template` any subresources, like `status` are ignored, even if specified in the field. +If not specified, the **namespace** of the resource mentioned in **.spec.data** will be controlled by the `sync-namespace` flag; otherwise, it will be respected. All other attributes (including **.metadata.name**, **apiVersion**, and **kind**) are taken over as stated. Note that since it behaves similarly to a `template`, any subresources, such as **status**, are ignored, even if specified in the field. -### `.spec.descriptor` +### **.spec.descriptor** -The core of any ModuleTemplate, the descriptor can be one of the schemas mentioned in the latest version of the [OCM Software Specification](https://ocm.software/spec/). While it is a `runtime.RawExtension` in the Go types, it will be resolved via ValidatingWebhook into an internal descriptor with the help of the official [OCM library](https://github.com/open-component-model/ocm). +The core of any ModuleTemplate CR, the descriptor can be one of the schemas mentioned in the latest version of the [OCM Software Specification](https://ocm.software/spec/). While it is a `runtime.RawExtension` in the Go types, it will be resolved via ValidatingWebhook into an internal descriptor with the help of the official [OCM library](https://github.com/open-component-model/ocm). -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, e.g. with [OCM CLI](https://github.com/open-component-model/ocm/tree/main/cmds/ocm) +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). + +### `operator.kyma-project.io` labels + +These are the synchronization labels available on the ModuleTemplate CR: + +- `operator.kyma-project.io/sync`: A boolean value. If set to `false`, this ModuleTemplate CR is not synchronized with any remote cluster. The default value is `true`. +- `operator.kyma-project.io/internal`: A boolean value. If set to `true`, marks the ModuleTemplate CR as an `internal` module. It is then synchronized only for these remote clusters which are managed by the Kyma CR with the same `operator.kyma-project.io/internal` label explicitly set to `true`. The default value is `false`. +- `operator.kyma-project.io/beta` A boolean value. If set to `true`, marks the ModuleTemplate CR as a `beta` module. It is then synchronized only for these remote clusters which are managed by the Kyma CR with the same `operator.kyma-project.io/beta` label explicitly set to `true`. The default value is `false`. diff --git a/docs/technical-reference/running-modes.md b/docs/technical-reference/running-modes.md index 7e32d62814..e38360dabe 100644 --- a/docs/technical-reference/running-modes.md +++ b/docs/technical-reference/running-modes.md @@ -1,22 +1,15 @@ # Running Modes -## Deployment / Delivery models +Lifecycle Manager can run in two modes: -lifecycle-manager (and module operators) can run in 2 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](../technical-reference/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. -- in-cluster - regular deployment in the kubernetes cluster where kyma should be deployed, control-plane manages itself -- control-plane - deployment on central kubernetes cluster that manages multiple kyma installations remotely (installing kyma on the remote clusters based on a secret providing connectivity details) +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. -Which mode is used is based on the lifecycle-manager deployment argument (`--in-kcp-mode`), when it's enabled, Module will be installed in the remote cluster. +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. -They both target different use cases. While in-cluster mode is useful for classical deployment of kyma with 1 cluster in play, the general consensus is that for large scale operations, it is recommended to either use an aggregated API-Server or use Clusters to manage other Clusters (nowadays known as Control-Plane) - -This means that, depending on your environment you might be running lifecycle-manager in one or the other mode. - -For local development, as well as for testing and verification purposes in integration testing, we recommend to use single-cluster mode. For E2E Testing, -and testing of scalability as well as remote reconciliation, we recommend the use of a separate control-plane cluster. - -### Release Lifecycles for Modules +## 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. As such, all module interactions are abstracted through the [ModuleTemplate](api/v1beta1/moduletemplate_types.go). @@ -26,12 +19,12 @@ This abstraction of a template is used for generically deploying instances of a 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 +## 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. -### Comparison to the Old Reconciler +## 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.