Upload OCI Images

Start from the base transfer guide

This guide builds on Transfer Component Versions. Read it first for the default ocm transfer cv workflow, credentials, and verification; the steps below only add the OCI uploader configuration.

Goal

Transfer a component version so that its container images (and Helm charts) land in the target registry as separate OCI artifacts, directly addressable and pullable with standard OCI tooling such as docker, oras, or crane, instead of staying referenced in place or embedded as local blobs.

How it works

Adding an oci.uploader.transfer.config.ocm.software/v1alpha1 entry to your OCM configuration tells transfer to upload every matched resource as its own OCI artifact in the target registry. The resource is stored independently of the component version, so it is directly pullable.

With no match field, the uploader uses its default selection: on OCI registry targets it uploads OCIImage resources (all aliases), Helm chart resources, and LocalBlob resources that hold an OCI manifest and carry a referenceName. That is exactly the scope of the deprecated --upload-as ociArtifact flag. With no imageReference field, the uploader derives the target reference automatically from each resource’s access type.

Prerequisites

  • OCM CLI installed
  • A source component version and a writable target OCI registry, as set up in Transfer Component Versions
  • An OCI client such as docker, oras, or crane to pull the uploaded artifacts

Steps

  1. Add the OCI uploader to your OCM configuration

    Add a catch-all uploader entry to your .ocmconfig (or any OCM configuration you pass with --config). Omitting match and imageReference uses the defaults, which cover OCI images and Helm charts:

    # .ocmconfig
type: generic.config.ocm.software/v1
configurations:
  - type: oci.uploader.transfer.config.ocm.software/v1alpha1

  2. Transfer with the uploader applied

    Run the base transfer with the configuration in effect:

    ocm transfer cv --config .ocmconfig \
  ghcr.io/<source-namespace>//ocm.software/examples/demo:1.0.0 \
  ghcr.io/<target-namespace>

    Each matched image or chart is pushed to the target registry under a reference derived from its access type. For an OCI image such as ghcr.io/org/image:v1, the uploader keeps the repository and tag (org/image:v1) and places it under the target prefix.

  3. Pull the uploaded artifact

    The uploaded resources are now plain OCI artifacts in the target registry. Pull one directly with any OCI client:

    docker pull ghcr.io/<target-namespace>/org/image:v1

Helm charts

The OCI uploader’s default selection also covers Helm chart resources (a helmChart resource with Helm/v1 access, see Add Helm Chart Resources for authoring one). During transfer the chart is converted to an OCI artifact and, with the uploader applied, uploaded as a separate image in the target registry. Without the uploader the chart stays embedded as a local blob, coupled to the component version and not pullable with the Helm CLI.

Inspect the component descriptor to find the resulting reference:

ocm get cv <target-registry>//<component-name>:<version> -o yaml

Look for the resources[].access.imageReference field:

resources:
  - name: my-chart
    type: helmChart
    access:
      type: OCIImage/v1
      imageReference: ghcr.io/my-org/charts/my-chart:1.0.0

Pull it with Helm’s OCI support:

helm pull oci://ghcr.io/my-org/charts/my-chart --version 1.0.0

Targeting specific resources

To upload only selected resources, or to control the exact target reference, set the match and imageReference fields. match is a CEL boolean over resource, component, and target; imageReference is a CEL template (${…}) or a literal. For example, to build the reference from resource metadata:

- type: oci.uploader.transfer.config.ocm.software/v1alpha1
  imageReference: '${target.baseUrl + (target.subPath == "" ? "" : "/" + target.subPath) + "/" + resource.name + ":" + resource.version}'

An explicit match may select only resources the OCI uploader can upload: OCI images, Helm charts, and local blobs holding an OCI manifest. Selecting anything else fails the transfer.

For the full match / imageReference schema, the default expressions, and more selection examples, see OCI Uploader.

Next steps

Prev
Verify GPG
Next
Upload to a Custom Target