(fix): report Unknown for deprecation status when catalog unavailable and prevent error leak

When a catalog is removed or unreachable, deprecation conditions now
correctly show Unknown instead of False. BundleDeprecated now reflects
the installed bundle and uses the correct reason.

Key changes:
- Defer deprecation status updates until end of reconciliation
- Track hadCatalogDeprecationData to distinguish catalog absence from "not deprecated"
- Report installed bundle deprecation, not the bundle being installed
- BundleDeprecated uses Deprecated reason when bundle exists, Absent only when none
- Prevent install/validation errors from leaking into deprecation conditions

Scenarios fixed:
- No catalog + no bundle → BundleDeprecated: Unknown/Absent
- No catalog + bundle installed → BundleDeprecated: Unknown/Deprecated (was False/Absent)
- During upgrade v1→v2 → shows v1 status, not v2
- Resolution fails with warnings → deprecation warnings still reach users

Assisted-by: Cursor

Author: camilamacedo86

PR_DESCRIPTION.md

@@ -0,0 +1,98 @@
+# Fix deprecation conditions when catalog is unavailable
+
+Fixes #2008
+
+## Description
+
+This PR fixes how deprecation conditions are reported when the catalog is unavailable or resolution fails:
+
+- **Show Unknown when catalog is unavailable**: When a catalog is removed or unreachable, deprecation conditions now correctly show `Unknown` instead of `False`, so users know "we don't know if it's deprecated" rather than "definitely not deprecated"
+
+- **Report installed bundle deprecation, not resolved**: BundleDeprecated now reflects the currently installed bundle's status, not the bundle being installed during an upgrade
+
+- **Keep deprecation data separate from errors**: Install and validation errors stay in Progressing/Installed conditions, never leak into deprecation conditions
+
+- **Handle catalog deprecation data on failures**: When resolution fails but the catalog still returns deprecation warnings, those warnings now reach users
+
+## TL;DR
+
+`SetDeprecationStatus` now properly handles three scenarios:
+
+**1. No catalog data (catalog removed or unreachable)**
+- All deprecation conditions → `Unknown`
+- BundleDeprecated reason → `Absent` only when no bundle installed, `Deprecated` when bundle exists
+
+**2. Catalog available with deprecation warnings**
+- PackageDeprecated → `True` if catalog marks package deprecated
+- ChannelDeprecated → `True` if requested channel marked deprecated
+- BundleDeprecated → reflects the **installed** bundle (not the one being installed)
+- Deprecated (rollup) → `True` if any deprecation signal present
+
+**3. Resolution fails but returns deprecation data**
+- Deprecation warnings shown even when installation cannot proceed
+- Progressing condition shows the resolution error
+- Deprecation conditions show catalog warnings separately
+
+## Key Changes
+
+### Controller Logic
+- Added defer to update deprecation status at the end of reconciliation
+- Track `hadCatalogDeprecationData` flag to distinguish "catalog absent" from "catalog says not deprecated"
+- Use installed bundle name from `revisionStates.Installed`, not the resolved bundle
+
+### SetDeprecationStatus Function
+- Simplified from ~90 lines to ~50 lines using helper function
+- Handle `hasCatalogData=false` case to set all conditions Unknown
+- BundleDeprecated uses correct reason based on whether bundle exists
+
+### Tests
+- Added `TestClusterExtensionResolutionFailsWithoutCatalogDeprecationData` - verifies Unknown status when catalog unavailable
+- Enhanced `TestSetDeprecationStatus` with 3 new test cases for catalog absence scenarios
+- Added scenario descriptions to all related tests for clarity
+
+## Examples
+
+### Before (incorrect behavior)
+```yaml
+# Bundle v1.0.0 installed, catalog removed
+Deprecated: False/Deprecated              # ❌ Wrong - should be Unknown
+BundleDeprecated: False/Absent            # ❌ Wrong - bundle exists but shows Absent
+```
+
+### After (correct behavior)
+```yaml
+# Bundle v1.0.0 installed, catalog removed
+Deprecated: Unknown/Deprecated            # ✅ Correct - we don't know
+BundleDeprecated: Unknown/Deprecated      # ✅ Correct - bundle exists, catalog unknown
+```
+
+### During Upgrade (fixed)
+```yaml
+# Upgrading from v1.0.0 to v1.0.1 (v1.0.1 not installed yet)
+BundleDeprecated: shows v1.0.0 status     # ✅ Correct - reflects installed bundle
+```
+
+## Testing
+
+All tests pass:
+- ✅ `TestSetDeprecationStatus` - 11 test cases covering all deprecation scenarios
+- ✅ `TestClusterExtensionResolutionFailsWithoutCatalogDeprecationData` - catalog unavailable
+- ✅ `TestClusterExtensionResolutionFailsWithDeprecationData` - resolution fails with warnings
+- ✅ `TestClusterExtensionBoxcutterApplierFailsDoesNotLeakDeprecationErrors` - errors don't leak
+- ✅ All existing controller tests
+
+## Files Changed
+
+```
+13 files changed, 723 insertions(+), 144 deletions(-)
+```
+
+**Controller:**
+- `clusterextension_controller.go` - defer logic, simplified SetDeprecationStatus
+- `clusterextension_controller_test.go` - new tests and scenario descriptions
+
+**API/Docs:**
+- `clusterextension_types.go` - updated deprecation condition documentation
+- `olmv1-api-reference.md` - updated API docs
+- CRD manifests - regenerated with updated descriptions
+

api/v1/clusterextension_types.go

@@ -483,12 +483,15 @@ type ClusterExtensionStatus struct {
 	// When Progressing is True and the Reason is Retrying, the ClusterExtension has encountered an error that could be resolved on subsequent reconciliation attempts.
 	// When Progressing is False and the Reason is Blocked, the ClusterExtension has encountered an error that requires manual intervention for recovery.
 	//
-	// When the ClusterExtension is sourced from a catalog, if may also communicate a deprecation condition.
+	// When the ClusterExtension is sourced from a catalog, it may surface deprecation conditions based on catalog metadata.
 	// These are indications from a package owner to guide users away from a particular package, channel, or bundle.
-	// BundleDeprecated is set if the requested bundle version is marked deprecated in the catalog.
-	// ChannelDeprecated is set if the requested channel is marked deprecated in the catalog.
-	// PackageDeprecated is set if the requested package is marked deprecated in the catalog.
-	// Deprecated is a rollup condition that is present when any of the deprecated conditions are present.
+	// PackageDeprecated reports the requested package as deprecated when the catalog says so. When no catalog talks
+	// about the package, the condition stays Unknown instead of claiming False.
+	// ChannelDeprecated follows the same rules for each requested channel.
+	// BundleDeprecated describes the installed bundle once one exists. Until a bundle installs, or when no catalog
+	// data is available, it remains Unknown.
+	// Deprecated is still the rollup: it goes True when any individual deprecation condition is True, and Unknown
+	// when we have no catalog information to report.
 	//
 	// +listType=map
 	// +listMapKey=type

docs/api-reference/olmv1-api-reference.md

@@ -359,7 +359,7 @@ _Appears in:_
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | The set of condition types which apply to all spec.source variations are Installed and Progressing.<br />The Installed condition represents whether or not the bundle has been installed for this ClusterExtension.<br />When Installed is True and the Reason is Succeeded, the bundle has been successfully installed.<br />When Installed is False and the Reason is Failed, the bundle has failed to install.<br />The Progressing condition represents whether or not the ClusterExtension is advancing towards a new state.<br />When Progressing is True and the Reason is Succeeded, the ClusterExtension is making progress towards a new state.<br />When Progressing is True and the Reason is Retrying, the ClusterExtension has encountered an error that could be resolved on subsequent reconciliation attempts.<br />When Progressing is False and the Reason is Blocked, the ClusterExtension has encountered an error that requires manual intervention for recovery.<br />When the ClusterExtension is sourced from a catalog, if may also communicate a deprecation condition.<br />These are indications from a package owner to guide users away from a particular package, channel, or bundle.<br />BundleDeprecated is set if the requested bundle version is marked deprecated in the catalog.<br />ChannelDeprecated is set if the requested channel is marked deprecated in the catalog.<br />PackageDeprecated is set if the requested package is marked deprecated in the catalog.<br />Deprecated is a rollup condition that is present when any of the deprecated conditions are present. |  |  |
+| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | The set of condition types which apply to all spec.source variations are Installed and Progressing.<br />The Installed condition represents whether or not the bundle has been installed for this ClusterExtension.<br />When Installed is True and the Reason is Succeeded, the bundle has been successfully installed.<br />When Installed is False and the Reason is Failed, the bundle has failed to install.<br />The Progressing condition represents whether or not the ClusterExtension is advancing towards a new state.<br />When Progressing is True and the Reason is Succeeded, the ClusterExtension is making progress towards a new state.<br />When Progressing is True and the Reason is Retrying, the ClusterExtension has encountered an error that could be resolved on subsequent reconciliation attempts.<br />When Progressing is False and the Reason is Blocked, the ClusterExtension has encountered an error that requires manual intervention for recovery.<br />When the ClusterExtension is sourced from a catalog, it may surface deprecation conditions based on catalog metadata.<br />These are indications from a package owner to guide users away from a particular package, channel, or bundle.<br />PackageDeprecated reports the requested package as deprecated when the catalog says so. When no catalog talks<br />about the package, the condition stays Unknown instead of claiming False.<br />ChannelDeprecated follows the same rules for each requested channel.<br />BundleDeprecated describes the installed bundle once one exists. Until a bundle installs, or when no catalog<br />data is available, it remains Unknown.<br />Deprecated is still the rollup: it goes True when any individual deprecation condition is True, and Unknown<br />when we have no catalog information to report. |  |  |
 | `install` _[ClusterExtensionInstallStatus](#clusterextensioninstallstatus)_ | install is a representation of the current installation status for this ClusterExtension. |  |  |
 
 

helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensions.yaml

@@ -518,12 +518,15 @@ spec:
                   When Progressing is True and the Reason is Retrying, the ClusterExtension has encountered an error that could be resolved on subsequent reconciliation attempts.
                   When Progressing is False and the Reason is Blocked, the ClusterExtension has encountered an error that requires manual intervention for recovery.
 
-                  When the ClusterExtension is sourced from a catalog, if may also communicate a deprecation condition.
+                  When the ClusterExtension is sourced from a catalog, it may surface deprecation conditions based on catalog metadata.
                   These are indications from a package owner to guide users away from a particular package, channel, or bundle.
-                  BundleDeprecated is set if the requested bundle version is marked deprecated in the catalog.
-                  ChannelDeprecated is set if the requested channel is marked deprecated in the catalog.
-                  PackageDeprecated is set if the requested package is marked deprecated in the catalog.
-                  Deprecated is a rollup condition that is present when any of the deprecated conditions are present.
+                  PackageDeprecated reports the requested package as deprecated when the catalog says so. When no catalog talks
+                  about the package, the condition stays Unknown instead of claiming False.
+                  ChannelDeprecated follows the same rules for each requested channel.
+                  BundleDeprecated describes the installed bundle once one exists. Until a bundle installs, or when no catalog
+                  data is available, it remains Unknown.
+                  Deprecated is still the rollup: it goes True when any individual deprecation condition is True, and Unknown
+                  when we have no catalog information to report.
                 items:
                   description: Condition contains details for one aspect of the current
                     state of this API Resource.

helm/olmv1/base/operator-controller/crd/standard/olm.operatorframework.io_clusterextensions.yaml

@@ -479,12 +479,15 @@ spec:
                   When Progressing is True and the Reason is Retrying, the ClusterExtension has encountered an error that could be resolved on subsequent reconciliation attempts.
                   When Progressing is False and the Reason is Blocked, the ClusterExtension has encountered an error that requires manual intervention for recovery.
 
-                  When the ClusterExtension is sourced from a catalog, if may also communicate a deprecation condition.
+                  When the ClusterExtension is sourced from a catalog, it may surface deprecation conditions based on catalog metadata.
                   These are indications from a package owner to guide users away from a particular package, channel, or bundle.
-                  BundleDeprecated is set if the requested bundle version is marked deprecated in the catalog.
-                  ChannelDeprecated is set if the requested channel is marked deprecated in the catalog.
-                  PackageDeprecated is set if the requested package is marked deprecated in the catalog.
-                  Deprecated is a rollup condition that is present when any of the deprecated conditions are present.
+                  PackageDeprecated reports the requested package as deprecated when the catalog says so. When no catalog talks
+                  about the package, the condition stays Unknown instead of claiming False.
+                  ChannelDeprecated follows the same rules for each requested channel.
+                  BundleDeprecated describes the installed bundle once one exists. Until a bundle installs, or when no catalog
+                  data is available, it remains Unknown.
+                  Deprecated is still the rollup: it goes True when any individual deprecation condition is True, and Unknown
+                  when we have no catalog information to report.
                 items:
                   description: Condition contains details for one aspect of the current
                     state of this API Resource.

internal/operator-controller/controllers/clusterextension_admission_test.go

@@ -13,20 +13,20 @@ import (
 )
 
 func TestClusterExtensionSourceConfig(t *testing.T) {
-	sourceTypeEmptyError := "Invalid value: null"
+	sourceTypeEmptyErrors := []string{"Invalid value: \"null\"", "Invalid value: null"}
 	sourceTypeMismatchError := "spec.source.sourceType: Unsupported value"
 	sourceConfigInvalidError := "spec.source: Invalid value"
 	// unionField represents the required Catalog or (future) Bundle field required by SourceConfig
 	testCases := []struct {
 		name       string
 		sourceType string
 		unionField string
-		errMsg     string
+		errMsgs    []string
 	}{
-		{"sourceType is null", "", "Catalog", sourceTypeEmptyError},
-		{"sourceType is invalid", "Invalid", "Catalog", sourceTypeMismatchError},
-		{"catalog field does not exist", "Catalog", "", sourceConfigInvalidError},
-		{"sourceConfig has required fields", "Catalog", "Catalog", ""},
+		{"sourceType is null", "", "Catalog", sourceTypeEmptyErrors},
+		{"sourceType is invalid", "Invalid", "Catalog", []string{sourceTypeMismatchError}},
+		{"catalog field does not exist", "Catalog", "", []string{sourceConfigInvalidError}},
+		{"sourceConfig has required fields", "Catalog", "Catalog", nil},
 	}
 
 	t.Parallel()
@@ -62,12 +62,20 @@ func TestClusterExtensionSourceConfig(t *testing.T) {
 				}))
 			}
 
-			if tc.errMsg == "" {
+			if len(tc.errMsgs) == 0 {
 				require.NoError(t, err, "unexpected error for sourceType %q: %w", tc.sourceType, err)
-			} else {
-				require.Error(t, err)
-				require.Contains(t, err.Error(), tc.errMsg)
+				return
+			}
+
+			require.Error(t, err)
+			matched := false
+			for _, msg := range tc.errMsgs {
+				if strings.Contains(err.Error(), msg) {
+					matched = true
+					break
+				}
 			}
+			require.True(t, matched, "expected one of %v in error %q", tc.errMsgs, err)
 		})
 	}
 }