Feature Overview (aka. Goal Summary)  

Enable users of the OLM v1 to proactively discover available update versions for their installed operators/cluster extensions and to preview the changes that will be applied before initiating an upgrade. 

This discovery process respects the vendor-supplied update paths and update channels, providing accurate and channel-aware update recommendations via the top-level API ClusterExtension object, without requiring users to directly browse a catalog. 

Goals (aka. expected user outcomes)

The primary goal is to provide transparency over the operator upgrade process, mitigating risks associated with unexpected changes and allowing users to make informed decisions about updating their installed packages managed by the OLM v1. 

This will empower users to:

• Identify available updates respecting the update path: Users can quickly determine if newer versions of their installed cluster extensions are available, with recommendations driven by the vendor-defined update channels and paths.
• Understand potential changes: Users can pre/review a summary of the changes included in an available update, including API changes, new description, and deprecation info (if any) without making any modifications to the currently installed extension in the cluster.
• Mitigate upgrade risks: By previewing changes, users can identify potential breaking changes or conflicts before applying an update, allowing them to plan and prepare accordingly.
• Make informed upgrade decisions: Users will have sufficient information to decide whether to proceed with an upgrade, defer it, or investigate further, including understanding if a channel switch is required (e.g., based on the deprecation info).
• Increase confidence in OLM upgrades: The transparency provided by this feature will build user trust in the OLM v1 upgrade process, across both the OpenShift Console (when supported) and CLI.
• Reduce operational overhead: By understanding changes upfront, admins can reduce time spent troubleshooting post-upgrade issues.

Background

The current OLM v1 allows for automatic or manual upgrades, but it lacks clear visibility into what changes are included in an available upgrade.  Users will need to rely on external documentation or trial-and-error to understand the impact of an upgrade, leading to potential issues and downtime.  Furthermore, understanding which update paths and channels are available and how to navigate them can be unclear.

This feature will address a critical user need for transparency and control.  By providing mechanisms to discover updates that respect vendor-defined channels/update paths, and to non-destructively preview changes, OLM can become a more reliable and user-friendly platform for managing the lifecycle of operators/cluster extensions on OpenShift.  This feature directly contributes to a smoother and more predictable operator upgrade experience, whether users are interacting via the OpenShift Console (when supported) or the CLI.

• Previous upstream engineering brief: https://docs.google.com/document/d/1BED6MBhBthFrXxb0QEc10dYVBg9n8gubVGD3Bwg3w4Y/edit?usp=sharing

Requirements (aka. Acceptance Criteria):

Discover available update versions

• Provide a mechanism for users to query an installed package managed by a ClusterExtension object for the available update versions, whether in the OpenShift console (when supported in the future) or via CLI command.
• For each installed operator, provide a mechanism to display the highest available recommended update version driven by the vendor-defined update channels and update paths, if one exists.
• For each installed Operator, provide a mechanism to (optionally) display all available update versions across all channels defined by the vendor's update graph, clearly indicating the channel for each version.
• Provide a mechanism to indicate if an installed operator is already on the latest available version within its current channel.
• For any recommended update version, provide a mechanism to indicate the channel it belongs to. 
• The mechanism guides how to switch to a different channel if a desired update version is only available in another channel.

Preview changes for an installed package version

• Provide a mechanism (e.g., CLI command, OpenShift Console UI element) for a user to preview the changes between their currently installed Operator version and a specified target update version, without making any changes to the currently installed extension in the cluster.
• Present a human-readable summary of changes, categorized by type, e.g., API/CRD changes, Kubernetes resource objects, deprecation info (when available).
• Include information about any CustomResourceDefinitions (CRDs) changes (e.g., new CRDs, modified CRD schemas, removed CRDs).
• Include information about new or updated ClusterServiceVersion (CSV) and the associated metadata.
• Indicate/differentiate between major, minor, and patch version changes in the preview.
• Handle cases where no changes are detected between versions (e.g., indicating "No changes found").

Use Cases (Optional):

Scenario 1: Installing and Discovering Updates for a Specific Operator

As a cluster admin, I want to manage my cluster extensions effectively, so I can keep them up-to-date while maintaining control over the update process.

1. I initially installed the 'rhacs-operator' version '4.1.2' from the 'stable' channel, explicitly configuring OLM v1 to not perform automatic updates.  This ensures I control when and how the operator is updated.
2. Over time, new versions of 'rhacs-operator' are released by the vendor.  In the 'stable' channel, versions '4.1.2' and '4.1.3' become available.  Additionally, new channels like 'rhacs-4.2' and 'rhacs-4.3' emerge, offering versions '4.2.0' and '4.3.2' respectively, reflecting the vendor's defined update graph.
3. When I later inquire about available updates for my installed 'rhacs-operator', OLM v1 quickly provides me with the relevant information.
4. OLM v1 indicates that version '4.1.3' is the recommended update within my current 'stable' channel.  This recommendation is driven by the vendor's defined update path for that channel, ensuring I see the logical next step for my current installation.
5. If I need to explore further, I can also optionally view all available update versions across all defined channels, such as '4.2.0' in 'rhacs-4.2', and '4.3.2' in 'rhacs-4.3'.  This gives me a comprehensive overview of all potential upgrade paths.

Scenario 2: Previewing Changes Before an Upgrade

As a cluster admin, before applying any update to my cluster extensions, I need to understand the exact changes included in the new version, so I can prepare for potential impacts and avoid unexpected issues.

1. After discovering that version '4.1.3' of the 'rhacs-operator' is available, I request OLM v1 to preview the changes for this specific version.  This is a non-destructive operation; it doesn't modify my current installation.
2. OLM v1 presents me with a human-readable summary of the changes.  This summary categorizes the updates, highlighting important aspects like API/CRD changes, Kubernetes resource object updates, and any deprecation info.
3. Specifically, I can pre/review any CRD changes, such as newly introduced CRDs, modifications to existing CRD schemas, or removed CRDs.  This detailed view helps me understand if my existing configurations or applications might be affected.
4. Once I've reviewed the changes and am confident in the update's impact, I can then instruct OLM to update the 'rhacs-operator' to version '4.1.3' when I am ready.

Documentation Considerations

• Detailed instructions on how to use the CLI commands for discovering available updates and previewing changes. 
• Provide concrete examples of how to use the feature with an operator as an example to show the change previews.
• Explanations of the different types of information presented in the change preview  (e.g., API changes, Kubernetes resource objects, deprecation info, when available).
• Guidance on understanding update channels and when/how to switch channels.
• Best practices for interpreting change previews and making informed upgrade decisions.
• Troubleshooting common issues related to update discovery and preview.
• (API Reference) Documentation of any new or modified OLM APIs related to update discovery and change preview.

Interoperability Considerations

Which other projects, including ROSA/OSD/ARO, and versions in our portfolio does this feature impact?  What interoperability test scenarios should be factored by the layered products?  Initial completion during Refinement status.

<your text here>