Resolving Components across Multiple Registries

Goal#

Configure an .ocmconfig file with resolver entries so the OCM CLI can recursively resolve component references stored in different OCI registries.

Prerequisites#

• OCM CLI installed
• Components already pushed to separate OCI registries
• An OCM configuration file (see .ocmconfig documentation)

Steps#

1. Create an .ocmconfig with resolver entries

   Add a resolver entry for each registry where referenced components are stored. Replace the placeholder values with your own registry, paths, and component names.

   Assume you have a root component <root-component> that references <component-a> and <component-b>, each stored in a different repository:

   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: <registry>                 # e.g. ghcr.io
             subPath: <subpath-a>                # e.g. my-org/team-a
           componentNamePattern: "<component-a>" # e.g. my-org.example/component-a
         - repository:
             type: OCIRepository/v1
             baseUrl: <registry>                 # e.g. ghcr.io
             subPath: <subpath-b>                # e.g. my-org/team-b
           componentNamePattern: "<component-b>" # e.g. my-org.example/component-b

2. Resolve the root component recursively

   Point the CLI at the root component and pass your config file:

   ocm add cv --repository <registry>/<root-subpath> \
     --constructor <constructor>.yaml \
     --config .ocmconfig

   or

   ocm get cv <registry>/<root-subpath>//<root-component>:<version> \
     --recursive=-1 --config .ocmconfig

   add cv uploads a component version to the registry using the resolver config to locate referenced components. get cv --recursive walks the full component graph and lists all transitively referenced components.

   Example

   ocm add cv --repository ghcr.io/my-org/components \
     --constructor root-constructor.yaml \
     --config .ocmconfig

   ocm get cv ghcr.io/my-org/components//my-org.example/root-component:1.0.0 \
     --recursive=-1 --config .ocmconfig

3. Verify the output

   The output should list the root component and all transitively referenced components. If a referenced component is missing, check that there is a matching resolver entry for it.

   Example output

   COMPONENT                          │ VERSION │ PROVIDER
   ───────────────────────────────────┼─────────┼──────────
   my-org.example/root-component      │ 1.0.0   │ my-org
   my-org.example/component-a         │ 1.0.0   │
   my-org.example/component-b         │ 1.0.0   │

Tips#

• If multiple components share a registry path, use a glob pattern (e.g. example.com/services/*) instead of listing each component individually. See Component Name Patterns for the full syntax.
• If you need to transfer components to another registry, use ocm transfer cv --recursive --copy-resources with the same config file. See OCM Transfer for details.
• Resolvers are evaluated in order — place more specific patterns before broader ones so the right repository is matched first.

Next Steps#

• Tutorial: Understand Credential Resolution — Configure registry credentials
• Tutorial: Working with Resolvers — Hands-on tutorial for building and pushing components with resolvers

Related Documentation#

• How-To: Migrate from Deprecated Resolvers — Replace deprecated fallback resolvers with glob-based resolvers
• Concept: Resolvers — High-level introduction to resolvers
• Reference: Resolver Configuration — Full configuration schema, repository types, and pattern syntax