How to manage default CR from OCM

[ruanxin]

In the current manifest controller, reconciling the default CR is simple: the resource comes directly from moduletemplate.spec.data and is placed into manifest.spec.resource.

With the new approach, however, the default CR is stored as an OCM resource. This requires an additional process: download, cache, parse, and then apply it to the SKR.

Example OCM resource entry:

      - access:
          localReference: sha256:df2c81e0e0cade87504b97e3634fa506561c9b87b5f04872c9df663864c9065c
          mediaType: application/x-tar
          referenceName: default-cr
          type: localBlob
        digest:
          hashAlgorithm: SHA-256
          normalisationAlgorithm: genericBlobDigest/v1
          value: df2c81e0e0cade87504b97e3634fa506561c9b87b5f04872c9df663864c9065c
        name: default-cr
        relation: local
        type: directoryTree
        version: 1.45.0

Option A: Keep spec.resource

1. Kyma controller downloads, caches, and parses the CR into manifest.spec.resource.
2. Manifest controller reconciles the CR from spec.resource as it does today.

Option B: Introduce new spec.moduleCR

Instead of reusing spec.resource, we define a dedicated field (similar to spec.install) that only describes the OCM resource metadata.

Example:
if we decided go this approach, the structure should be designed much better.

apiVersion: operator.kyma-project.io/v1beta2
kind: Manifest
spec:
  customResourcePolicy: CreateAndDelete
  moduleCR:
      name: kyma-project.io/module/istio
      ref: sha256:df2c81e0e0cade87504b97e3634fa506561c9b87b5f04872c9df663864c9065c
      repo: europe-docker.pkg.dev/kyma-project/kyma-modules/component-descriptors
      type: oci-dir
  install:
    name: raw-manifest
    source:
      name: kyma-project.io/module/istio
      ref: sha256:32e5138866a981204080676271a8306b50e9c74a8e9cc64f34953faa58e88447
      repo: europe-docker.pkg.dev/kyma-project/kyma-modules/component-descriptors
      type: oci-dir

Process with spec.moduleCR

1. Kyma controller copies the OCM resource metadata into manifest.spec.moduleCR.
2. Manifest controller takes care of downloading, enhancing, caching, and finally applying the CR to the SKR.

This approach cleanly separates responsibilities:

• Kyma controller stays isolated from OCM resource handling.
• Manifest controller owns the logic for CR, module resources retrieval and application.

[ruanxin]

For Option2, the enhanced Manifest CR could be:

spec:
  customResourcePolicy: CreateAndDelete
  ocmComponentName: kyma-project.io/module/istio
  ocmRepo: europe-docker.pkg.dev/kyma-project/kyma-modules/component-descriptors
  ocmResources:
   - name: raw-manifest
     ref: sha256:32e5138866a981204080676271a8306b50e9c74a8e9cc64f34953faa58e88447
     type: oci-dir
   - name: module-cr
     ref: sha256:df2c81e0e0cade87504b97e3634fa506561c9b87b5f04872c9df663864c9065c
     type: oci-dir

[c-pius]

Would prefer this one over the one shown in the Description above.

ocmRepo: europe-docker.pkg.dev/kyma-project/kyma-modules/component-descriptors

Is this intentionally kept? Could it be removed as this is config for KLM by now?

[lindnerby]

onentName: kyma-project.io/module/istio
ocmRepo: europe-docker.pkg.dev/kyma-project/kyma-modules/component-descriptors
ocmResources:

• name: raw-manifest
  ref: sha256:32e5138866a981204080676271a8306b50e9c74a8e9cc64f34953faa58e88447
  type: oci-dir
• name: module-cr
  ref: sha256:df2c81e0e0cade87504b97e3634fa506561c9b87b5f04872c9df663864c9065c
  type: oci-dir

Personally would also vote for a similar API. But this requires some preparation and would make the spec.install obsolete?
It is more explicit in naming for what it's actually used for.
As an interim's solution to move the responsibility of ocm related handling strictly to ManifestReconciler we could add a field of spec.moduleCR which requires no API version upgrade/deprecation nor conversion webhooks from one version to another. So we have the feature faster and in a follow-up do the proper Manifest version upgrade with breaking changes to the API and consolidate the fields of spec.moduleCR and spec.install into the list element of spec.ocmResources (which is then also easily extensible due to the fact of being a list).

[Tomasz-Smelcerz-SAP]

+1 for option 2(B)

[c-pius]

T0

spec:
  install:
    ... # raw manifest

T1

Lifecycle-manager reconciles the manifest regularly, and will write the ocmResources field.

spec:
  install:
    ... # raw manifest
  ocmResources:
  - ... # raw manifest
  - ... # module CR

T2

spec:
  ocmResources
  - ... # raw manifest
  - ... # module CR

[ruanxin]

v1beta2

spec:
  install:
    ... # raw manifest
  ocmResources (optional):
  - ... # raw manifest
  - ... # module CR

v1beta3

spec:
  ocmResources (required):
  - ... # raw manifest
  - ... # module CR

newly created Manifest CR (v1beta3):

spec:
  ocmResources (required):
  - ... # raw manifest
  - ... # module CR

existing manifest CR (v1beta2):

spec:
  install:
    ... # raw manifest
  ocmResources (optional):
  - ... # raw manifest  (added by conversion webhook)
  - ... # module CR

[lindnerby]

To sum up after the discussion on 07.10.2025:
The plan would be to include the module CR in the Manifest and to achieve that we do the following steps:

1. First add the field ocmResources to the v1beta2.Manifest as optional. This will be a list of elements including raw manifest and module CR. KymaReconciler will initially populate ocmResources with the module CR entry, when creating Manifests.
2. Then v1beta3 as a new Manifest version is introduced and along with it all required breaking changes mentioned in Release new Manifest API version #2383. In this version ocmResources is required and the install field (containing the raw manifest until now) is removed. Along the version, the required conversion webhook to map between v1beta2 and v1beta3 is also introduced, which transfers the raw manifest from v1beta2's install field to ocmResources. Also KymaReconciler needs to create v1beta3 Manifests instead now. ManifestReconciler should be changed to only reoncile v1beta3 Manifests and there operates on ocmResources only.
3. Once KLM has been rolled out with these changes and the new Manifest CRD introduced, the last steps of the migration guide need to be done (see Release new Manifest API version #2383) making sure all Manifests stored versions are v1beta3.

[LeelaChacha]

Why our current approach is blocked: In the restricted markets Canary, we don't have ca injection feature for the conversion webhook to work properly. Feature Request