Using absolute access types for transferred-by-value artifacts is problematic

[anbrsap]

Scenario

• A K8s cluster runs an own OCI registry.
• All artifacts of a component version should be made available in that cluster-internal OCI registry (no references to external OCI registries)
• Consumption of the component version artifacts happens from within the cluster using the cluster-local network only (all external network access is blocked).

The component version is transferred into the cluster-internal registry using port-forwarding:

$ ocm transfer ctf --copy-resources component-1/ http://localhost:9999/local/components

Problem

The artifact consumption from within the cluster fails.

Example using OCM CLI:

$ ocm download resources http://cluster-registry.svc/local/components//example.com/component-1 image--busybox -O busybox.tar.gz
Error: resource image--busybox/v1.36.1: unable to read access: failed to resolve manifest "localhost:9999/local/components/library/busybox@sha256:ec15a5bd53cf9507beb851574654669e778a9735f8e605e0ee3d71fd07debbe1": Head "http://localhost:9999/v2/local/components/library/busybox/manifests/sha256:ec15a5bd53cf9507beb851574654669e778a9735f8e605e0ee3d71fd07debbe1": dial tcp [::1]:9999: connect: connection refused

It tries to get the artifact (image--busybox) using the registry host name + port localhost:9999 that was used when uploading the component version. But this is not valid in the consumer's environment.

The component version descriptor in the registry looks like this:

meta:
  schemaVersion: v2
component:
  componentReferences: []
  creationTime: "2025-04-07T13:01:16Z"
  name: example.com/component-1
  provider: example.com
  repositoryContexts:
  - baseUrl: http://localhost:9999
    componentNameMapping: urlPath
    subPath: local/components
    type: OCIRegistry
  resources:
  - access:
      imageReference: http://localhost:9999/local/components/library/busybox:1.36.1@sha256:ec15a5bd53cf9507beb851574654669e778a9735f8e605e0ee3d71fd07debbe1
      type: ociArtifact
    digest:
      hashAlgorithm: SHA-256
      normalisationAlgorithm: ociArtifactDigest/v1
      value: ec15a5bd53cf9507beb851574654669e778a9735f8e605e0ee3d71fd07debbe1
    name: image--busybox
    relation: external
    type: ociImage
    version: v1.36.1
  sources: []
  version: 0.1.0

component.resources[0].access is an absolute reference, although the artifact is stored with the component descriptor in the same OCM repository.

Proposed Solution

For all artifacts contained in the same OCM repository as the component version descriptor relative access types should be used (relative to OCM repo location of component version descriptor). This avoids storing the URL of the OCM repository, and thus makes the descriptor portable.

Further Information

The described problem arises in all scenarios where the OCM repo URL during uploads of component versions differs from the OCM repo URL used by consumers, for example:

• Consumers access an OCI repository through a reverse proxy
• OCI repository content is generically replicated to other instances, which are used by consumers

[fabianburth]

Hey @anbrsap, we are aware of this issue when working with in-cluster registries. There is the concept of relativeOciReferences. In the PR by @mandelsoft linked above, there would also be an option to control whether an oci artifact is uploaded with an access type ociArtifact or relativeOciReference.
It would be great if you could have a look at the PR yourself to check whether you would be satisfied with the proposed solution.

A quick warning, we are currently working on a new version of the current ocm cli. And while we are generally doing our best to keep backward compatibility, the relativeOciReference will likely not be supported like that anymore. Though, there will likely be another concept in place to solve your use case.

[anbrsap]

@fabianburth: I tested #1412 locally. It works!

Here's what I did:

1. Upload to localhost:1111 enabling relative access method:

   $ ocm -X preferrelativeaccess=true transfer ctf --copy-resources component-1.ctf http://localhost:1111/components-c
    2025-04-29T18:12:55+02:00 warning [ocm/oci/ocireg] "using insecure http for oci registry localhost:1111"
   transferring component "example.com/component-1"...
     transferring version "example.com/component-1:0.1.0"...
     ...resource 0 image--busybox[ociImage](library/busybox:1.36.1)...
     ...adding component version...
   

2. Uploaded component manifest now contains a relative access method:

   $ ocm get componentversions http://localhost:1111/components-c//example.com/component-1 -o yaml
    2025-04-29T18:13:09+02:00 warning [ocm/oci/ocireg] "using insecure http for oci registry localhost:1111"
   ---
   component:
     componentReferences: []
     creationTime: "2025-04-29T16:06:10Z"
     name: example.com/component-1
     provider: example.com
     repositoryContexts:
     - baseUrl: http://localhost:1111
       componentNameMapping: urlPath
       subPath: components-c
       type: OCIRegistry
     resources:
     - access:
         reference: components-c/library/busybox:1.36.1@sha256:ec15a5bd53cf9507beb851574654669e778a9735f8e605e0ee3d71fd07debbe1
         type: relativeOciReference
       digest:
         hashAlgorithm: SHA-256
         normalisationAlgorithm: ociArtifactDigest/v1
         value: ec15a5bd53cf9507beb851574654669e778a9735f8e605e0ee3d71fd07debbe1
       name: image--busybox
       relation: external
       type: ociImage
       version: v1.36.1
     sources: []
     version: 0.1.0
   meta:
     schemaVersion: v2
   

3. Download using different registry name localhost:2222 (port forwarding localhost:1111 is removed):

   $ ocm transfer componentversions http://localhost:2222/components-c//example.com/component-1 ./download-component-1
    2025-04-29T18:16:11+02:00 warning [ocm/oci/ocireg] "using insecure http for oci registry localhost:2222"
   transferring version "example.com/component-1:0.1.0"...
   ...resource 0 image--busybox[ociImage](components-c/library/busybox:1.36.1@sha256:ec15a5bd53cf9507beb851574654669e778a9735f8e605e0ee3d71fd07debbe1)...
   ...adding component version...
   1 versions transferred
   

   It works!

4. Check downloaded component manifest:

   $ ocm get componentversions ./download-component-1/ -o yaml
   ---
   component:
     componentReferences: []
     creationTime: "2025-04-29T16:06:10Z"
     name: example.com/component-1
     provider: example.com
     repositoryContexts:
     - baseUrl: http://localhost:1111
       componentNameMapping: urlPath
       subPath: components-c
       type: OCIRegistry
     resources:
     - access:
         localReference: sha256:c49eb16edd73b5adf91e822e9417bf7d4a76182a40ef9e61758d610e7b32408f
         mediaType: application/vnd.oci.image.manifest.v1+tar+gzip
         referenceName: components-c/library/busybox:1.36.1@sha256:ec15a5bd53cf9507beb851574654669e778a9735f8e605e0ee3d71fd07debbe1
         type: localBlob
       digest:
         hashAlgorithm: SHA-256
         normalisationAlgorithm: ociArtifactDigest/v1
         value: ec15a5bd53cf9507beb851574654669e778a9735f8e605e0ee3d71fd07debbe1
       name: image--busybox
       relation: external
       type: ociImage
       version: v1.36.1
     sources: []
     version: 0.1.0
   meta:
     schemaVersion: v2
   

Still, the component manifest contains traces of the registry name used for uploading:

component:
    repositoryContexts:
      - baseUrl: http://localhost:1111
        componentNameMapping: urlPath
        subPath: components-c
        type: OCIRegistry

I don't know if this may cause trouble.

[morri-son]

Hi @anbrsap , the repositoryContexts is only used for documentation purposes in which repositories a component version existed. It contains a list of all repositories. It should not influence any action done on an OCM component.