Transfer Configuration

This page is the technical reference for OCM transfer configuration. For a task-oriented walkthrough of routing resources to a custom upload target, see the Configure Custom Uploads During Transfer tutorial. For the conceptual model, see Transfer and Transport.

Configuration Types

Transfer behaviour is controlled by configuration types embedded in the standard OCM configuration file. They are carried as entries inside the central generic.config.ocm.software/v1 configuration and may appear together:

type: generic.config.ocm.software/v1
configurations:
  - type: transfer.config.ocm.software/v1alpha1
    recursive: -1
  - type: oci.uploader.transfer.config.ocm.software/v1alpha1
  - type: http.uploader.transfer.config.ocm.software/v1alpha1
    match: resource.access.isType("Wget/v1")
    targetURL: '${"https://mytarget.registry.com/uploads" + url(resource.access.url).path}'
    method: PUT

By default the CLI looks for configuration in $HOME/.ocmconfig. Pass --config <file> to use a different file. --recursive overrides the transfer config when set.

Deprecated Flags

The --copy-resources and --upload-as flags are deprecated. They are translated into uploader configuration entries appended after all configured entries. See the migration guide for details.

Uploader Configurations

An uploader configuration routes the resources it selects to a custom target instead of the default handling. Six config types are available:

Each entry is an independent rule; you may declare several.

Selection

For each resource, uploaders are evaluated in declaration order. An uploader selects a resource when its match evaluates to true. An omitted match means the uploader type’s default match; the HTTP, Artifactory, and Nexus uploaders have no default and require match.

The first uploader that selects a resource handles it. There is no fall-through: if the selected uploader cannot handle the resource (for example an OCI uploader selecting a Wget resource, or an imageReference that does not evaluate for the resource), the transfer fails with an error that names the uploader and the resource.

A resource that no uploader selects follows the baseline: local blobs are copied as local blobs; all other resources stay by reference (their access is unchanged in the target). A catch-all localblob.uploader.transfer.config.ocm.software/v1alpha1 entry copies every supported resource. Declare more specific rules before broader ones.

A warning is logged for an uploader whose match selected no resource.

match

match is a plain CEL boolean expression (not wrapped in ${…}). It is evaluated once per resource while the transfer graph is built. The following identifiers are available:

Available functions:

isType semantics

resource.access.isType(arg) receives the resource’s access map and tests its type field against the argument. Both sides are resolved through the transfer access scheme (alias resolution):

• Unversioned argument: matches any version. isType("OCIImage") matches ociArtifact/v1, ociImage/v1, ociRegistry/v1, etc.
• Versioned argument: the resolved types must be equal, so aliases of the same version match (isType("ociImage/v1") matches ociArtifact/v1), but isType("S3/v1") does not match s3/v2.
• Unregistered types (for example Custom/v1) resolve to themselves: isType("Custom") matches Custom/v1 by name.

• Every uploader type except http, artifactory, and nexus has a default match (see the type sections). An explicit match replaces the default entirely; writing the default out is equivalent to omitting it.
• A match that does not compile, does not evaluate, or does not return a bool fails the transfer.

Complete Example

The following shows a full config migrated from the old --copy-resources plus --upload-as ociArtifact style.

type: generic.config.ocm.software/v1
configurations:
  - type: transfer.config.ocm.software/v1alpha1
    recursive: -1
  # 1. Keep the large base image by reference (not copied at all).
  #    Declared first, so the catch-all below never sees it.
  - type: reference.uploader.transfer.config.ocm.software/v1alpha1
    match: resource.name == "base-os-image"
  # 2. Stream wget-hosted documentation to an HTTP artifact store.
  - type: http.uploader.transfer.config.ocm.software/v1alpha1
    match: resource.access.isType("Wget/v1")
    targetURL: '${"https://artifacts.example.com/ocm" + url(resource.access.url).path}'
    method: PUT
  # 3. OCI images, Helm charts and OCI-manifest local blobs become separate OCI
  #    artifacts next to the component version (former --upload-as ociArtifact).
  #    Default match and imageReference.
  - type: oci.uploader.transfer.config.ocm.software/v1alpha1
  # 4. Everything the rules above did not select is embedded as a local blob
  #    (former --copy-resources). Default match.
  - type: localblob.uploader.transfer.config.ocm.software/v1alpha1

Entries 3 and 4 need no fields: their default match (see the OCI Uploader and Local Blob Uploader sections) and the default imageReference are what the former settings did.

Outcome for ocm.software/demo:1.0.0 transferred to ghcr.io/target-org/ocm:

Transferring the same config to a CTF target: entry 3’s match is false for every resource, so app-image and chart are copied as local blobs by entry 4.

Notes

Precedence

For a given resource, uploaders are evaluated in declaration order and the first whose match selects the resource handles it. A selected uploader that cannot handle the resource fails the transfer. A resource no uploader selects follows the baseline: local blobs are copied as local blobs, all other resources stay by reference. See Selection.

Deterministic Plans

Transfer produces a deterministic transformation plan: components are processed in sorted order and transformation identifiers are derived from stable hashes. The plan is rendered with human-readable labels such as my-app@1.0.0 [Stream icons to mytarget.registry.com].

Related Documentation

• Configure Custom Uploads During Transfer — tutorial that walks through an uploader end to end
• Transfer and Transport — the conceptual transfer model
• Working with HTTP Resources — the Wget/v1 type produced by the HTTP streaming uploader
• HTTP Client Configuration — tuning the HTTP client used for the upload
• Migrate from –upload-as to Uploader Configurations — migration from deprecated flags