Transfer Helm Charts with OCM

Goal

Transfer a component version that contains a Helm chart resource sourced from a Helm repository (type helmChart with Helm/v1 access) to an OCI registry. This guide does not cover charts that are already stored as OCI artifacts.

You’ll end up with

  • A component version containing a Helm chart transferred to a target OCI registry

Estimated time: ~10 minutes

Prerequisites

  • OCM CLI installed
  • Write access to a target OCI registry with credentials configured
  • A component version containing a Helm chart resource (stored in a CTF archive or OCI registry)

Steps

    Helm charts stored as ociImage

    If your existing component version contains a Helm chart stored as an ociImage resource rather than a helmChart with Helm/v1 access, you need to create a new component version using the helmChart type as shown below. This guide only covers the transfer of Helm charts sourced from Helm repositories.

  1. Create a component version with a Helm chart resource

    If you already have a component version containing a Helm chart with Helm/v1 access, skip to the next step.

    Create a constructor.yaml that references a chart from a Helm repository:

    components:
  - name: example.com/my-app
    version: 1.0.0
    provider:
      name: example.com
    resources:
      - name: my-chart
        version: 1.0.0
        type: helmChart
        access:
          type: Helm/v1
          helmRepository: https://charts.example.com
          helmChart: my-chart-1.0.0.tgz

    Add the component version to a CTF archive:

    ocm add cv --repository ctf::<path/to/archive> \
  --constructor constructor.yaml

  2. Transfer the component version

    Transfer the component version to the target registry. An OCI uploader stores the Helm chart as a standalone OCI artifact in the target registry, and a local blob catch-all copies every other resource.

    Add the uploaders to .ocmconfig in the working directory. If the file already exists (for example with the signing key, credentials or resolvers), add only the two uploader entries, in this order, to its configurations list; otherwise create it with this content:

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

    The CLI automatically merges .ocmconfig from the current directory with your other OCM configuration (such as $HOME/.ocmconfig), so credentials and resolvers stay in effect.

    ocm transfer cv \
  ctf::<path/to/archive>//<component-name>:<version> \
  <target-registry>

    This configuration can also be added to an existing OCM configuration file (for example $HOME/.ocmconfig):

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

    During transfer, the Helm chart is always converted to an OCI artifact. With the OCI uploader configuration, this artifact is uploaded as a separate image in the target registry. The component descriptor references it via an imageReference (e.g., ghcr.io/my-org/charts/my-chart:1.0.0), making it independently addressable and pullable with helm pull. For more details on how transfers and resource handling work, see Transfer and Transport.

    Without the OCI uploader, copied resources are embedded directly in the component version’s blob store as local blobs. This keeps the chart coupled to the component version but means it is not independently addressable in the registry and cannot be pulled with the Helm CLI.

    For more on the OCI uploader and how it replaces the deprecated --upload-as flag, see Migrate from –upload-as to Uploader Configurations.

    To find the imageReference, inspect the component descriptor:

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

    In the output, 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

    Use the imageReference value with Helm’s OCI support:

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

  3. Verify the transfer

    Confirm the component version is available in the target registry:

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

    Download the chart resource to verify it was transferred correctly:

    ocm download resource \
  <target-registry>//<component-name>:<version> \
  --identity name=my-chart \
  --output ./downloaded

Transfer between registries

To transfer a Helm chart component version from one OCI registry to another, use the source registry reference directly:

ocm transfer cv \
  <source-registry>//<component-name>:<version> \
  <target-registry>

Tips

  • If provenance files (.prov) are present in the Helm repository, they are automatically included in the transfer.
  • If you need to transfer recursively, add --recursive to include all transitively referenced component versions.
  • For air-gapped environments, first transfer to a CTF archive, move it across the boundary, then import into the target registry. See Transfer Components Across an Air Gap.

Next Steps

Prev
The OCM Core Model
Next
How to use the OCM CLI container image