docs: Add how-to for migrating fallback resolvers to path matcher resolvers (#748)

matthiasbruns · jakobmoellerdev · web-flow · commit 1f0c8b2e58cd · 2026-03-11T13:11:24.000+01:00
#### What this PR does / why we need it Adds a new how-to guide that walks users through migrating their `.ocmconfig` from the deprecated `ocm.config.ocm.software` fallback resolvers to the new `resolvers.config.ocm.software/v1alpha1` path matcher resolvers. The guide covers: - Step-by-step config migration (`prefix` → `componentNamePattern`, removing `priority`, changing the config type) - A "When You Cannot Migrate Yet" section with mermaid diagrams showing the behavioral difference (probe-and-retry vs first-match-wins) - A concrete example of a registry migration scenario where fallback resolvers are still needed - A key differences comparison table #### Which issue(s) this PR is related to Related to open-component-model/ocm-project#927 #### Type of content - [ ] Tutorial (`getting-started/` or `tutorials/`) - [x] How-to Guide (`how-to/`) - [ ] Explanation / Concept (`concepts/`) - [ ] Reference (`reference/`) - [ ] Other (infrastructure, config, fixes) #### Checklist - [x] I have read and followed the [Contributing Guide](https://github.com/open-component-model/ocm-website/blob/main/CONTRIBUTING.md) - [x] All commands/code snippets are tested and can be copy-pasted #### Testing Fully tested with ##### .ocmconfig-legacy ```yaml type: generic.config.ocm.software/v1 configurations: - type: credentials.config.ocm.software repositories: - repository: type: DockerConfig/v1 dockerConfigFile: "~/.docker/config.json" - type: ocm.config.ocm.software resolvers: - repository: type: OCIRepository/v1 baseUrl: ghcr.io subPath: matthiasbruns/ocm-tutorial-migrate-a prefix: ocm.software/tutorials/backend priority: 10 - repository: type: OCIRepository/v1 baseUrl: ghcr.io subPath: matthiasbruns/ocm-tutorial-migrate-b prefix: ocm.software/tutorials/frontend priority: 10 ``` ##### .ocmconfig-migrated ```yaml type: generic.config.ocm.software/v1 configurations: - type: credentials.config.ocm.software repositories: - repository: type: DockerConfig/v1 dockerConfigFile: "~/.docker/config.json" - type: resolvers.config.ocm.software/v1alpha1 resolvers: - repository: type: OCIRepository/v1 baseUrl: ghcr.io subPath: matthiasbruns/ocm-tutorial-migrate-a componentNamePattern: "ocm.software/tutorials/backend" - repository: type: OCIRepository/v1 baseUrl: ghcr.io subPath: matthiasbruns/ocm-tutorial-migrate-b componentNamePattern: "ocm.software/tutorials/frontend" ``` ##### app-constructor.yam ```yaml components: - name: ocm.software/tutorials/app version: "1.0.0" provider: name: ocm.software componentReferences: - name: backend-service componentName: ocm.software/tutorials/backend version: "1.0.0" - name: frontend-service componentName: ocm.software/tutorials/frontend version: "1.0.0" resources: - name: config version: "1.0.0" type: plainText input: type: utf8 text: "app deployment configuration" ``` ##### backend-constructor.yaml ```yaml components: - name: ocm.software/tutorials/backend version: "1.0.0" provider: name: ocm.software resources: - name: config version: "1.0.0" type: plainText input: type: utf8 text: "backend service configuration" ``` ##### frontend-constructor.yaml ```yaml components: - name: ocm.software/tutorials/frontend version: "1.0.0" provider: name: ocm.software resources: - name: config version: "1.0.0" type: plainText input: type: utf8 text: "frontend service configuration" ``` ##### test-migrate-resolvers.sh ```bash #!/bin/bash set -x echo $GITHUB_TOKEN | docker login ghcr.io -u ${GITHUB_USERNAME} --password-stdin # Step 1: Push backend and frontend components (no resolvers needed for leaf components) ./ocm add cv --repository ghcr.io/matthiasbruns/ocm-tutorial-migrate-a \ --constructor backend-constructor.yaml \ --component-version-conflict-policy replace \ --config ./ocm add cv --repository ghcr.io/matthiasbruns/ocm-tutorial-migrate-b \ --constructor frontend-constructor.yaml \ --component-version-conflict-policy replace \ --config # Step 2: Push app component using the LEGACY fallback config # This should work but emit a deprecation warning about fallback resolvers ./ocm add cv --repository ghcr.io/matthiasbruns/ocm-tutorial-migrate-app \ --constructor app-constructor.yaml \ --component-version-conflict-policy replace \ --config .ocmconfig-legacy # Step 3: Verify recursive resolution works with the legacy config ./ocm get cv ghcr.io/matthiasbruns/ocm-tutorial-migrate-app//ocm.software/tutorials/app:1.0.0 \ --config .ocmconfig-legacy --recursive=-1 # Step 4: Verify recursive resolution works with the MIGRATED config ./ocm get cv ghcr.io/matthiasbruns/ocm-tutorial-migrate-app//ocm.software/tutorials/app:1.0.0 \ --config .ocmconfig-migrated --recursive=-1 # Step 5: Push app component again using the migrated config (no deprecation warning) ./ocm add cv --repository ghcr.io/matthiasbruns/ocm-tutorial-migrate-app \ --constructor app-constructor.yaml \ --component-version-conflict-policy replace \ --config .ocmconfig-migrated # Step 6: Final verification with migrated config ./ocm get cv ghcr.io/matthiasbruns/ocm-tutorial-migrate-app//ocm.software/tutorials/app:1.0.0 \ --config .ocmconfig-migrated --recursive=-1 ```  ## Summary by CodeRabbit * **Documentation** * Added a new migration guide with step‑by‑step instructions, examples, verification steps, troubleshooting notes, coexistence guidance, and a “when you cannot migrate yet” section. * Updated resolver-related docs, tutorials, and tips with links and a callout directing readers to the new migration guide.  --------- Signed-off-by: Matthias Bruns <git@matthiasbruns.com> Signed-off-by: Matthias Bruns <github@matthiasbruns.com> Co-authored-by: Jakob Möller <contact@jakob-moeller.com>
diff --git a/content/docs/concepts/resolvers.md b/content/docs/concepts/resolvers.md
@@ -76,3 +76,5 @@ For more information about OCM transfer, see the [Transfer and Transport]({{< re
 - [Understand Credential Resolution]({{< relref "docs/tutorials/credential-resolution.md" >}}) — Configure credentials for OCI registries
 - [How to Transfer Components Across an Air Gap]({{< relref "docs/how-to/air-gap-transfer.md" >}}) — Use OCM Transfer to move components between
   air-gapped environments
+- [Migrate from Deprecated Resolvers]({{< relref "docs/how-to/migrate-from-deprecated-resolvers.md" >}}) — Replace deprecated fallback
+  resolvers with glob-based resolvers
diff --git a/content/docs/how-to/migrate-from-deprecated-resolvers.md b/content/docs/how-to/migrate-from-deprecated-resolvers.md
@@ -0,0 +1,262 @@
+---
+title: "Migrate from Fallback to Deterministic Repository Resolvers"
+description: "Replace deprecated fallback resolvers with glob-based resolvers for deterministic and efficient component resolution."
+weight: 100
+toc: true
+---
+
+## Goal
+
+Replace the deprecated `ocm.config.ocm.software` fallback resolver configuration with the new `resolvers.config.ocm.software/v1alpha1` glob-based
+resolvers.
+
+{{< callout context="caution" >}}
+The fallback resolver (`ocm.config.ocm.software`) is deprecated. It uses priority-based ordering with prefix matching and probes multiple
+repositories until one succeeds. The glob-based resolver (`resolvers.config.ocm.software/v1alpha1`) replaces it with first-match glob-based matching
+against component names, which is simpler and more efficient.
+{{< /callout >}}
+
+## 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]({{< relref "/docs/getting-started/ocm-cli-installation.md" >}}) installed
+- An existing `.ocmconfig` file that uses `ocm.config.ocm.software` resolver entries
+
+## Steps
+
+Suppose you have the following legacy resolver config in `~/.ocmconfig`:
+
+```yaml
+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.
+
+{{< steps >}}
+
+{{< step >}}
+**Change the config type from `ocm.config.ocm.software` to `resolvers.config.ocm.software/v1alpha1`**
+
+Replace the configuration type:
+
+```yaml
+configurations:
+  - type: resolvers.config.ocm.software/v1alpha1  # was: ocm.config.ocm.software
+    resolvers:
+      ...
+```
+
+{{< /step >}}
+
+{{< step >}}
+**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]({{< relref "docs/reference/resolver-configuration.md#component-name-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:
+
+```yaml
+    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:
+
+```yaml
+        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:
+
+```yaml
+        componentNamePattern: "*"  # was: prefix: "" (or no prefix)
+```
+
+{{< /step >}}
+
+{{< step >}}
+**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:
+
+```yaml
+    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: "*"
+```
+
+{{< /step >}}
+
+{{< step >}}
+**Review the final config**
+
+Your migrated config should now look like this:
+
+```yaml
+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: "*"
+```
+
+{{< /step >}}
+
+{{< step >}}
+**Verify**
+
+Run any OCM command that resolves components:
+
+```bash
+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.
+
+{{< /step >}}
+
+{{< /steps >}}
+
+## Key Differences
+
+|                      | Fallback (`ocm.config.ocm.software`)                              | Glob-based (`resolvers.config.ocm.software/v1alpha1`) |
+|----------------------|-------------------------------------------------------------------|-------------------------------------------------------|
+| **Matching**         | String prefix on component name                                   | Glob pattern (`*`, `?`, `[...]`) on component name    |
+| **Resolution order** | Priority-based (highest first), then fallback through all matches | First match wins (list order)                         |
+| **Get behaviour**    | Tries all matching repos until one succeeds                       | Returns the first matching repo deterministically     |
+| **Add behaviour**    | Adds to the first matching repo by priority                       | Adds to the first matching repo by list order         |
+| **Status**           | Deprecated                                                        | Active                                                |
+
+## 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:
+
+| Version                             | Repository                     |
+|-------------------------------------|--------------------------------|
+| `my-org.example/my-component:1.0.0` | `old-registry.example/legacy`  |
+| `my-org.example/my-component:1.5.0` | `old-registry.example/legacy`  |
+| `my-org.example/my-component:2.0.0` | `new-registry.example/current` |
+
+{{< tabs >}}
+{{< tab "Fallback (works)" >}}
+
+The fallback resolver matches repositories by **prefix** and tries them in **priority order**. If the requested version is not found in the
+highest-priority repository, it falls back to the next one until it finds a match or exhausts the list.
+
+In this example, both resolvers share the prefix `my-org.example`. A request for `my-component:2.0.0` finds it in the new registry (priority 10). A
+request for `my-component:1.0.0` misses in the new registry, falls back to the old one (priority 1), and succeeds.
+
+```yaml
+  - 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
+```
+
+{{< /tab >}}
+{{< tab "Glob-based (breaks)" >}}
+
+The glob-based resolver matches the component name against patterns in list order and returns the **first match** — it does not probe the repository
+or retry with the next resolver if the version is missing.
+
+In this example, `componentNamePattern: "my-org.example/*"` points to the new registry only. Requesting `my-component:2.0.0` succeeds, but requesting
+`my-component:1.0.0` fails because the old registry is not configured and there is no fallback.
+
+```yaml
+  - 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/*"
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
+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](https://github.com/open-component-model/ocm-project/issues/941).
+
+## What's Next?
+
+- [How-To: Resolving Components Across Multiple Registries]({{< relref "resolve-components-from-multiple-repositories.md" >}}) — Configure resolver
+  entries for multi-registry setups
+- [Resolver Configuration Reference]({{< relref "docs/reference/resolver-configuration.md" >}}) — Full configuration schema and pattern syntax
+- [Resolvers]({{< relref "docs/concepts/resolvers.md" >}}) — High-level introduction to resolvers
diff --git a/content/docs/how-to/resolve-components-from-multiple-repositories.md b/content/docs/how-to/resolve-components-from-multiple-repositories.md
@@ -115,6 +115,10 @@ my-org.example/component-b         │ 1.0.0   │
 
 {{< /steps >}}
 
+{{< callout context="tip" >}}
+If you are migrating from the deprecated `ocm.config.ocm.software` fallback resolvers, see [Migrate from Deprecated Resolvers]({{< relref "migrate-from-deprecated-resolvers.md" >}}) for a step-by-step guide.
+{{< /callout >}}
+
 ## Tips
 
 - **If multiple components share a registry path**, use a glob pattern (e.g. `example.com/services/*`) instead of
@@ -133,3 +137,5 @@ my-org.example/component-b         │ 1.0.0   │
 - [Working with Resolvers Tutorial]({{< relref "docs/tutorials/configure-resolvers.md" >}}) — Hands-on tutorial for
   building and pushing components with resolvers
 - [Understand Credential Resolution]({{< relref "docs/tutorials/credential-resolution.md" >}}) — Configure registry credentials
+- [Migrate from Deprecated Resolvers]({{< relref "migrate-from-deprecated-resolvers.md" >}}) — Replace deprecated fallback
+  resolvers with glob-based resolvers
diff --git a/content/docs/reference/resolver-configuration.md b/content/docs/reference/resolver-configuration.md
@@ -124,3 +124,5 @@ The first matching resolver wins. Place more specific patterns before broader on
 - [Working with Resolvers Tutorial]({{< relref "docs/tutorials/configure-resolvers.md" >}}) — Hands-on walkthrough for setting up resolvers
 - [How to Resolve Components Across Multiple Registries]({{< relref "docs/how-to/resolve-components-from-multiple-repositories.md" >}}) — Recipe for
   multi-registry resolution
+- [Migrate from Deprecated Resolvers]({{< relref "docs/how-to/migrate-from-deprecated-resolvers.md" >}}) — Replace deprecated fallback
+  resolvers with glob-based resolvers
diff --git a/content/docs/tutorials/configure-resolvers.md b/content/docs/tutorials/configure-resolvers.md
@@ -336,3 +336,5 @@ Now that you know how to configure resolvers, you can:
   and access types (by reference)
 - [Signing and Verification]({{< relref "signing-and-verification.md" >}}) — Sign and verify component versions with
   cryptographic keys
+- [Migrate from Deprecated Resolvers]({{< relref "docs/how-to/migrate-from-deprecated-resolvers.md" >}}) — Replace deprecated fallback
+  resolvers with glob-based resolvers
