OCPBUGS-73760: fix conversion issue for catalog

[aguidirh]

Description

This PR fixes a critical bug where mirroring operator catalogs to certain registries (like Nexus) fails with the error: Manifest list must be converted to type "application/vnd.docker.distribution.manifest.list.v2+json" to be written to destination, but we cannot modify it: "Instructed to preserve digests"

The root cause was that when oc-mirror rebuilds/filters operator catalogs, it sets PreserveDigests=true for all images. However, rebuilt catalogs have already been modified (filtered), so their digests differ from the original. When copying these rebuilt catalogs to registries that require Docker v2 manifest format conversion, the conversion is blocked by the PreserveDigests flag, causing the mirror operation to fail.

Solution: Set PreserveDigests=false for rebuilt operator catalogs, allowing necessary manifest format conversions while maintaining digest preservation for unmodified images (bundles, related images, etc.).

Github / Jira issue: OCPBUGS-73760

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Code Improvements (Refactoring, Performance, CI upgrades, etc)
• Internal repo assets (diagrams / docs on github repo)
• This change requires a documentation update on openshift docs

How Has This Been Tested?

Test Configuration:

• Nexus OSS 3.37.3 running in a container with Docker registry on port 8082
• ImageSet configuration targeting registry.redhat.io/redhat/redhat-operator-index:v4.17
• oc-mirror v2 mirroring to Nexus registry

Test Steps:

1. Set up Nexus with a Docker hosted repository
2. Create an ImageSetConfiguration with operator catalogs requiring filtering
3. Run: ./bin/oc-mirror -c <config>.yaml --workspace file://<path> docker://127.0.0.1:8082 --dest-tls-verify=false --v2
4. Verify all operator images (including the rebuilt catalog) mirror successfully

Expected Outcome

Before the fix:

• Mirroring fails with error: Manifest list must be converted to type "application/vnd.docker.distribution.manifest.list.v2+json" to be written to destination, but we cannot modify it: "Instructed to preserve digests"
• Operator catalog image fails to copy to the destination registry
• Related operator bundles are skipped due to catalog failure

After the fix:

• ✅ All 74 operator images (including the rebuilt catalog) mirror successfully
• ✅ Catalog successfully copies from cache to destination registry (Nexus)
• ✅ No manifest conversion errors
• ✅ Digest preservation still works for non-rebuilt images (bundles, related images)

Logs showing success:

2026/01/09 19:16:01 [INFO] : Success copying docker://registry.redhat.io/redhat/redhat-operator-index:v4.17 ➡️ 127.0.0.1:8082/redhat/
2026/01/09 19:16:03 [INFO] : Success copying docker://registry.redhat.io/redhat/redhat-operator-index:v4.17 ➡️ cache
2026/01/09 19:16:03 [INFO] : === Results ===

Additional Notes

This fix specifically targets rebuilt/filtered operator catalogs (identified by img.Type.IsOperatorCatalog() && img.RebuiltTag != ""). The change:

• Does NOT affect digest preservation for operator bundles and related images
• Only applies when a catalog has been rebuilt/filtered by oc-mirror
• Allows manifest format conversion when required by the destination registry
• Is safe because rebuilt catalogs already have different digests than the original

This resolves the issue for registries like Nexus that require Docker v2 manifest format but was previously blocked by the digest preservation constraint.

[openshift-ci-robot]

@aguidirh: This pull request references Jira Issue OCPBUGS-53455, which is invalid:

• expected the bug to be open, but it isn't
• expected the bug to target the "4.22.0" version, but no target version was set
• expected the bug to be in one of the following states: NEW, ASSIGNED, POST, but it is Closed (Not a Bug) instead

Comment /jira refresh to re-evaluate validity if changes to the Jira bug are made, or edit the title of this pull request to link to a different bug.

The bug has been updated to refer to the pull request using the external bug tracker.

Details

In response to this:

Description

This PR fixes a critical bug where mirroring operator catalogs to certain registries (like Nexus) fails with the error: Manifest list must be converted to type "application/vnd.docker.distribution.manifest.list.v2+json" to be written to destination, but we cannot modify it: "Instructed to preserve digests"

The root cause was that when oc-mirror rebuilds/filters operator catalogs, it sets PreserveDigests=true for all images. However, rebuilt catalogs have already been modified (filtered), so their digests differ from the original. When copying these rebuilt catalogs to registries that require Docker v2 manifest format conversion, the conversion is blocked by the PreserveDigests flag, causing the mirror operation to fail.

Solution: Set PreserveDigests=false for rebuilt operator catalogs, allowing necessary manifest format conversions while maintaining digest preservation for unmodified images (bundles, related images, etc.).

Github / Jira issue: OCPBUGS-53455

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Code Improvements (Refactoring, Performance, CI upgrades, etc)
• Internal repo assets (diagrams / docs on github repo)
• This change requires a documentation update on openshift docs

How Has This Been Tested?

Test Configuration:

• Nexus OSS 3.37.3 running in a container with Docker registry on port 8082
• ImageSet configuration targeting registry.redhat.io/redhat/redhat-operator-index:v4.17
• oc-mirror v2 mirroring to Nexus registry

Test Steps:

1. Set up Nexus with a Docker hosted repository
2. Create an ImageSetConfiguration with operator catalogs requiring filtering
3. Run: ./bin/oc-mirror -c <config>.yaml --workspace file://<path> docker://127.0.0.1:8082 --dest-tls-verify=false --v2
4. Verify all operator images (including the rebuilt catalog) mirror successfully

Expected Outcome

Before the fix:

• Mirroring fails with error: Manifest list must be converted to type "application/vnd.docker.distribution.manifest.list.v2+json" to be written to destination, but we cannot modify it: "Instructed to preserve digests"
• Operator catalog image fails to copy to the destination registry
• Related operator bundles are skipped due to catalog failure

After the fix:

• ✅ All 74 operator images (including the rebuilt catalog) mirror successfully
• ✅ Catalog successfully copies from cache to destination registry (Nexus)
• ✅ No manifest conversion errors
• ✅ Digest preservation still works for non-rebuilt images (bundles, related images)

Logs showing success:

2026/01/09 19:16:01 [INFO] : Success copying docker://registry.redhat.io/redhat/redhat-operator-index:v4.17 ➡️ 127.0.0.1:8082/redhat/
2026/01/09 19:16:03 [INFO] : Success copying docker://registry.redhat.io/redhat/redhat-operator-index:v4.17 ➡️ cache
2026/01/09 19:16:03 [INFO] : === Results ===

Additional Notes

This fix specifically targets rebuilt/filtered operator catalogs (identified by img.Type.IsOperatorCatalog() && img.RebuiltTag != ""). The change:

• Does NOT affect digest preservation for operator bundles and related images
• Only applies when a catalog has been rebuilt/filtered by oc-mirror
• Allows manifest format conversion when required by the destination registry
• Is safe because rebuilt catalogs already have different digests than the original

This resolves the issue for registries like Nexus that require Docker v2 manifest format but was previously blocked by the digest preservation constraint.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[openshift-ci]

@aguidirh: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[openshift-ci-robot]

@aguidirh: This pull request references Jira Issue OCPBUGS-73760, which is invalid:

• expected the bug to target either version "4.22." or "openshift-4.22.", but it targets "4.21.0" instead

Comment /jira refresh to re-evaluate validity if changes to the Jira bug are made, or edit the title of this pull request to link to a different bug.

The bug has been updated to refer to the pull request using the external bug tracker.

Details

In response to this:

Description

This PR fixes a critical bug where mirroring operator catalogs to certain registries (like Nexus) fails with the error: Manifest list must be converted to type "application/vnd.docker.distribution.manifest.list.v2+json" to be written to destination, but we cannot modify it: "Instructed to preserve digests"

The root cause was that when oc-mirror rebuilds/filters operator catalogs, it sets PreserveDigests=true for all images. However, rebuilt catalogs have already been modified (filtered), so their digests differ from the original. When copying these rebuilt catalogs to registries that require Docker v2 manifest format conversion, the conversion is blocked by the PreserveDigests flag, causing the mirror operation to fail.

Solution: Set PreserveDigests=false for rebuilt operator catalogs, allowing necessary manifest format conversions while maintaining digest preservation for unmodified images (bundles, related images, etc.).

Github / Jira issue: OCPBUGS-53455

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Code Improvements (Refactoring, Performance, CI upgrades, etc)
• Internal repo assets (diagrams / docs on github repo)
• This change requires a documentation update on openshift docs

How Has This Been Tested?

Test Configuration:

• Nexus OSS 3.37.3 running in a container with Docker registry on port 8082
• ImageSet configuration targeting registry.redhat.io/redhat/redhat-operator-index:v4.17
• oc-mirror v2 mirroring to Nexus registry

Test Steps:

1. Set up Nexus with a Docker hosted repository
2. Create an ImageSetConfiguration with operator catalogs requiring filtering
3. Run: ./bin/oc-mirror -c <config>.yaml --workspace file://<path> docker://127.0.0.1:8082 --dest-tls-verify=false --v2
4. Verify all operator images (including the rebuilt catalog) mirror successfully

Expected Outcome

Before the fix:

• Mirroring fails with error: Manifest list must be converted to type "application/vnd.docker.distribution.manifest.list.v2+json" to be written to destination, but we cannot modify it: "Instructed to preserve digests"
• Operator catalog image fails to copy to the destination registry
• Related operator bundles are skipped due to catalog failure

After the fix:

• ✅ All 74 operator images (including the rebuilt catalog) mirror successfully
• ✅ Catalog successfully copies from cache to destination registry (Nexus)
• ✅ No manifest conversion errors
• ✅ Digest preservation still works for non-rebuilt images (bundles, related images)

Logs showing success:

2026/01/09 19:16:01 [INFO] : Success copying docker://registry.redhat.io/redhat/redhat-operator-index:v4.17 ➡️ 127.0.0.1:8082/redhat/
2026/01/09 19:16:03 [INFO] : Success copying docker://registry.redhat.io/redhat/redhat-operator-index:v4.17 ➡️ cache
2026/01/09 19:16:03 [INFO] : === Results ===

Additional Notes

This fix specifically targets rebuilt/filtered operator catalogs (identified by img.Type.IsOperatorCatalog() && img.RebuiltTag != ""). The change:

• Does NOT affect digest preservation for operator bundles and related images
• Only applies when a catalog has been rebuilt/filtered by oc-mirror
• Allows manifest format conversion when required by the destination registry
• Is safe because rebuilt catalogs already have different digests than the original

This resolves the issue for registries like Nexus that require Docker v2 manifest format but was previously blocked by the digest preservation constraint.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[aguidirh]

/jira refresh

[openshift-ci-robot]

@aguidirh: This pull request references Jira Issue OCPBUGS-73760, which is valid. The bug has been moved to the POST state.

3 validation(s) were run on this bug

• bug is open, matching expected state (open)
• bug target version (4.22.0) matches configured target version for branch (4.22.0)
• bug is in the state ASSIGNED, which is one of the valid states (NEW, ASSIGNED, POST)

Requesting review from QA contact:
/cc @nidangavali

Details

In response to this:

/jira refresh

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: adolfo-ab, aguidirh

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [aguidirh]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment