Working with OCI

Transfer by Value

In this use case, you start with a component version that references an external OCI image, transfer it with --copy-resources to internalize the image as a local blob, and then access it natively from the target registry.

1. Set up a working directory

   mkdir -p /tmp/ocm-transfer-native && cd /tmp/ocm-transfer-native

2. Create a component with an external image reference

   Create a component that references an existing OCI image by reference (not by value):

   cat > component-constructor.yaml << 'EOF'
   # yaml-language-server: $schema=https://ocm.software/latest/schemas/bindings/go/constructor/schema-2020-12.json
   components:
   - name: github.com/acme.org/transfer-demo
     version: 1.0.0
     provider:
       name: acme.org
     resources:
       - name: app-image
         type: ociImage
         version: 1.0.0
         access:
           type: ociArtifact
           imageReference: ghcr.io/stefanprodan/podinfo:6.9.1
   EOF

   Build the component version:

   ocm add cv

3. Inspect the external reference

   ocm get cv ./transport-archive//github.com/acme.org/transfer-demo:1.0.0 -o yaml

   Expected output

   - component:
       name: github.com/acme.org/transfer-demo
       provider: acme.org
       resources:
         - access:
             imageReference: ghcr.io/stefanprodan/podinfo:6.9.1@sha256:...
             type: ociArtifact
           name: app-image
           relation: external
           type: ociImage
           version: 1.0.0
       version: 1.0.0
     meta:
       schemaVersion: v2

   The image is referenced externally — it still lives in ghcr.io. The component descriptor only stores the reference.

4. Transfer with –copy-resources

   Transfer the component to your target registry, copying all resources by value:

   ocm transfer cv \
     --copy-resources \
     ./transport-archive//github.com/acme.org/transfer-demo:1.0.0 \
     <your-registry>

   Note

   For local registries running without TLS, use the http:// scheme prefix (e.g. http://localhost:5001). HTTPS registries work without a scheme prefix.

   With --copy-resources, OCM:

   1. Downloads the image from ghcr.io/stefanprodan/podinfo:6.9.1
   2. Stores it as a local blob in the target component version
   3. Maps it to a native OCI manifest in the component version’s index
   4. Updates the access specification with a localReference (digest) pointing to the native OCI manifest

5. Inspect the transferred component

   ocm get cv <your-registry>//github.com/acme.org/transfer-demo:1.0.0 -o yaml

   After transfer with --copy-resources, the access specification changes from an external reference to a local blob:

   resources:
     - access:
         localReference: sha256:...
         mediaType: application/vnd.oci.image.index.v1+json
         referenceName: stefanprodan/podinfo:6.9.1
         type: LocalBlob/v1
       name: app-image
       relation: external
       type: ociImage
       version: 1.0.0

   Key observations:

   • access.type changed from ociArtifact to LocalBlob/v1 — the image is now embedded
   • localReference contains the digest of the stored image manifest/index
   • mediaType is application/vnd.oci.image.index.v1+json (or application/vnd.oci.image.manifest.v1+json for single-platform images)
   • referenceName preserves the original image reference for traceability
   • relation remains external — this indicates the resource was originally sourced externally, even though it is now stored locally

6. Pull the image natively

   Use the localReference digest to pull the image with standard OCI tooling. The image is stored within the component version’s repository:

   # Using docker
   docker pull <your-registry>/component-descriptors/github.com/acme.org/transfer-demo@sha256:...
   
   # Using crane
   crane manifest <your-registry>/component-descriptors/github.com/acme.org/transfer-demo@sha256:...

   The image is stored as a first-class OCI manifest in the registry. No OCM tooling is required to access it — any OCI-compliant client works.

   You can also download through OCM:

   ocm download resource <your-registry>//github.com/acme.org/transfer-demo:1.0.0 \
     --identity name=app-image \
     --output app-image-download

Fetch from Remote with ORAS

In this use case, you fetch an existing OCI artifact from a remote registry using ORAS, embed it into a component version, and transfer it to a target registry.

1. Set up a working directory

   mkdir -p /tmp/ocm-fetch-oci && cd /tmp/ocm-fetch-oci

2. Fetch the OCI artifact with ORAS

   Pull an existing artifact from a remote registry into a local OCI image layout:

   mkdir -p oci-layout
   oras copy ghcr.io/stefanprodan/podinfo:6.9.1 --to-oci-layout oci-layout:latest

3. Create the component constructor

   cat > component-constructor.yaml << 'EOF'
   components:
   - name: github.com/acme.org/fetched-oci-demo
     version: 1.0.0
     provider:
       name: acme.org
     resources:
       - name: app-image
         type: ociArtifact
         version: 1.0.0
         input:
           type: dir/v1
           path: ./oci-layout
           mediaType: application/vnd.ocm.software.oci.layout.v1+tar
   EOF

4. Build and transfer

   ocm add cv
   
   ocm transfer cv \
     --copy-resources \
     ./transport-archive//github.com/acme.org/fetched-oci-demo:1.0.0 \
     <your-registry>

5. Inspect the transferred component version

   After transfer, inspect the component version in the registry:

   ocm get cv <your-registry>//github.com/acme.org/fetched-oci-demo:1.0.0 -o yaml

   The resource access now shows a local blob reference:

   resources:
     - access:
         localReference: sha256:abc123...
         mediaType: application/vnd.oci.image.index.v1+json
         referenceName: stefanprodan/podinfo:6.9.1
         type: LocalBlob/v1
       name: app-image
       relation: external
       type: ociArtifact
       version: 1.0.0

   Key observations:

   • localReference contains the digest of the stored image manifest/index — this is the value you need for native access
   • mediaType is application/vnd.oci.image.index.v1+json (multi-platform) or application/vnd.oci.image.manifest.v1+json (single-platform)
   • referenceName preserves the original image reference for traceability

6. Pull natively

   Use the localReference digest from the previous step to pull the artifact with standard OCI tooling:

   # Pull using the localReference digest
   oras pull <your-registry>/component-descriptors/github.com/acme.org/fetched-oci-demo@sha256:abc123...

   The image is stored as a first-class OCI manifest in the registry. No OCM tooling is required to access it — any OCI-compliant client works.