Add OCI Artifacts

Embed an OCI Image Layout

In this use case, you create an OCI image layout from scratch using ORAS and embed it in a component version, ready to transfer to an OCI registry where it becomes natively accessible.

1. Set up a working directory#

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

2. Create a sample artifact with ORAS#

   Create a simple file and package it as an OCI artifact using ORAS. This produces an OCI image layout on disk:

   # Create sample content
   echo '{"message": "hello from OCM"}' > artifact.json
   
   # Create an OCI image layout directory using ORAS
   mkdir -p oci-layout
   oras push --oci-layout oci-layout:latest \
     --artifact-type application/vnd.example.config \
     artifact.json:application/json

   Verify the layout was created:

   ls oci-layout/

   You should see the standard OCI image layout structure:

   blobs/
   index.json
   oci-layout

3. Create the component constructor#

   Create a component-constructor.yaml that embeds the OCI image layout directory using the dir/v1 input type:

   cat > component-constructor.yaml << 'EOF'
   # yaml-language-server: $schema=https://ocm.software/main/schemas/bindings/go/constructor/schema-2020-12.json
   components:
   - name: github.com/acme.org/native-oci-demo
     version: 1.0.0
     provider:
       name: acme.org
     resources:
       - name: my-oci-artifact
         type: ociArtifact
         version: 1.0.0
         input:
           type: dir/v1
           path: ./oci-layout
           mediaType: application/vnd.ocm.software.oci.layout.v1+tar
   EOF

   Key points:

   • The type: dir/v1 input packs the directory into a tar archive and embeds it by value as a local blob
   • The mediaType: application/vnd.ocm.software.oci.layout.v1+tar tells OCM this is an OCI image layout, not an opaque blob — the dir/v1 input automatically produces the tar archive expected by this media type
   • During ocm add cv, OCM unpacks the layout and stores the contained manifest directly — the resulting local blob has the native OCI media type (e.g. application/vnd.oci.image.manifest.v1+json), not the tar media type

4. Build the component version#

   ocm add cv

   Expected output

    COMPONENT                          | VERSION | PROVIDER
   ------------------------------------+---------+----------
    github.com/acme.org/native-oci-demo | 1.0.0   | acme.org

5. Inspect the component version#

   Examine the component descriptor to see how the resource was stored:

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

   Expected output

   - component:
       name: github.com/acme.org/native-oci-demo
       provider: acme.org
       resources:
         - access:
             localReference: sha256:...
             mediaType: application/vnd.oci.image.manifest.v1+json
             type: LocalBlob/v1
           name: my-oci-artifact
           relation: local
           type: ociArtifact
           version: 1.0.0
       version: 1.0.0
     meta:
       schemaVersion: v2

   Notice that the resource has access.type: LocalBlob/v1 with the native OCI manifest media type. OCM recognized the OCI image layout during ingestion, unpacked it, and stored the manifest directly. The localReference contains the digest of the embedded manifest.