Migrate from Fallback to Deterministic Repository Resolvers

Goal#

Replace the deprecated ocm.config.ocm.software fallback resolver configuration with the new resolvers.config.ocm.software/v1alpha1 glob-based resolvers.

Why Migrate?#

• The fallback resolver (ocm.config.ocm.software) is deprecated and will be removed in a future release.
• The fallback resolver probes multiple repositories on every lookup, which adds latency and makes it harder to reason about which repository is used.
• Glob-based resolvers use first-match semantics — the outcome is determined by list order alone, making configurations simpler to understand and debug.

Prerequisites#

• OCM CLI installed
• An existing .ocmconfig file that uses ocm.config.ocm.software resolver entries

Steps#

Suppose you have the following legacy resolver config in $HOME/.ocmconfig:

type: generic.config.ocm.software/v1
configurations:
  - type: ocm.config.ocm.software
    resolvers:
      - repository:
          type: OCIRepository/v1
          baseUrl: ghcr.io
          subPath: my-org/team-a
        prefix: my-org.example/services
        priority: 10
      - repository:
          type: OCIRepository/v1
          baseUrl: ghcr.io
          subPath: my-org/team-b
        prefix: my-org.example/libraries
        priority: 10
      - repository:
          type: CommonTransportFormat/v1
          filePath: ./local-archive
        priority: 1

The following steps walk you through each change needed to migrate to glob-based resolvers.

1. Change the config type from ocm.config.ocm.software to resolvers.config.ocm.software/v1alpha1

   Replace the configuration type:

   configurations:
     - type: resolvers.config.ocm.software/v1alpha1  # was: ocm.config.ocm.software
       resolvers:
         ...

2. Replace prefix with componentNamePattern

   The fallback resolver uses prefix to match component names by string prefix. The glob-based resolver uses componentNamePattern, which supports glob patterns. In most cases, appending /* to the old prefix is the closest equivalent. Note that the old prefix also matched the bare prefix itself as an exact component name (e.g. prefix: my-org.example/services matched both my-org.example/services and my-org.example/services/foo). If you have components that match the bare prefix, use {,/*} instead:

       resolvers:
         - repository:
             type: OCIRepository/v1
             baseUrl: ghcr.io
             subPath: my-org/team-a
           # matches my-org.example/services and my-org.example/services/*
           componentNamePattern: "my-org.example/services{,/*}"  # was: prefix: my-org.example/services

   If no component uses the bare prefix as its name (which is the common case), /* is sufficient:

           componentNamePattern: "my-org.example/services/*"  # was: prefix: my-org.example/services

   If a resolver had an empty prefix (matching all components), use * as the pattern:

           componentNamePattern: "*"  # was: prefix: "" (or no prefix)

3. Remove the priority field

   Glob-based resolvers do not use priorities. Instead, resolvers are evaluated in the order they appear in the list, and the first match wins. That’s one of the key differences from the fallback resolver, which tries all matching resolvers in priority order until one succeeds. If your legacy resolvers had equal priority values, keep their original list order to preserve the same resolution behaviour (the fallback resolver uses a stable sort, so equal-priority entries were tried in insertion order).

   For new configs, place more specific patterns before broader ones:

       resolvers:
         # specific patterns first
         - repository:
             type: OCIRepository/v1
             baseUrl: ghcr.io
             subPath: my-org/team-a
           componentNamePattern: "my-org.example/services/*"
         # broader patterns last
         - repository:
             type: CommonTransportFormat/v1
             filePath: ./local-archive
           componentNamePattern: "*"

4. Review the final config

   Your migrated config should now look like this:

   type: generic.config.ocm.software/v1
   configurations:
     - type: resolvers.config.ocm.software/v1alpha1
       resolvers:
         - repository:
             type: OCIRepository/v1
             baseUrl: ghcr.io
             subPath: my-org/team-a
           componentNamePattern: "my-org.example/services/*"
         - repository:
             type: OCIRepository/v1
             baseUrl: ghcr.io
             subPath: my-org/team-b
           componentNamePattern: "my-org.example/libraries/*"
         - repository:
             type: CommonTransportFormat/v1
             filePath: ./local-archive
           componentNamePattern: "*"

5. Verify

   Run any OCM command that resolves components:

   ocm get cv ghcr.io/my-org/team-a//my-org.example/services/my-service:1.0.0 \
     --recursive=-1 --config .ocmconfig

   If you still see the warning using deprecated fallback resolvers, consider switching to glob-based resolvers, check that you removed all ocm.config.ocm.software configuration blocks. Both resolver types can coexist in the same config file during migration — the fallback resolvers will still work but will emit the deprecation warning.

Key Differences#

When You Cannot Migrate Yet#

The fallback resolver has a probe-and-retry behaviour that the glob-based resolver does not replicate.

Consider a registry migration where the same component has versions spread across multiple repositories:

  - type: ocm.config.ocm.software
    resolvers:
      - repository:
          type: OCIRepository/v1
          baseUrl: new-registry.example
          subPath: current
        prefix: my-org.example
        priority: 10
      - repository:
          type: OCIRepository/v1
          baseUrl: old-registry.example
          subPath: legacy
        prefix: my-org.example
        priority: 1

  - type: resolvers.config.ocm.software/v1alpha1
    resolvers:
      # Only new-registry is queried — old versions are unreachable
      - repository:
          type: OCIRepository/v1
          baseUrl: new-registry.example
          subPath: current
        componentNamePattern: "my-org.example/*"

The same applies to listing component versions: the fallback resolver accumulates versions from all matching repositories, while the glob-based resolver only queries the first match.

If either case applies, consolidate all versions of the affected components into a single repository before migrating your resolver config. Version-based matching is being tracked as a future feature in ocm-project#941.

What’s Next?#

• How-To: Resolving Components Across Multiple Registries — Configure resolver entries for multi-registry setups
• Resolver Configuration Reference — Full configuration schema and pattern syntax
• Resolvers — High-level introduction to resolvers