Pull OCI Artifacts Natively

Transfer by Value

Starting from the component version that references an external OCI image, transfer it with a local blob uploader configuration to internalize the image as a local blob, and then access it natively from the target registry.

1. Transfer with a local blob uploader#

   Transfer the component to your target registry, copying all resources by value. Create the .ocmconfig if you have not already:

   cat > .ocmconfig << 'EOF'
   type: generic.config.ocm.software/v1
   configurations:
     - type: localblob.uploader.transfer.config.ocm.software/v1alpha1
   EOF

   ocm transfer cv \
     ./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 the local blob uploader configuration, 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

2. Inspect the transferred component#

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

   After transfer with the local blob uploader, 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

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

Starting from the component version that embeds an ORAS-fetched OCI image layout, transfer it to a target registry and pull it natively.

1. Transfer#

   cat > .ocmconfig << 'EOF'
   type: generic.config.ocm.software/v1
   configurations:
     - type: localblob.uploader.transfer.config.ocm.software/v1alpha1
   EOF
   
   ocm transfer cv \
     ./transport-archive//github.com/acme.org/fetched-oci-demo:1.0.0 \
     <your-registry>

2. 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 shows a local blob reference:

   resources:
     - access:
         localReference: sha256:262578cde928d5c9eba3bce079976444f624c13ed0afb741d90d5423877496cb
         mediaType: application/vnd.oci.image.index.v1+json
         type: LocalBlob/v1
       name: app-image
       relation: local
       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)
   • relation: local confirms the artifact is stored inside the component version, not referenced externally

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