From 287e599f8dd21739dbf5685a69ceea7b229928be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20Schw=C3=A4gerl?= Date: Wed, 18 Dec 2024 10:57:23 +0100 Subject: [PATCH 1/5] docs: Migrating from Kyma CLI to modulectl --- docs/contributor/migration-guide.md | 86 +++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/contributor/migration-guide.md diff --git a/docs/contributor/migration-guide.md b/docs/contributor/migration-guide.md new file mode 100644 index 00000000..5f3416ba --- /dev/null +++ b/docs/contributor/migration-guide.md @@ -0,0 +1,86 @@ +# Migrating from Kyma CLI to `modulectl` + +This guide provides detailed instructions for migrating from the current Kyma CLI tool to the new `modulectl` tool. +It covers all necessary changes and deprecations to ensure a smooth transition. + +## Overview + +`modulectl` is the successor of the module developer facing capabilities of Kyma CLI. +It is already tailored for the update ModuleTemplate metadata as discussed in [ADR: Iteratively moving forward with module requirements and aligning responsibilities](https://github.com/kyma-project/lifecycle-manager/issues/1681). + +## Use `modulectl` + +It is available for download from the [GitHub Releases](https://github.com/kyma-project/modulectl/releases). +For an overview of the supported commands and flags, use `modulectl -h` or `modulectl -h` to show the definitions. + +## Deprecations and Changes + +In the following, the key changes between Kyma CLI and `modulectl` are briefly described. + +1. **New command** + + - The new module create command is `modulectl create`, use `modulectl create -h` for detailed description. + +2. **Release Channel Configuration** + + - **Deprecated**: The **.channel** field is no longer required in the config file. + - **New Approach**: Release Channel is configured separately in the [ModuleReleaseMeta](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md). + +3. **Manifest and Default CR data** + + - **Deprecated**: The Manifest and Default CR data cannot be read from a local file. + - **New Approach**: The Manifest and Default CR data is fetched directly from the GitHub release. See an example [here](https://github.com/kyma-project/modulectl/blob/91e01856b944fda0d5595843e040bca26416abdc/tests/e2e/create/testdata/moduleconfig/valid/with-defaultcr.yaml#L3-L4). + +4. **Annotations and Labels** + + - **Deprecated**: The documentation link is not added as an annotation `operator.kyma-project.io/doc-url`. + - **New**: The documentation link is added as **.spec.info.documentation**. The value is configured in the module config file with key **.documentation**. + - **Deprecated**: The module version is not added as a label `operator.kyma-project.io/module-version`. + - **New**: The module version is added as **.spec.version**. + +5. **Command Flags** + + - **Deprecated**: Flag `--module-config-file` is deprecated. + - **New**: Flag `--config-file` with shortcut `-c` (applicable for both scaffold and create commands). + - **Deprecated**: Flag `--module-archive-version-overwrite` is deprecated. + - There is no successor, this feature has been sunset entirely. Reason is that module versions should be immutable once built and pushed. If a version really needs to be re-written, it should be deleted from the registry explicitly first. + +6. **ModuleTemplate Naming Pattern** + + - **Deprecated**: **.metadata.name** is not written as `-`. + - **New**: **.metadata.name** is written as `-`. + +7. **Mandatory ModuleTemplates** + + - **Restriction**: At the moment, `modulectl` is not used for the creation of mandatory ModuleTemplates. Please use Kyma CLI instead until the next release. + +8. **Beta and Internal Flags** + +- **Deprecated**: Beta and Internal flags are not supported for ModuleTemplates. +- **New**: Beta and Intenral flags are configured as part of the ModuleReleaseMeta, see [ModuleReleaseMeta Configuration](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md#configuration). + +## Migration Period + +**Support for Both Approaches Temporarily**: + +- Both old and new approaches will be supported simultaneously by KLM during the migration period. +- After the full migration to the new approach, KLM will no longer accept ModuleTemplate with the old naming pattern. +- For testing, provide ModuleTemplates in the new format accompanied by [ModuleReleaseMeta](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md). KLM will attempt to use the new approach and fall back to the old approach if the new format is not found. To avoid syncing the new ModuleTemplate to the SKR while testing, use the internal label. + +## Submission Process + +The general submission process may look as follows: + +1. Module Team releases a new module version in the GitHub release. +2. Module Team configures the version to be released in the module config (in the new format) in the internal module-manifest repo. +3. Module Team updates the version in the related channel in ModuleReleaseMeta. +4. The submission pipeline gets triggered. +5. After certain quality gates are passed, the new version of ModuleTemplate gets provisioned into KCP first. +6. The updated ModuleReleaseMeta gets provisioned into KCP. +8. Outdated ModuleTemplate (the version not mentioned in ModuleReleaseMeta) should be removed. This step allows both outdated and new versions to coexist temporary. KLM only handle the version defined in ModuleReleaseMeta. + +## Additional Resources + +- [Update on Module Metadata @iteration review](https://sap-my.sharepoint.com/:p:/p/c_schwaegerl/EbvSNmRnr3JEjaLoZ__cI9UB9lu5tt0qaly-f7yQO2Gwbw?e=slfiDf) +- [ADR: Iteratively moving forward with module requirements and aligning responsibilities](https://github.com/kyma-project/lifecycle-manager/issues/1681) +- [`modulectl` GitHub Repository](https://github.com/kyma-project/modulectl) From 7d923f25372272d88292077cc85c7de9e360fc15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20Schw=C3=A4gerl?= Date: Wed, 18 Dec 2024 11:00:04 +0100 Subject: [PATCH 2/5] remove unaccessible resource --- docs/contributor/migration-guide.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/contributor/migration-guide.md b/docs/contributor/migration-guide.md index 5f3416ba..372793b8 100644 --- a/docs/contributor/migration-guide.md +++ b/docs/contributor/migration-guide.md @@ -81,6 +81,5 @@ The general submission process may look as follows: ## Additional Resources -- [Update on Module Metadata @iteration review](https://sap-my.sharepoint.com/:p:/p/c_schwaegerl/EbvSNmRnr3JEjaLoZ__cI9UB9lu5tt0qaly-f7yQO2Gwbw?e=slfiDf) - [ADR: Iteratively moving forward with module requirements and aligning responsibilities](https://github.com/kyma-project/lifecycle-manager/issues/1681) - [`modulectl` GitHub Repository](https://github.com/kyma-project/modulectl) From 4ea02f5442d350c755209dd86601824ef79728e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20Schw=C3=A4gerl?= Date: Wed, 18 Dec 2024 14:43:37 +0100 Subject: [PATCH 3/5] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Małgorzata Świeca --- docs/contributor/migration-guide.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/contributor/migration-guide.md b/docs/contributor/migration-guide.md index 372793b8..5a82dc4d 100644 --- a/docs/contributor/migration-guide.md +++ b/docs/contributor/migration-guide.md @@ -5,7 +5,7 @@ It covers all necessary changes and deprecations to ensure a smooth transition. ## Overview -`modulectl` is the successor of the module developer facing capabilities of Kyma CLI. +`modulectl` is the successor of the module developer-facing capabilities of Kyma CLI. It is already tailored for the update ModuleTemplate metadata as discussed in [ADR: Iteratively moving forward with module requirements and aligning responsibilities](https://github.com/kyma-project/lifecycle-manager/issues/1681). ## Use `modulectl` @@ -15,16 +15,16 @@ For an overview of the supported commands and flags, use `modulectl -h` or `modu ## Deprecations and Changes -In the following, the key changes between Kyma CLI and `modulectl` are briefly described. +Look at the key changes between Kyma CLI and `modulectl`. -1. **New command** +1. **New Command** - - The new module create command is `modulectl create`, use `modulectl create -h` for detailed description. + - The new command for module creation is `modulectl create`, use `modulectl create -h` for a detailed description. 2. **Release Channel Configuration** - **Deprecated**: The **.channel** field is no longer required in the config file. - - **New Approach**: Release Channel is configured separately in the [ModuleReleaseMeta](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md). + - **New Approach**: The release channel is configured separately in the [ModuleReleaseMeta CR](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md). 3. **Manifest and Default CR data** @@ -33,9 +33,9 @@ In the following, the key changes between Kyma CLI and `modulectl` are briefly d 4. **Annotations and Labels** - - **Deprecated**: The documentation link is not added as an annotation `operator.kyma-project.io/doc-url`. + - **Deprecated**: The documentation link is not added as the `operator.kyma-project.io/doc-url` annotation. - **New**: The documentation link is added as **.spec.info.documentation**. The value is configured in the module config file with key **.documentation**. - - **Deprecated**: The module version is not added as a label `operator.kyma-project.io/module-version`. + - **Deprecated**: The module version is not added as the `operator.kyma-project.io/module-version` label. - **New**: The module version is added as **.spec.version**. 5. **Command Flags** @@ -43,7 +43,7 @@ In the following, the key changes between Kyma CLI and `modulectl` are briefly d - **Deprecated**: Flag `--module-config-file` is deprecated. - **New**: Flag `--config-file` with shortcut `-c` (applicable for both scaffold and create commands). - **Deprecated**: Flag `--module-archive-version-overwrite` is deprecated. - - There is no successor, this feature has been sunset entirely. Reason is that module versions should be immutable once built and pushed. If a version really needs to be re-written, it should be deleted from the registry explicitly first. + - There is no successor, this feature has been sunset entirely. The reason is that module versions should be immutable once built and pushed. If a version needs to be rewritten, first it should be explicitly deleted from the registry. 6. **ModuleTemplate Naming Pattern** @@ -56,8 +56,8 @@ In the following, the key changes between Kyma CLI and `modulectl` are briefly d 8. **Beta and Internal Flags** -- **Deprecated**: Beta and Internal flags are not supported for ModuleTemplates. -- **New**: Beta and Intenral flags are configured as part of the ModuleReleaseMeta, see [ModuleReleaseMeta Configuration](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md#configuration). + - **Deprecated**: Beta and Internal flags are not supported for ModuleTemplates. + - **New**: Beta and Intenral flags are configured as part of the ModuleReleaseMeta, see [ModuleReleaseMeta Configuration](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md#configuration). ## Migration Period @@ -65,7 +65,7 @@ In the following, the key changes between Kyma CLI and `modulectl` are briefly d - Both old and new approaches will be supported simultaneously by KLM during the migration period. - After the full migration to the new approach, KLM will no longer accept ModuleTemplate with the old naming pattern. -- For testing, provide ModuleTemplates in the new format accompanied by [ModuleReleaseMeta](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md). KLM will attempt to use the new approach and fall back to the old approach if the new format is not found. To avoid syncing the new ModuleTemplate to the SKR while testing, use the internal label. +- For testing, provide ModuleTemplate CRs in the new format accompanied by [ModuleReleaseMeta CRs](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md). KLM will attempt to use the new approach and fall back to the old approach if the new format is not found. Use the internal label, to avoid syncing the new ModuleTemplate to the SKR while testing. ## Submission Process @@ -77,7 +77,7 @@ The general submission process may look as follows: 4. The submission pipeline gets triggered. 5. After certain quality gates are passed, the new version of ModuleTemplate gets provisioned into KCP first. 6. The updated ModuleReleaseMeta gets provisioned into KCP. -8. Outdated ModuleTemplate (the version not mentioned in ModuleReleaseMeta) should be removed. This step allows both outdated and new versions to coexist temporary. KLM only handle the version defined in ModuleReleaseMeta. +7. Outdated ModuleTemplate (the version not mentioned in ModuleReleaseMeta) should be removed. This step allows both outdated and new versions to coexist temporarily. KLM only handles the version defined in ModuleReleaseMeta. ## Additional Resources From 4e2943ddac31c8de212b24097f93c41c3c1aee40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20Schw=C3=A4gerl?= Date: Wed, 18 Dec 2024 14:44:40 +0100 Subject: [PATCH 4/5] Update docs/contributor/migration-guide.md --- docs/contributor/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributor/migration-guide.md b/docs/contributor/migration-guide.md index 5a82dc4d..a8bee655 100644 --- a/docs/contributor/migration-guide.md +++ b/docs/contributor/migration-guide.md @@ -6,7 +6,7 @@ It covers all necessary changes and deprecations to ensure a smooth transition. ## Overview `modulectl` is the successor of the module developer-facing capabilities of Kyma CLI. -It is already tailored for the update ModuleTemplate metadata as discussed in [ADR: Iteratively moving forward with module requirements and aligning responsibilities](https://github.com/kyma-project/lifecycle-manager/issues/1681). +It is already tailored for the updated ModuleTemplate metadata as discussed in [ADR: Iteratively moving forward with module requirements and aligning responsibilities](https://github.com/kyma-project/lifecycle-manager/issues/1681). ## Use `modulectl` From 94a12653aaa08cd8bb6ef61b13e64a1c3af8256c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20Schw=C3=A4gerl?= Date: Wed, 18 Dec 2024 14:46:12 +0100 Subject: [PATCH 5/5] Update docs/contributor/migration-guide.md --- docs/contributor/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributor/migration-guide.md b/docs/contributor/migration-guide.md index a8bee655..8ff48a7a 100644 --- a/docs/contributor/migration-guide.md +++ b/docs/contributor/migration-guide.md @@ -65,7 +65,7 @@ Look at the key changes between Kyma CLI and `modulectl`. - Both old and new approaches will be supported simultaneously by KLM during the migration period. - After the full migration to the new approach, KLM will no longer accept ModuleTemplate with the old naming pattern. -- For testing, provide ModuleTemplate CRs in the new format accompanied by [ModuleReleaseMeta CRs](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md). KLM will attempt to use the new approach and fall back to the old approach if the new format is not found. Use the internal label, to avoid syncing the new ModuleTemplate to the SKR while testing. +- For testing, provide ModuleTemplate CRs in the new format accompanied by [ModuleReleaseMeta CRs](https://github.com/kyma-project/lifecycle-manager/blob/main/docs/contributor/resources/05-modulereleasemeta.md). KLM will attempt to use the new approach and fall back to the old approach if the new format is not found. The ModuleReleaseMeta CR can be marked as internal and beta to avoid syncing it. ## Submission Process