[Community Modules] Prepare handover documentation for the modulectl

[janmedrek]

Description

We want to create a documentation that is collecting all things that need to be communicated explicitly when handing over the new modulectl (migrate from CLI). Things to cover:

• deprecate module-configl.yaml manifest to use a local file (fetch from git instead)
  • manifest will automatically write an entry named rawManifest to .spec.resources
• do not use annotation operator.kyma-project.io/doc-url anymore, use .spec.info.documentation instead
• do not use label operator.kyma-project.io/module-version anymore, use .spec.version instead
• flag --module-config-file / --module-config has been renamed to --config-file and has shortcut -c (both, scaffold and create command)
• flag --git-remote needs to be provided with the value of the url of the GitHub repository to provide the security scanners config
• verify what moduleRepo is in https://github.tools.sap/kyma/module-manifests/blob/main/modules/api-gateway/fast/module-config.yaml#L11 and check if it can be replaced with .spec.info.repository
• new naming schema: .metadata.name is concatenated from <module-name>-<version> (instead of <module-name>-<channel> (See [ModuleCatalog] ModuleTemplate's metadata.name is <module-name>-<version> #62)
• mention that we want to support both approaches at the same time; for testing, they can already provide ModuleTemplates in the new format accompanied by ModuleReleaseMeta. KLM will try to use the new approach and fall back to the old approach if not found. To not sync new ModuleTemplate to the SKR while testing, the internal label can be used.
• manifest and defaultCR in the specified module config file MUST be links to the released asset of the module, not links to local files
• modulectl must not be used for the creation of manadatory ModuleTemplates [Module Catalog] Create concept for how to deal with mandatory modules and the latest module changes lifecycle-manager#1979

Acceptance Criteria

• Handover documented in this issue

[ruanxin]

Migration Guide: Use modulectl for Submission Pipeline

Introduction

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.

Deprecations and Changes

1. Release Channel Configuration

   • Deprecated: The channel field is no longer required in the config file.
   • New Approach: Release Channel is configured separately in ModuleReleaseMeta.

2. Manifest and Default CR Resource

   • Deprecated: The manifest used to offer a local file as input.
   • New Approach: Fetch the manifest directly from the GitHub release. See an example here.

3. Annotations and Labels

   • Deprecated: The documentation link will not be added as an annotation operator.kyma-project.io/doc-url in ModuleTemplate.
   • New: The documentation link will be presented in .spec.info.documentation instead. The input is configured in the config file as below:

     documentation: <link>

   • Deprecated: The module version is not a label operator.kyma-project.io/module-version anymore.
   • New: Instead, it's being persisted as .spec.version.

4. Command Flags

   • Deprecated: Flag --module-config-file.
   • New: Use --config-file with shortcut -c (applicable for both scaffold and create commands).
   • For the rest of the newly introduced flags, use modulectl create module -h to check for the definitions.

5. ModuleTemplate Naming Pattern

   • Deprecated: .metadata.name as <module-name>-<channel>.
   • New: .metadata.name is concatenated as <module-name>-<version>.

6. 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.

Migration Period

KLM supports consuming ModuleTemplate both in the old and new naming patterns. For each Kyma Module, a dedicated ModuleReleaseMeta must be provisioned into the KCP cluster accordingly. The general submission process should be as follows:

1. Module Team releases a new 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.
7. 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 Notes

• 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. 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.