Add support for oci:// URLs to fetch RPMs from OCI registries

[lcarva]

Currently, the Hermeto lock file requires an http:// or https:// URL in the url field for each RPM entry. This limits the sources from which RPMs can be fetched. I would like to store and distribute RPMs in OCI-compliant registries and have Hermeto fetch them directly.

I propose extending the url field to support an oci:// scheme. This would allow Hermeto to pull RPMs from an OCI registry, where the RPM is stored as a layer in an OCI artifact.

An entry in rpms.lock.yaml would, partially, look like this:

- name: aardvark-dns
  checksum: sha256:deadbeef...
  url: oci://registry.example.com/rpms/aardvark-dns:1.14.0

The oci:// URL points to an OCI Image Manifest or an Image Index that describes an OCI Artifact. The manifest will likely contain one or more layers (blobs). The checksum value from the lock file entry corresponds to the digest of the correct RPM layer. Hermeto should fetch the manifest, find the layer with the matching digest, and download it. Alternatively, it is possible to fetch the layer directly from the registry using its digest (the checksum value).

Standard OCI registry authentication mechanisms (e.g., ~/.docker/config.json) should be supported.

[lcarva]

I'm gonna direct my bot towards this issue to create a pull request so we can explore the rough edges of this idea. Let me know if that's a problem and I'll stop it.

[gnotlooy]

Hey! I'd love to pick up this issue and implement oci:// URL support for RPM fetching.

After diving into the codebase, here's my implementation approach:

Current Architecture Understanding:

• RPMs are fetched via async_download_files() in the general module
• URLs are stored in LockfilePackage.url field and passed directly to download
• Download flow: URL -> async_download_files() -> verify checksum

Implementation Plan:

1. Add OCI dependencies - Add container registry client library (like oci or docker-py)
2. URL scheme detection - Modify download logic to detect oci:// URLs and route them differently
3. OCI manifest/layer fetching - Implement OCI registry client to:
   • Authenticate using standard ~/.docker/config.json
   • Fetch image manifest from oci://registry/repo:tag
   • Find layer matching the lockfile checksum
   • Download the matching layer blob
4. Integration - Hook into existing _download() function in rpm/main.py seamlessly
5. Error handling - Add proper validation and error messages for OCI operations
6. Testing - Add unit tests for OCI URL parsing and integration tests

This keeps the existing http/https flow unchanged while cleanly adding oci:// support. The checksum matching ensures we get the right RPM layer from the OCI artifact.

I'll start working on this and submit a PR. Let me know if you have any feedback on the approach!

[eskultety]

Thank you for the interest in adding this functionality. As far as upstream is concerned, my personal take on this based on

⚠️ This backend is best-effort only and apart from bug fixes we may be reluctant to introduce new functionality (unless trivially added), especially one that would require architectural OR rpms.lock.yaml schema changes simply because there's a native DNF solution in the making which we expect will fully replace and hence deprecate this backend. ⚠️

in https://github.com/hermetoproject/hermeto/blob/main/docs/rpm.md is that this work primarily has to happen and mature in the DNF land itself, we have no intention to keep maintaining the custom half-baked, no formal schema backed YAML for the RPM lockfile. We might consider this work for downstream as a temporary solution for the time being until the larger ecosystem catches up, but that is outside of this repo where we're strictly trying to be community oriented and rely on vetted technologies rather than emerging bleeding edge solutions that we (partly) end up being the owners of.
That all said, I think a few questions are still worth answering to complete the request:

• do you have a tangible use case for this where and how you'd like to consume it?
• what does resolve & generate the lockfile in this case including transitive OCI dependencies?
• is there any repo metadata support for OCI artifacts regarding the artifact resolution in place today?

I feel like there's a need for a new standard on how to approach OCI artifacts from RPM perspective and I'd very much like to avoid our team getting into DNF land matters and try defining one like we tried with the lockfile attempt which wasn't the best of designs without having the DNF folks know-how (e.g. non-persistent URLs).
I would also like to avoid dealing with OCI artifacts in different backends, i.e. for RPM-based ones in rpms.lock.yaml and in the generic backend, i.e. artifacts.lock.yaml by adding support for generic OCI-style URIs backed by the oras tool.
^These are all very important questions and details to iron out first that an AI-generated lump of code isn't going to do without a proper investigation of the case I'm afraid.

[ben-alkov]

100% agree with Erik, and

resolve & generate the lockfile

this is waay outside the scope of what Hermeto's mission is, so at a minimum, someone else would have to create this tool.

[lcarva]

Thank you for the feedback!

I feel like there's a need for a new standard on how to approach OCI artifacts from RPM perspective and I'd very much like to avoid our team getting into DNF land matters and try defining one like we tried with the lockfile attempt which wasn't the best of designs without having the DNF folks know-how (e.g. non-persistent URLs).

I wasn't aware of libpkgmanifest. It is interesting that the RPM lock format they provide differs from the RPM lock file here in some important ways. Mainly, the URL is per YUM repo instead of per RPM. That makes sense for YUM repos. I can take the conversation there as I agree that's where this idea should evolve and mature.

We might consider this work for downstream as a temporary solution for the time being until the larger ecosystem catches up, but that is outside of this repo

Can you point me to where downstream work is captured and discussed? I'm happy to progress in that front instead.

do you have a tangible use case for this where and how you'd like to consume it?

Yes, I'm exploring with @brianwcook a way to manage RPM composes in Konflux. He can probably provide more details on this, but the general idea is to use the OCI registry as the storage backend in the form of OCI Artifacts.

what does resolve & generate the lockfile in this case including transitive OCI dependencies?
this is waay outside the scope of what Hermeto's mission is, so at a minimum, someone else would have to create this tool.

Agree that generating that lockfile is outside the scope of hermeto. Apologies if I gave the wrong impression. For now, the idea is to use specialized scripts that can perform these operations. I'd like to use a floating tag for OCI Artifacts and a digest. This would, in theory, allow us to track when a new version exists.

is there any repo metadata support for OCI artifacts regarding the artifact resolution in place today?

Not that I'm aware of. It sounds like a topic for libpkgmanifest.

I would also like to avoid dealing with OCI artifacts in different backends, i.e. for RPM-based ones in rpms.lock.yaml and in the generic backend, i.e. artifacts.lock.yaml by adding support for generic OCI-style URIs backed by the oras tool.

Maybe. OCI Artifacts are just a storage type. They don't implement the context or intricacies of the different package managers. If OCI Artifacts continue to be a successful storage solution, you may end up with having to support that kind of storage in different backends. But I'm speculating. I understand your point.

^These are all very important questions and details to iron out first that an AI-generated lump of code isn't going to do without a proper investigation of the case I'm afraid.

I was simply exploring what is possible which IMO is what AI-generated code excels at. I wanted to do this exploration in the open for the curious eyes out there. You may have noticed that I closed out that PR shortly after it was open. Apologies if that caused stress of any form.

[brianwcook]

I think all we are proposing here is taking the current support for rpm and adding fetch support for OCI in addition to http. The extent of changes to the lockfile itself wll just be "s/http:/oci:". We all agree that the dnf lockfile itself needs work and more involvement from dnf community, but I am also hoping that this will nudge them in a particular direction.

[eskultety]

Mainly, the URL is per YUM repo instead of per RPM. That makes sense for YUM repos.

Yes, in DNF's context as a native tool that's what it should have been all along, but the implementation and idea was sadly rushed.

I can take the conversation there as I agree that's where this idea should evolve and mature.

Perfect, please do, I can tell you for a fact that ^this OCI idea is something @cgwalters might also be interested in based on his feedback in some past issue I can't remember anymore.

If OCI Artifacts continue to be a successful storage solution, you may end up with having to support that kind of storage in different backends

That's the thing, I don't think injecting this into several backends is a sustainable way forward, that's why I'm advocating for more thorough exploration and understanding of the matter here. If OCI ever becomes the defacto standard as you envision, then it automatically becomes its own ecosystem, so designing the approach around this approach may turn out to be a simpler thing to do than just add bits here and there to the existing backends and then at some point get rid of them.

I was simply exploring what is possible which IMO is what AI-generated code excels at.
You may have noticed that I closed out that PR shortly after it was open.

@lcarva That's fine and you absolutely did close it! No apologies needed, I was merely trying to point out that using an AI generated code right away without having the problem hashed out in an issue discussion would simply not fly and would very likely not lead to a speedy review & merge.

The extent of changes to the lockfile itself wll just be "s/http:/oci:". We all agree that the dnf lockfile itself needs work and more involvement from dnf community, but I am also hoping that this will nudge them in a particular direction.

@brianwcook I get ^this, but see my points above, it all may sounds just like a different protocol implementation - nobrainer - but having learnt something from the RPM backend experience, I'd like to understand this to a larger extent before we jump into implementing something there isn't really any tooling available to integrate with in the first place.

[cgwalters]

Lots of links from rpm-software-management/librepo#323 (also directly to coreos/rpm-ostree#4155 )

[cgwalters]

Also related to lockfiles I will reiterate here because it's really important that I think we should change RHEL to do this: rpm-software-management/dnf5#833 (comment)

If we did this 95% of the lockfile YAML use cases would go away for RHT products, and "update packages in an image" would always be "update the base image digest, the end".

[cgwalters]

We might consider this work for downstream as a temporary solution for the time being until the larger ecosystem catches up, but that is outside of this repo where we're strictly trying to be community oriented and rely on vetted technologies rather than emerging bleeding edge solutions that we (partly) end up being the owners of.

Valid concern, but honestly...looking at the PR there I don't see any glaring flaws and we could certainly use it as a driving example use case for making OCI be first class in dnf.

There's various implementation details to bikeshed, like using skopeo vs oras vs whatever and in the end we'd probably want a standalone tool like dnf-oci-fetch-prototype or something but I wouldn't fully block on landing this in dnf. I would say we want engagement from the team though and commitment to generalizing it.

[eskultety]

Valid concern, but honestly...looking at the PR there I don't see any glaring flaws and we could certainly use it as a driving example use case for making OCI be first class in dnf.

Like I said I'm not opposed to temporary (downstream) solution, but I want to emphasize the need to keep this work in sync with the work in the DNF ecosystem for a smooth transition and now that you linked rpm-software-management/librepo#323 I think this gives us the opportunity to do just that!

There's various implementation details to bikeshed, like using skopeo vs oras vs whatever and in the end we'd probably want a standalone tool like dnf-oci-fetch-prototype or something but I wouldn't fully block on landing this in dnf.

See my point above, I'm not shutting it down, but I'm not in favour of building a completely different solution behind making the transition painful.

I would say we want engagement from the team though and commitment to generalizing it.

Yep, agreed.