NO-ISSUE: Synchronize From Upstream Repositories

Makefile

@@ -149,6 +149,10 @@ custom-linter-build: #EXHELP Build custom linter
 lint-custom: custom-linter-build #EXHELP Call custom linter for the project
 	go vet -tags=$(GO_BUILD_TAGS) -vettool=./bin/custom-linter ./...
 
+.PHONY: lint-api-diff
+lint-api-diff: $(GOLANGCI_LINT) #HELP Validate API changes using kube-api-linter with diff-aware analysis
+	hack/api-lint-diff/run.sh
+
 .PHONY: k8s-pin
 k8s-pin: #EXHELP Pin k8s staging modules based on k8s.io/kubernetes version (in go.mod or from K8S_IO_K8S_VERSION env var) and run go mod tidy.
 	K8S_IO_K8S_VERSION='$(K8S_IO_K8S_VERSION)' go run hack/tools/k8smaintainer/main.go

cmd/operator-controller/main.go

@@ -42,10 +42,7 @@ import (
 	_ "k8s.io/client-go/plugin/pkg/client/auth"
 	"k8s.io/klog/v2"
 	"k8s.io/utils/ptr"
-	"pkg.package-operator.run/boxcutter/machinery"
 	"pkg.package-operator.run/boxcutter/managedcache"
-	"pkg.package-operator.run/boxcutter/ownerhandling"
-	"pkg.package-operator.run/boxcutter/validation"
 	ctrl "sigs.k8s.io/controller-runtime"
 	crcache "sigs.k8s.io/controller-runtime/pkg/cache"
 	"sigs.k8s.io/controller-runtime/pkg/certwatcher"
@@ -628,7 +625,7 @@ func (c *boxcutterReconcilerConfigurator) Configure(ceReconciler *controllers.Cl
 		controllers.RetrieveRevisionStates(revisionStatesGetter),
 		controllers.ResolveBundle(c.resolver),
 		controllers.UnpackBundle(c.imagePuller, c.imageCache),
-		controllers.ApplyBundleWithBoxcutter(appl),
+		controllers.ApplyBundleWithBoxcutter(appl.Apply),
 	}
 
 	baseDiscoveryClient, err := discovery.NewDiscoveryClientForConfig(c.mgr.GetConfig())
@@ -653,21 +650,29 @@ func (c *boxcutterReconcilerConfigurator) Configure(ceReconciler *controllers.Cl
 		return fmt.Errorf("unable to add tracking cache to manager: %v", err)
 	}
 
+	cerCoreClient, err := corev1client.NewForConfig(c.mgr.GetConfig())
+	if err != nil {
+		return fmt.Errorf("unable to create client for ClusterExtensionRevision controller: %w", err)
+	}
+	cerTokenGetter := authentication.NewTokenGetter(cerCoreClient, authentication.WithExpirationDuration(1*time.Hour))
+
+	revisionEngineFactory, err := controllers.NewDefaultRevisionEngineFactory(
+		c.mgr.GetScheme(),
+		trackingCache,
+		discoveryClient,
+		c.mgr.GetRESTMapper(),
+		fieldOwnerPrefix,
+		c.mgr.GetConfig(),
+		cerTokenGetter,
+	)
+	if err != nil {
+		return fmt.Errorf("unable to create revision engine factory: %w", err)
+	}
+
 	if err = (&controllers.ClusterExtensionRevisionReconciler{
-		Client: c.mgr.GetClient(),
-		RevisionEngine: machinery.NewRevisionEngine(
-			machinery.NewPhaseEngine(
-				machinery.NewObjectEngine(
-					c.mgr.GetScheme(), trackingCache, c.mgr.GetClient(),
-					ownerhandling.NewNative(c.mgr.GetScheme()),
-					machinery.NewComparator(ownerhandling.NewNative(c.mgr.GetScheme()), discoveryClient, c.mgr.GetScheme(), fieldOwnerPrefix),
-					fieldOwnerPrefix, fieldOwnerPrefix,
-				),
-				validation.NewClusterPhaseValidator(c.mgr.GetRESTMapper(), c.mgr.GetClient()),
-			),
-			validation.NewRevisionValidator(), c.mgr.GetClient(),
-		),
-		TrackingCache: trackingCache,
+		Client:                c.mgr.GetClient(),
+		RevisionEngineFactory: revisionEngineFactory,
+		TrackingCache:         trackingCache,
 	}).SetupWithManager(c.mgr); err != nil {
 		return fmt.Errorf("unable to setup ClusterExtensionRevision controller: %w", err)
 	}

commitchecker.yaml

@@ -1,4 +1,4 @@
-expectedMergeBase: 9d8fda0a1cad37c5e04eea413650e39cfeb67cd6
+expectedMergeBase: b08a054acc3892fb5b1977299c8a92cbddd90819
 upstreamBranch: main
 upstreamOrg: operator-framework
 upstreamRepo: operator-controller

docs/draft/howto/configure-bundles.md

@@ -0,0 +1,172 @@
+## Description
+
+!!! note
+This feature is still in `alpha` and the `SingleOwnNamespaceInstallSupport` feature-gate must be enabled to make use of it.
+See the instructions below on how to enable it.
+
+---
+
+# Configuring OLM v1 Extensions: Migration and Reference
+
+In OLM v1, the way extensions are configured has changed significantly to improve flexibility and consistency. This guide explains the architectural shift from OLM v0, how to inspect bundles for supported configurations, and how to correctly configure `registry+v1` (legacy) bundles using the new `ClusterExtension` API.
+
+## OLM v0 vs. OLM v1: The Configuration Shift
+
+In **OLM v0**, configuration was split across multiple resources and concepts. "Install Modes" (defining which namespaces an Operator watches) were handled by the `OperatorGroup` resource, while operand configuration (environment variables, resource limits) was handled via the `Subscription` resource.
+
+In **OLM v1**, these concepts are unified under the **ClusterExtension** resource.
+
+| Feature             | OLM v0 Approach                                                                                           | OLM v1 Approach                                                                                                                    |
+|:--------------------|:----------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------|
+| **Namespace Scope** | Defined by **OperatorGroup**. You had to pre-create an OperatorGroup to tell the Operator where to watch. | Defined by **Configuration**. You provide a `watchNamespace` value directly in the `ClusterExtension` YAML.                        |
+| **User Settings**   | `Subscription.spec.config` (e.g., env, resources).                                                        | `ClusterExtension.spec.config.inline` (arbitrary JSON/YAML defined by the bundle author).                                          |
+| **Multi-Tenancy**   | "Install Modes" allowed multiple instances of an operator to exist.                                       | "Install Modes" are treated as **bundle configuration**. You install the extension once, and configure it to watch specific areas. |
+
+### The `watchNamespace` Configuration
+
+For existing `registry+v1` bundles (standard OLM bundles), OLM v1 automatically generates a configuration schema based on the bundle's capabilities. The primary configuration field available is `watchNamespace`.
+
+* **OLM v0:** You selected `SingleNamespace` mode by creating an `OperatorGroup` that targeted a specific namespace.
+* **OLM v1:** You set `watchNamespace: "my-target-namespace"` inside the `ClusterExtension` config.
+
+## Step 1: Identifying Bundle Capabilities
+
+Before configuring a bundle, you must understand which Install Modes it supports. OLM v1 does not allow you to force a configuration that the bundle author has not explicitly supported.
+
+You can inspect a bundle image using the `opm` CLI tool and `jq` to parse the output.
+
+**Prerequisites:**
+* `opm` CLI installed.
+* `jq` installed.
+
+**Command:**
+
+Run the following command, replacing `<bundle-image>` with your target image (e.g., `quay.io/example/my-operator-bundle:v1.0.0`).
+
+```bash
+opm render <bundle-image> -o json | \
+jq 'select(.schema == "olm.bundle") | .properties[] | select(.type == "olm.csv") | .value.spec.installModes'
+```
+
+**Example Output:**
+
+```json
+[
+  {
+    "type": "OwnNamespace",
+    "supported": true
+  },
+  {
+    "type": "SingleNamespace",
+    "supported": true
+  },
+  {
+    "type": "MultiNamespace",
+    "supported": false
+  },
+  {
+    "type": "AllNamespaces",
+    "supported": false
+  }
+]
+```
+
+By analyzing which modes are marked `true`, you can determine how to configure the `ClusterExtension` in the next step.
+
+## Step 2: Capability Matrix & Configuration Guide
+
+Use the output from Step 1 to locate your bundle's capabilities in the matrix below. This determines if you *must* provide configuration, if it is optional, and what values are valid.
+
+### Legend
+* **Install Namespace:** The namespace where the Operator logic (Pod) runs (defined in `ClusterExtension.spec.namespace`).
+* **Watch Namespace:** The namespace the Operator monitors for Custom Resources (defined in `spec.config.inline.watchNamespace`).
+
+### Configuration Matrix
+
+| Capabilities Detected (from `opm`)       | `watchNamespace` Field Status | Valid Values / Constraints                                                                                |
+|:-----------------------------------------|:------------------------------|:----------------------------------------------------------------------------------------------------------|
+| **OwnNamespace ONLY**                    | **Required**                  | Must be exactly the same as the **Install Namespace**.                                                    |
+| **SingleNamespace ONLY**                 | **Required**                  | Must be **different** from the Install Namespace.                                                         |
+| **OwnNamespace** AND **SingleNamespace** | **Required**                  | Can be **any** namespace (either the install namespace or a different one).                               |
+| **AllNamespaces** (regardless of others) | **Optional**                  | If omitted: defaults to Cluster-wide watch.<br>If provided: can be any specific namespace (limits scope). |
+
+### Common Configuration Scenarios
+
+#### Scenario A: The Legacy "OwnNamespace" Operator
+* **Capability:** Only supports `OwnNamespace`.
+* **Requirement:** The operator is hardcoded to watch its own namespace.
+* **Config:** You must explicitly set `watchNamespace` to match the installation namespace.
+
+```yaml
+apiVersion: olm.operatorframework.io/v1
+kind: ClusterExtension
+metadata:
+  name: my-operator
+spec:
+  namespace: my-operator-ns      # <--- Install Namespace
+  serviceAccount:
+    name: my-sa
+  config:
+    configType: Inline
+    inline:
+      watchNamespace: my-operator-ns # <--- MUST match Install Namespace
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: my-package
+```
+
+#### Scenario B: The "SingleNamespace" Operator
+* **Capability:** Supports `SingleNamespace` (but not `OwnNamespace`).
+* **Requirement:** The operator runs in one namespace (e.g., `ops-system`) but watches workloads in another (e.g., `dev-team-a`).
+* **Config:** You must set `watchNamespace` to the target workload namespace.
+
+```yaml
+apiVersion: olm.operatorframework.io/v1
+kind: ClusterExtension
+metadata:
+  name: monitor-operator
+spec:
+  namespace: ops-system          # <--- Install Namespace
+  serviceAccount:
+    name: monitor-operator-installer
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: monitor-operator
+  config:
+    configType: Inline
+    inline:
+      watchNamespace: dev-team-a     # <--- MUST differ from Install Namespace
+```
+
+#### Scenario C: The Modern "AllNamespaces" Operator
+* **Capability:** Only supports `AllNamespaces`.
+
+```yaml
+apiVersion: olm.operatorframework.io/v1
+kind: ClusterExtension
+metadata:
+  name: global-operator
+spec:
+  namespace: operators
+  # No config provided = Operator watches the entire cluster (AllNamespaces)
+  serviceAccount:
+    name: global-operator-installer
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: global-operator
+```
+
+
+## Troubleshooting Configuration Errors
+
+OLM v1 validates your configuration against the bundle's schema before installation proceeds. If your configuration is invalid, the `ClusterExtension` will report a `Progressing` condition with an error message.
+
+| Error Message Example                                                                                                                                                         | Cause                                                                                              | Solution                                                                                                        |
+|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------|
+| `required field "watchNamespace" is missing`                                                                                                                                  | The bundle does not support `AllNamespaces` default mode.                                          | Add the `inline` block and specify a `watchNamespace`.                                                          |
+| `invalid value "X": watchNamespace must be "Y" (the namespace where the operator is installed) because this operator only supports OwnNamespace install mode`                 | You tried to set a different watch namespace for an `OwnNamespace`-only bundle.                    | Change `watchNamespace` to match `spec.namespace`.                                                              |
+| `invalid value "X": watchNamespace must be different from "Y" (the install namespace) because this operator uses SingleNamespace install mode to watch a different namespace` | You tried to set the watch namespace to the install namespace for a `SingleNamespace`-only bundle. | Change `watchNamespace` to a different target namespace.                                                        |
+| `unknown field "foo"`                                                                                                                                                         | You added extra fields to the inline config.                                                       | Remove fields other than `watchNamespace` (unless the bundle author explicitly documents extra schema support). |

go.mod

@@ -24,7 +24,7 @@ require (
 	github.com/operator-framework/helm-operator-plugins v0.8.0
 	github.com/operator-framework/operator-registry v1.61.0
 	github.com/prometheus/client_golang v1.23.2
-	github.com/prometheus/common v0.67.4
+	github.com/prometheus/common v0.67.5
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/pflag v1.0.10
@@ -127,11 +127,13 @@ require (
 	github.com/go-openapi/swag/stringutils v0.25.4 // indirect
 	github.com/go-openapi/swag/typeutils v0.25.4 // indirect
 	github.com/go-openapi/swag/yamlutils v0.25.4 // indirect
+	github.com/go-sql-driver/mysql v1.9.2 // indirect
 	github.com/gobuffalo/flect v1.0.3 // indirect
 	github.com/gobwas/glob v0.2.3 // indirect
 	github.com/gofrs/uuid v4.3.1+incompatible // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 // indirect
+	github.com/golang/mock v1.7.0-rc.1 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/google/btree v1.1.3 // indirect
 	github.com/google/cel-go v0.26.1 // indirect
@@ -142,7 +144,7 @@ require (
 	github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 // indirect
 	github.com/gosuri/uitable v0.0.4 // indirect
 	github.com/gregjones/httpcache v0.0.0-20190611155906-901d90724c79 // indirect
-	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.1 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.4 // indirect
 	github.com/h2non/filetype v1.1.3 // indirect
 	github.com/h2non/go-is-svg v0.0.0-20160927212452-35e8c4b0612c // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
@@ -159,10 +161,9 @@ require (
 	github.com/klauspost/pgzip v1.2.6 // indirect
 	github.com/lann/builder v0.0.0-20180802200727-47ae307949d0 // indirect
 	github.com/lann/ps v0.0.0-20150810152359-62de8c46ede0 // indirect
-	github.com/letsencrypt/boulder v0.0.0-20250624003606-5ddd5acf990d // indirect
 	github.com/lib/pq v1.10.9 // indirect
 	github.com/liggitt/tabwriter v0.0.0-20181228230101-89fcab3d43de // indirect
-	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-runewidth v0.0.16 // indirect
 	github.com/mattn/go-sqlite3 v1.14.32 // indirect
@@ -184,6 +185,7 @@ require (
 	github.com/monochromegane/go-gitignore v0.0.0-20200626010858-205db1a8cc00 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/mxk/go-flowrate v0.0.0-20140419014527-cca7078d478f // indirect
+	github.com/nxadm/tail v1.4.11 // indirect
 	github.com/onsi/gomega v1.38.3 // indirect
 	github.com/opencontainers/runtime-spec v1.2.1 // indirect
 	github.com/operator-framework/operator-lib v0.17.0 // indirect
@@ -200,49 +202,48 @@ require (
 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/secure-systems-lab/go-securesystemslib v0.9.1 // indirect
 	github.com/shopspring/decimal v1.4.0 // indirect
-	github.com/sigstore/fulcio v1.7.1 // indirect
-	github.com/sigstore/protobuf-specs v0.4.3 // indirect
-	github.com/sigstore/sigstore v1.9.5 // indirect
+	github.com/sigstore/fulcio v1.8.5 // indirect
+	github.com/sigstore/protobuf-specs v0.5.0 // indirect
+	github.com/sigstore/sigstore v1.10.3 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
 	github.com/smallstep/pkcs7 v0.2.1 // indirect
 	github.com/spf13/cast v1.7.1 // indirect
 	github.com/stefanberger/go-pkcs11uri v0.0.0-20230803200340-78284954bff6 // indirect
 	github.com/stoewer/go-strcase v1.3.1 // indirect
 	github.com/stretchr/objx v0.5.3 // indirect
-	github.com/titanous/rocacheck v0.0.0-20171023193734-afe73141d399 // indirect
 	github.com/ulikunitz/xz v0.5.15 // indirect
 	github.com/vbatts/tar-split v0.12.2 // indirect
 	github.com/vbauerster/mpb/v8 v8.10.2 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
 	github.com/xlab/treeprint v1.2.0 // indirect
 	go.etcd.io/bbolt v1.4.3 // indirect
 	go.opencensus.io v0.24.0 // indirect
-	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.63.0 // indirect
 	go.opentelemetry.io/otel v1.38.0 // indirect
-	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.37.0 // indirect
-	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.37.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.38.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.38.0 // indirect
 	go.opentelemetry.io/otel/metric v1.38.0 // indirect
-	go.opentelemetry.io/otel/sdk v1.37.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.38.0 // indirect
 	go.opentelemetry.io/otel/trace v1.38.0 // indirect
-	go.opentelemetry.io/proto/otlp v1.7.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.7.1 // indirect
 	go.podman.io/common v0.66.0 // indirect
 	go.podman.io/storage v1.61.0 // indirect
 	go.yaml.in/yaml/v2 v2.4.3 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/crypto v0.46.0 // indirect
 	golang.org/x/net v0.48.0 // indirect
-	golang.org/x/oauth2 v0.33.0 // indirect
+	golang.org/x/oauth2 v0.34.0 // indirect
 	golang.org/x/sys v0.39.0 // indirect
 	golang.org/x/term v0.38.0 // indirect
 	golang.org/x/text v0.32.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	gomodules.xyz/jsonpatch/v2 v2.5.0 // indirect
-	google.golang.org/genproto v0.0.0-20250603155806-513f23925822 // indirect
-	google.golang.org/genproto/googleapis/api v0.0.0-20250804133106-a7a43d27e69b // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20251110190251-83f479183930 // indirect
-	google.golang.org/grpc v1.76.0 // indirect
-	google.golang.org/protobuf v1.36.10 // indirect
+	google.golang.org/genproto v0.0.0-20251202230838-ff82c1b0f217 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20251222181119-0a764e51fe1b // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20251222181119-0a764e51fe1b // indirect
+	google.golang.org/grpc v1.78.0 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect