Epic Goal

• Simplify the structure and maintenance of metadata about related images of an Operator
• Remove ambiguity / duplication commonly found in the current structure of related images metadata in the CSV
• Remove any contradiction between downstream OCP documentation and internal Red Hat Operator pipeline (which supports automatic digest replacement in pull specs)

Why is this important?

• Currently Operator authors are asked to maintain related images information in spec.relatedImages in the Operator metadata (CSV) but commonly users also use environment variables in their Operator Deployment manifests to pass in image references - this is creates data duplication
• the Red Hat internal Operator pipelines mandate that Operator reference their related images via environment variables in order to use automatic SHA replacement offered by OSBS
• the spec.relatedImages list is lacking context of what certain images are required for, whereas environment variables have a specific naming pattern that gives context which component of the Operator/Operand requires this images, providing better UX

Scenarios

1. Operator authors can solely rely on environment variables in their Deployment manifests of their Operator to denote related images
2. Environment variables denoting related images are supposed to follow a certain naming conventions to be parsed
3. related images references can be tag based and there will be a a library to do the parsing and rendering of replaced bundle manifests with SHAs
4. Operator SDK should be able to use aforementioned tooling to by default produce bundles that only contain digest based references
5. Migration: existing tooling (opm) will recognize an env vars with related images and merge theme with existing images listed in spec.relatedImages and remove any duplicates in the process), thus the change is transparent for the catalog structure
6. at a later stage, when bundles do not contain a CSV anymore, the implementation still respects env vars with a certain naming pattern in Kubernetes manifests
7. Pipeline Migration: The internal Red Hat Operator pipeline should not need to change change to adopt this format and in most cases end up not needing to do any digest pinning (since the input is already digest based)

Acceptance Criteria

• CI - MUST be running successfully with tests automated
• Release Technical Enablement - Provide necessary release enablement details and documents.
• The implementation needs to allow the use of spec.relatedImages in parallel with the environment variable based implementation, in doubt the env vars take precedence

Previous Work (Optional):

1. OSBS Digest Pinning: https://osbs.readthedocs.io/en/latest/users.html?#pinning-pullspecs-for-related-images
2. CFC Digest Pinning Guidance: https://docs.engineering.redhat.com/display/CFC/Digest_Pinning

Open questions::

1. Should there only be a library in OF to encapsulate digest pinning logic or do we want to a standalone tool like Carvel's kbld (https://carvel.dev/kbld/) available for maximum flexibility for customers and upstream users?
2. Edge case: Inadvertent mirroring of images from accidentally named environment variables in unrelated manifest (helm)

Done Checklist

• CI - CI is running, tests are automated and merged.
• Release Enablement <link to Feature Enablement Presentation>
• DEV - Upstream code and tests merged: <link to meaningful PR or GitHub Issue>
• DEV - Upstream documentation merged: <link to meaningful PR or GitHub Issue>
• DEV - Downstream build attached to advisory: <link to errata>
• QE - Test plans in Polarion: <link or reference to Polarion>
• QE - Automated tests merged: <link or reference to automated tests>
• DOC - Downstream documentation merged: <link to meaningful PR>