fix: hex-encode OCI layout image name to avoid validation errors#1954
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates the containersimageregistry OCI-layout cache keying to avoid OCI ref.name validation failures when Docker image tags contain characters that OCI layout does not permit (e.g. __). It does this by hex-encoding the full image reference string before passing it to layout.NewReference.
Changes:
- Add
layoutKey(ref string)which hex-encodes the reference into an OCI-ref-name-safe string. - Use
layoutKey(ref.String())when creating OCI layout references inPull,Unpack, andLabels.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // layoutKey returns a deterministic, OCI-ref-name-safe key for the given | ||
| // image reference. Docker tags allow characters (e.g. "__") that are not | ||
| // valid in OCI layout ref.name annotations, so we hex-encode the reference | ||
| // instead of using it directly. | ||
| func layoutKey(ref string) string { | ||
| return hex.EncodeToString([]byte(ref)) | ||
| } |
There was a problem hiding this comment.
Changing the OCI layout key from the raw ref string to a hex-encoded value will effectively invalidate any existing on-disk cache entries when OLM_CACHE_DIR is set (preserve=true), forcing images to be re-pulled and making older cache entries unreachable by Unpack/Labels. If persistent cache reuse across runs is expected, consider a backward-compatible fallback (try the legacy raw ref.name when the new key is missing) and/or a one-time migration/cleanup strategy, or clearly document this cache-key change as a breaking cache behavior.
There was a problem hiding this comment.
Image re-pulling is already optimized by containers/image internals and is not related to the use of the org.opencontainers.image.ref.name annotation.
That annotation is written by Pull and then read by Unpack and Labels. If someone pulls using the new Pull method, but then unpacks/gets labels with the old Unpack and Labels methods, that would be a problem. But it is not intended for different versions of the library to be used for different image interactions.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #1954 +/- ##
=======================================
Coverage 57.70% 57.71%
=======================================
Files 139 139
Lines 13371 13373 +2
=======================================
+ Hits 7716 7718 +2
Misses 4468 4468
Partials 1187 1187 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
eebc916 to
7332146
Compare
Docker tags allow characters (e.g. "__") that are not valid in OCI layout ref.name annotations. Instead of passing the raw image reference as the OCI layout image name, hex-encode it to produce a string that always satisfies the OCI ref.name regex. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
7332146 to
becb80f
Compare
| @@ -0,0 +1 @@ | |||
| sha256:a1bec450c104ceddbb25b252275eb59f1f1e6ca68e0ced76462042f72f7057d8 No newline at end of file | |||
There was a problem hiding this comment.
do we care about empty new line at the end of the file?
| @@ -0,0 +1 @@ | |||
| sha256:a1bec450c104ceddbb25b252275eb59f1f1e6ca68e0ced76462042f72f7057d8 No newline at end of file | |||
|
/lgtm |
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: grokspawn The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
2c26996
into
operator-framework:master
Description of the change:
Hex-encode the image reference string when using it as the OCI layout
ref.nameannotation in the containers/image registry cache. Docker tags allow characters (e.g.__) that are not valid in OCI layout ref.name annotations, causingopm renderto fail withInvalid imageerrors for images with such tags.The
layoutKey()function hex-encodes the reference string, producing a value that is always valid per the OCI ref.name regex while remaining reversible for debugging.Motivation for the change:
Running
opm renderon images with double underscores in their tags (e.g.quay.io/redhat-user-workloads/ocp-art-tenant/art-fbc:oadp-1.6__v4.22__oadp-rhel9-operator) fails because thecontainersimageregistryPullmethod passes the raw docker reference as the OCI layout image name, and the OCI ref.name annotation format is stricter than docker tag rules.Reviewer Checklist
/docsGenerated with Claude Code