diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000000..e3d1e8a069 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,31 @@ +# This is a configuration file for the markdownlint. You can use this file to overwrite the default settings. +# MD004 checks if the asterisk symbol is used for unordered list items +MD004: + style: asterisk +# MD013 is set to false by default because many files include lines longer than the conventional 80 character limit +MD013: false +# MD024 disable the Multiple headings with the same content rule +MD024: false +# MD029 Set to false because it generates issues with longer lists +MD029: false +# MD033 is set to false to allow for inline HTML elements in a Markdown document +MD033: false +# MD044 is used to set capitalization for particular words. You can determine whether it should be used also for code blocks and HTML elements +MD044: + code_blocks: false + html_elements: false + names: + - Kyma + - Kubernetes + - ConfigMap + - CronJob + - CustomResourceDefinition + - Ingress + - Node + - PodPreset + - Pod + - ProwJob + - Secret + - ServiceBinding + - ServiceClass + - ServiceInstance \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 6b3bb9f2d5..9191d99436 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,27 +4,27 @@ The `docs` folder contains documentation on the Lifecycle Manager project. -## Table of contents +## Table of Contents The table of contents lists all the documents in repository with their short description. -- [Developer tutorials](developer-tutorials/README.md) - a directory containing infrastructure-related guides for developers - - [Provide credential for private OCI registry authentication](developer-tutorials/config-private-registry.md) - - [Local test setup in the control-plane mode using k3d](developer-tutorials/local-test-setup.md) - - [Create a test environment on Google Container Registry (GCR)](developer-tutorials/prepare-gcr-registry.md) - - [Provision cluster and OCI registry](developer-tutorials/provision-cluster-and-registry.md) - - [Enable Webhooks in Lifecycle Manager](developer-tutorials/starting-operator-with-webhooks.md) -- Technical reference - a directory with techncial details on Lifecycle Manager, such as architecture, APIs, or running modes - - [API](technical-reference/api/README.md) - a directory with the description of Lifecycle Manager's custom resources (CRs) - - [Kyma CR](technical-reference/api/kyma-cr.md) - - [Manifest CR](technical-reference/api/manifest-cr.md) - - [ModuleTemplate CR](technical-reference/api/moduleTemplate-cr.md) - - [Architecture](technical-reference/architecture.md) - describes Lifecycle Manager's architecture - - [Controllers](technical-reference/controllers.md) - describes Kyma, Manifest and Watcher controllers - - [Running Modes](technical-reference/running-modes.md) - describes Lifecycle Manager's running modes - - [Declarative Reconciliation Library Reference Documentation](/internal/declarative/README.md) - - [Internal Manifest Reconciliation Library Extensions](/internal/manifest/README.md) -- User tutorials - - [Managing module enablement with the CustomResourcePolicy](user-tutorials/02-10-manage-module-with-custom-resource-policy.md) - - [Quick Start](user-tutorials/01-10-control-plane-quick-start.md) -- [Modularization](modularization.md) - describes the modularization concept and its building blocks in the context of Lifecycle Manager +* [Developer tutorials](developer-tutorials/README.md) - a directory containing infrastructure-related guides for developers + * [Provide credential for private OCI registry authentication](developer-tutorials/config-private-registry.md) + * [Local test setup in the control-plane mode using k3d](developer-tutorials/local-test-setup.md) + * [Create a test environment on Google Container Registry (GCR)](developer-tutorials/prepare-gcr-registry.md) + * [Provision cluster and OCI registry](developer-tutorials/provision-cluster-and-registry.md) + * [Enable Webhooks in Lifecycle Manager](developer-tutorials/starting-operator-with-webhooks.md) +* Technical reference - a directory with techncial details on Lifecycle Manager, such as architecture, APIs, or running modes + * [API](technical-reference/api/README.md) - a directory with the description of Lifecycle Manager's custom resources (CRs) + * [Kyma CR](technical-reference/api/kyma-cr.md) + * [Manifest CR](technical-reference/api/manifest-cr.md) + * [ModuleTemplate CR](technical-reference/api/moduleTemplate-cr.md) + * [Architecture](technical-reference/architecture.md) - describes Lifecycle Manager's architecture + * [Controllers](technical-reference/controllers.md) - describes Kyma, Manifest and Watcher controllers + * [Running Modes](technical-reference/running-modes.md) - describes Lifecycle Manager's running modes + * [Declarative Reconciliation Library Reference Documentation](/internal/declarative/README.md) + * [Internal Manifest Reconciliation Library Extensions](/internal/manifest/README.md) +* User tutorials + * [Managing module enablement with the CustomResourcePolicy](user-tutorials/02-10-manage-module-with-custom-resource-policy.md) + * [Quick Start](user-tutorials/01-10-control-plane-quick-start.md) +* [Modularization](modularization.md) - describes the modularization concept and its building blocks in the context of Lifecycle Manager diff --git a/docs/developer-tutorials/README.md b/docs/developer-tutorials/README.md index ae1f5da103..4554b3bde3 100644 --- a/docs/developer-tutorials/README.md +++ b/docs/developer-tutorials/README.md @@ -1,3 +1,3 @@ -# Developer tutorials +# Developer Tutorials This directory contains infrastructure-related developer tutorials around Lifecycle Manager. diff --git a/docs/developer-tutorials/config-private-registry.md b/docs/developer-tutorials/config-private-registry.md index eec99dc2b2..42edc0167f 100644 --- a/docs/developer-tutorials/config-private-registry.md +++ b/docs/developer-tutorials/config-private-registry.md @@ -1,4 +1,4 @@ -# Provide credentials for private OCI registry authentication +# Provide Credentials for Private OCI Registry Authentication ## Context @@ -16,7 +16,7 @@ Before you proceed, prepare your registry credentials. Check also how to deal wi ## Procedure -### Prepare a docker-registry Secret manifest +### Prepare a docker-registry Secret Manifest 1. Create a docker-registry Secret manifest. Run: @@ -39,7 +39,7 @@ Before you proceed, prepare your registry credentials. Check also how to deal wi 3. Deploy the Secret on the same cluster where the ModuleTemplate CR is to be located. For example, if the ModuleTemplate CR is on the SKR cluster, then the Secret should be deployed to the SKR. Otherwise, it should be deployed to the KCP cluster. -### Generate a ModuleTemplate CR with the `oci-registry-cred` label +### Generate a ModuleTemplate CR with the `oci-registry-cred` Label The `oci-registry-cred` label in a ModuleTemplate CR allows Lifecycle Manager to parse the Secret label selector and propagate it to the Manifest CR so that Lifecycle Manager knows which credentials Secret to look up. diff --git a/docs/developer-tutorials/local-test-setup.md b/docs/developer-tutorials/local-test-setup.md index 427e6c5dab..0dfb213166 100644 --- a/docs/developer-tutorials/local-test-setup.md +++ b/docs/developer-tutorials/local-test-setup.md @@ -1,26 +1,26 @@ -# Local test setup in the control-plane mode using k3d +# Local test Setup in the control-plane Mode Using k3d ## Context This tutorial shows how to configure a fully working e2e test setup including the following components: -- Lifecycle Manager -- Runtime Watcher on a remote cluster -- `template-operator` on a remote cluster as an example +* Lifecycle Manager +* Runtime Watcher on a remote cluster +* `template-operator` on a remote cluster as an example This setup is deployed with the following security features enabled: -- Strict mTLS connection between Kyma Control Plane (KCP) and SKR clusters -- SAN Pinning (SAN of client TLS certificate needs to match the DNS annotation of a corresponding Kyma CR) +* Strict mTLS connection between Kyma Control Plane (KCP) and SKR clusters +* SAN Pinning (SAN of client TLS certificate needs to match the DNS annotation of a corresponding Kyma CR) > **NOTE:** If you want to use remote clusters instead of a local k3d setup or external registries, please refer to the following guides for the cluster and registry setup: > -> - [Provision cluster and OCI registry](provision-cluster-and-registry.md) -> - [Create a test environment on Google Container Registry (GCR)](prepare-gcr-registry.md) +> * [Provision cluster and OCI registry](provision-cluster-and-registry.md) +> * [Create a test environment on Google Container Registry (GCR)](prepare-gcr-registry.md) ## Procedure -### KCP cluster setup +### KCP Cluster Setup 1. Create a local KCP cluster: @@ -137,7 +137,7 @@ This setup is deployed with the following security features enabled: kubectl apply -f ./template.yaml ``` -### SKR cluster setup +### SKR Cluster Setup Create a local Kyma runtime (SKR) cluster: @@ -145,7 +145,7 @@ Create a local Kyma runtime (SKR) cluster: k3d cluster create skr-local ``` -### Create a Kyma CR and a remote Secret +### Create a Kyma CR and a Remote Secret 1. Switch the context for using the KCP cluster: @@ -216,7 +216,7 @@ k3d cluster create skr-local -### Watcher and module installation verification +### Watcher and Module Installation Verification Check the Kyma CR events to verify if the `SKRWebhookIsReady` condition is set to `True`. Also make sure if the state of the `template-operator` is `Ready` and check the overall `state`. @@ -257,7 +257,7 @@ status: state: Ready ``` -### (Optional) Check the functionality of the Watcher component +### (Optional) Check the Functionality of the Watcher Component 1. Switch the context to use the SKR cluster: diff --git a/docs/developer-tutorials/prepare-gcr-registry.md b/docs/developer-tutorials/prepare-gcr-registry.md index f83c89a755..7101ebca2f 100644 --- a/docs/developer-tutorials/prepare-gcr-registry.md +++ b/docs/developer-tutorials/prepare-gcr-registry.md @@ -1,4 +1,4 @@ -# Create a test environment on Google Container Registry (GCR) +# Create a test Environment on Google Container Registry (GCR) ## Context @@ -10,7 +10,7 @@ This tutorial assumes that you have a GCP project called `sap-kyma-jellyfish-dev ## Procedure -### Create your repository +### Create your Repository 1. Create an Artifact Registry repository. For tutorial purposes, call it `operator-test`. @@ -27,7 +27,7 @@ This tutorial assumes that you have a GCP project called `sap-kyma-jellyfish-dev --location=europe-west3 --member=allUsers --role=roles/artifactregistry.reader ``` -### Authenticate locally and create a service account in Google Cloud +### Authenticate Locally and Create a Service Account in Google Cloud 1. Under the assumption you're [creating and using a service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) called `operator-test-sa`, authenticate against your registry: diff --git a/docs/developer-tutorials/provision-cluster-and-registry.md b/docs/developer-tutorials/provision-cluster-and-registry.md index 9113940187..74a48efe92 100644 --- a/docs/developer-tutorials/provision-cluster-and-registry.md +++ b/docs/developer-tutorials/provision-cluster-and-registry.md @@ -1,4 +1,4 @@ -# Provision a cluster and OCI registry +# Provision a Cluster and OCI Registry ## Context @@ -8,7 +8,7 @@ For the control-plane mode, with Kyma Control Plane (KCP) and Kyma runtime (SKR) ## Procedure -### Local cluster setup +### Local Cluster Setup 1. Create a `k3d` cluster: @@ -31,14 +31,14 @@ For the control-plane mode, with Kyma Control Plane (KCP) and Kyma runtime (SKR) 3. Set the `IMG` environment variable for the `docker-build` and `docker-push` commands, to make sure images are accessible by local k3d clusters. - - For the **single-cluster mode**: + * For the **single-cluster mode**: ```sh # pointing to KCP registry in dual cluster mode export IMG=op-kcp-registry.localhost:8888/unsigned/operator-images ``` - - For the **control-plane mode**: + * For the **control-plane mode**: ```sh # pointing to SKR registry in dual cluster mode @@ -47,7 +47,7 @@ For the control-plane mode, with Kyma Control Plane (KCP) and Kyma runtime (SKR) 4. Once you pushed your image, verify the content. For browsing through the content of the local container registry, use, for example, `http://op-kcp-registry.localhost:8888/v2/_catalog?n=100`. -### Remote cluster setup +### Remote Cluster Setup Learn how to use a Gardener cluster for testing. diff --git a/docs/developer-tutorials/starting-operator-with-webhooks.md b/docs/developer-tutorials/starting-operator-with-webhooks.md index cb878ffd6b..99b7c63178 100644 --- a/docs/developer-tutorials/starting-operator-with-webhooks.md +++ b/docs/developer-tutorials/starting-operator-with-webhooks.md @@ -1,4 +1,4 @@ -# Enable webhooks in Lifecycle Manager +# Enable Webhooks in Lifecycle Manager ## Context diff --git a/docs/technical-reference/api/README.md b/docs/technical-reference/api/README.md index 6be86751e1..bc330d1ffe 100644 --- a/docs/technical-reference/api/README.md +++ b/docs/technical-reference/api/README.md @@ -14,11 +14,11 @@ Additionally, we maintain the [Watcher CR](/api/v1beta2/watcher_types.go) to def 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 CR](kyma-cr.md) +* [Manifest CR](manifest-cr.md) +* [ModuleTemplate CR](moduleTemplate-cr.md) -## Synchronization of Module Catalog with remote clusters +## Synchronization of Module Catalog with Remote Clusters Lifecycle Manager ensures 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. @@ -26,9 +26,9 @@ The synchronization mechanism described below is essential to allow users to ena 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`. +* 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. diff --git a/docs/technical-reference/api/changelog.md b/docs/technical-reference/api/changelog.md index 0ce9aea41c..fcef05d507 100644 --- a/docs/technical-reference/api/changelog.md +++ b/docs/technical-reference/api/changelog.md @@ -10,13 +10,13 @@ The v1beta1 to v1beta2 version change introduced the following changes to Lifecy 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.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. +* **.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.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. +* `.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 51a58f2aed..ddf9da8dfc 100644 --- a/docs/technical-reference/api/kyma-cr.md +++ b/docs/technical-reference/api/kyma-cr.md @@ -2,9 +2,9 @@ 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. -- **.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. +* **.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. @@ -64,7 +64,7 @@ spec: The module mentioned above can be referenced in one of the following ways: -- The label value of `operator.kyma-project.io/module-name`: +* The label value of `operator.kyma-project.io/module-name`: ```yaml spec: @@ -73,7 +73,7 @@ The module mentioned above can be referenced in one of the following ways: - name: module-name-from-label ``` -- The name or namespace/name of a ModuleTemplate CR: +* The name or namespace/name of a ModuleTemplate CR: ```yaml spec: @@ -91,7 +91,7 @@ The module mentioned above can be referenced in one of the following ways: - name: default/moduletemplate-sample ``` -- 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: @@ -118,9 +118,9 @@ The conditions represent individual elements of the reconciliation that can eith Currently, we maintain conditions for: -- Module (Manifest CR) synchronization -- Module Catalog (ModuleTemplate CR) synchronization -- Watcher Installation Consistency +* Module (Manifest CR) synchronization +* Module Catalog (ModuleTemplate CR) synchronization +* Watcher Installation Consistency We also calculate the **.status.state** readiness based on all the conditions available. @@ -165,18 +165,18 @@ To observe not only how the state of the `synchronization` but the entire reconc 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). 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 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`. +* `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 c422fd6b79..1ccefaeaa4 100644 --- a/docs/technical-reference/api/moduleTemplate-cr.md +++ b/docs/technical-reference/api/moduleTemplate-cr.md @@ -96,10 +96,10 @@ By default, it will most likely be easiest to use [Kyma CLI](https://github.com/ 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: -- `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`. +* `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/architecture.md b/docs/technical-reference/architecture.md index 6ad094eeb5..261197d12f 100644 --- a/docs/technical-reference/architecture.md +++ b/docs/technical-reference/architecture.md @@ -6,9 +6,9 @@ You can compare it with [Operator Lifecycle Manager](https://olm.operatorframewo Lifecycle Manager: -- 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 +* 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. @@ -30,10 +30,10 @@ To run, Lifecycle Manager uses the following workflow: 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 in the target SKR cluster and removing them when the Manifest CRs are flagged for deletion. -- [Purge controller](../../internal/controller/purge/controller.go) - reconciles the Kyma CRs that are marked for deletion longer than the grace period, which means purging all the resources deployed by Lifecycle Manager in the target SKR cluster. -- [Watcher controller](../../internal/controller/watcher/controller.go) - reconciles the Watcher CR which means creating Istio Virtual Service resources in KCP when a Watcher CR is created and removing the same resources when the Watcher CR is deleted. This is done to configure the routing of the messages that come from the watcher agent, installed on each Kyma runtime, and go to a listener agent deployed in KCP. +* [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 in the target SKR cluster and removing them when the Manifest CRs are flagged for deletion. +* [Purge controller](../../internal/controller/purge/controller.go) - reconciles the Kyma CRs that are marked for deletion longer than the grace period, which means purging all the resources deployed by Lifecycle Manager in the target SKR cluster. +* [Watcher controller](../../internal/controller/watcher/controller.go) - reconciles the Watcher CR which means creating Istio Virtual Service resources in KCP when a Watcher CR is created and removing the same resources when the Watcher CR is deleted. This is done to configure the routing of the messages that come from the watcher agent, installed on each Kyma runtime, and go to a listener agent deployed in KCP. For more details about Lifecycle Manager controllers, read the [Controllers](controllers.md) document. @@ -41,7 +41,7 @@ For more details about Lifecycle Manager controllers, read the [Controllers](con The architecture is based on Kubernetes API and resources, and on best practices for building Kubernetes operators. To learn more, read the following: -- [Kubebuilder](https://kubebuilder.io/) -- [Operator SDK](https://sdk.operatorframework.io/docs/building-operators/golang/) -- [Best practices for building Kubernetes Operators and stateful apps](https://cloud.google.com/blog/products/containers-kubernetes/best-practices-for-building-kubernetes-operators-and-stateful-apps) -- [Operator SDK - Best Practices](https://sdk.operatorframework.io/docs/best-practices/). +* [Kubebuilder](https://kubebuilder.io/) +* [Operator SDK](https://sdk.operatorframework.io/docs/building-operators/golang/) +* [Best practices for building Kubernetes Operators and stateful apps](https://cloud.google.com/blog/products/containers-kubernetes/best-practices-for-building-kubernetes-operators-and-stateful-apps) +* [Operator SDK - Best Practices](https://sdk.operatorframework.io/docs/best-practices/). diff --git a/docs/technical-reference/controllers.md b/docs/technical-reference/controllers.md index 84ab42a0e4..e9fb60cfb3 100644 --- a/docs/technical-reference/controllers.md +++ b/docs/technical-reference/controllers.md @@ -24,8 +24,8 @@ The Kyma CR in Kyma Control Plane shows the initial specification and the curren Lifecycle Manager uses two Mandatory Modules Controllers: -- [Mandatory modules installation controller](../../internal/controller/mandatorymodule/installation_controller.go) deals with the reconciliation of mandatory modules -- [Mandatory modules deletion controller](../../internal/controller/mandatorymodule/deletion_controller.go) deals with the deletion of mandatory modules +* [Mandatory modules installation controller](../../internal/controller/mandatorymodule/installation_controller.go) deals with the reconciliation of mandatory modules +* [Mandatory modules deletion controller](../../internal/controller/mandatorymodule/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), 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. @@ -36,8 +36,10 @@ it propagates changes from the ModuleTemplate CR to the Manifest CR. The mandato 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. ## Purge Controller + [Purge controller](../../internal/controller/purge/controller.go) is responsible for handling the forced cleanup of deployed resources in a remote cluster when its Kyma CR is marked for deletion. Suppose a Kyma CR has been marked for deletion for longer than the grace period (default is 5 minutes). In that case, the controller resolves the remote client for the cluster, retrieves all relevant CRs deployed on the cluster, and removes finalizers, allowing the resources to be garbage collected. This ensures that all associated resources are properly purged, maintaining the integrity and cleanliness of the cluster. + ## 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. diff --git a/docs/technical-reference/running-modes.md b/docs/technical-reference/running-modes.md index 600606f2ed..3f9dd7ccd5 100644 --- a/docs/technical-reference/running-modes.md +++ b/docs/technical-reference/running-modes.md @@ -2,8 +2,8 @@ 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 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. 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. @@ -11,7 +11,7 @@ Use the single-cluster mode for local development and testing. For E2E testing, ## 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 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/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). 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 6a57445858..9a337dd20c 100644 --- a/docs/user-tutorials/01-10-control-plane-quick-start.md +++ b/docs/user-tutorials/01-10-control-plane-quick-start.md @@ -4,17 +4,17 @@ This quick start guide shows how to: -- provision a Kyma Control Plane (KCP) cluster and deploy Lifecycle Manager using Kyma CLI -- deploy a ModuleTemplate CR -- manage modules using Kyma CLI +* provision a Kyma Control Plane (KCP) cluster and deploy Lifecycle Manager using Kyma CLI +* deploy a ModuleTemplate CR +* manage modules using Kyma CLI ## Prerequisites To use Lifecycle Manager in a local setup, you need the following prerequisites: -- [k3d](https://k3d.io/) -- [istioctl](https://istio.io/latest/docs/setup/install/istioctl/) -- [Kyma CLI](https://kyma-project.io/#/04-operation-guides/operations/01-install-kyma-CLI) +* [k3d](https://k3d.io/) +* [istioctl](https://istio.io/latest/docs/setup/install/istioctl/) +* [Kyma CLI](https://kyma-project.io/#/04-operation-guides/operations/01-install-kyma-CLI) ## Procedure @@ -56,8 +56,8 @@ We recommend deploying Lifecycle Manager with the KCP kustomize profile. You mus 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 +* 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 @@ -88,5 +88,5 @@ After the successful deployment of the access Secrete, you can start to use Kyma ## Next Steps -- To learn how to publish ModuleTemplate CRs in a private OCI registry, refer to the [Provide credentials for private OCI registry authentication](../developer-tutorials/config-private-registry.md) tutorial -- To learn how to manage module enablement with the provided strategies, refer to the [Manage module enablement with CustomResourcePolicy](02-10-manage-module-with-custom-resource-policy.md) tutorial +* To learn how to publish ModuleTemplate CRs in a private OCI registry, refer to the [Provide credentials for private OCI registry authentication](../developer-tutorials/config-private-registry.md) tutorial +* To learn how to manage module enablement with the provided strategies, refer to the [Manage module enablement with CustomResourcePolicy](02-10-manage-module-with-custom-resource-policy.md) tutorial diff --git a/markdown_heading_capitalization.js b/markdown_heading_capitalization.js new file mode 100644 index 0000000000..ca98421ef0 --- /dev/null +++ b/markdown_heading_capitalization.js @@ -0,0 +1,29 @@ +module.exports = [{ + "names": [ "custom/capitalize-headings" ], + "description": "Heading words longer than 4 characters should be capitalized", + "tags": [ "formatting" ], + "function": function rule(params, onError) { + params.tokens.filter(function filterToken(token) { + return token.type === "heading_open"; + }).forEach(function forToken(heading) { + var headingTokenContent = heading.line.trim(); + var wordsInHeading = headingTokenContent.split(' '); + + for (var i = 0; i < wordsInHeading.length; i++) { + if (wordsInHeading[i].length > 4 && wordsInHeading[i] && + wordsInHeading[i].charAt(0) !== wordsInHeading[i].charAt(0).toUpperCase()) { + var capitalizedWord = wordsInHeading[i].charAt(0).toUpperCase() + wordsInHeading[i].slice(1); + var detailMessage = "Change " + "'" + wordsInHeading[i] + "'" + " to " + "'" + capitalizedWord + "'"; + + onError({ + "lineNumber": heading.lineNumber, + "detail": detailMessage, + "context": headingTokenContent, // Show the whole heading as context + "range": [headingTokenContent.indexOf(wordsInHeading[i]), wordsInHeading[i].length] // Underline the word which needs a change + }); + } + } + }); + } + }]; + \ No newline at end of file