• OWNERS

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

The change adds direct OCI image sources to ClusterExtension. It updates API types, generated configurations, CRD validation, bundle resolution, feature-gated reconciliation, manifests, documentation, and tests. Bundle source validation also checks package metadata.

Changes: OCI image source support

Layer / File(s)	Summary
OCI source contract and schemas api/v1/..., applyconfigurations/api/v1/..., applyconfigurations/internal/internal.go, applyconfigurations/utils.go, docs/api-reference/..., helm/olmv1/base/operator-controller/crd/..., manifests/*.yaml	SourceConfig supports Catalog and experimental OCIImage. The OCI image reference has schema validation. Generated apply configurations, CRD schemas, manifests, and API documentation describe the new source. Standard schemas remain Catalog-only.
Bundle package-property contract internal/operator-controller/rukpak/bundle/source/..., internal/testing/bundle/fs/bundlefs.go, internal/operator-controller/applier/*_test.go	Bundle sources validate the CSV olm.package property. The bundle filesystem test builder can add a default package property or suppress it. Tests cover package metadata and generated annotations.
Direct OCI image resolution internal/operator-controller/resolve/...	OCIImageResolver builds bundle metadata from a pulled image filesystem. MultiResolver exposes source-specific catalog and fallback behavior.
Feature-gated reconciliation integration cmd/operator-controller/main.go, internal/operator-controller/controllers/clusterextension_*.go	The OCI resolver is registered when Boxcutter is enabled. Reconciliation validates direct sources and uses resolver behavior to control error fallback. Catalog checks use package-name presence.
Source validation and Catalog compatibility internal/operator-controller/controllers/*_test.go, internal/operator-controller/resolve/catalog_test.go, api/v1/validation_test.go, internal/object-controller/controllers/*_test.go, test/extension-developer-e2e/...	Tests cover OCI image admission and direct-source validation. Catalog fixtures use value-based CatalogFilter fields.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~50 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ClusterExtension
  participant MultiResolver
  participant OCIImageResolver
  participant ImagePuller
  ClusterExtension->>MultiResolver: Resolve OCIImage source
  MultiResolver->>OCIImageResolver: Resolve image reference
  OCIImageResolver->>ImagePuller: Pull image through cache
  ImagePuller-->>OCIImageResolver: Return filesystem and canonical reference
  OCIImageResolver->>OCIImageResolver: Parse bundle and extract version and release
  OCIImageResolver-->>MultiResolver: Return bundle metadata

Loading

Suggested reviewers: perdasilva, joelanford

Resolve the admission and bundle-compatibility regressions before merging: direct OCI sources can be rejected, registry-port references fail validation, and existing catalog installations can fail on previously accepted images.

Direct image installation retains cluster-wide installation authority while removing catalog selection and upgrade checks. Image identity and admission-rule inconsistencies need attention to preserve trustworthy revision records and recovery behavior. No new privilege escalation was established.

Retained concerns

• Medium · security · inferred: The new resolver records the returned canonical digest as bundle and revision identity, but the shared puller resolves that digest before copying from the original reference. If a registry writer moves a tag between those operations, different content may be cached and installed under the earlier digest. The puller condition is pre-existing; the new direct path makes it authoritative for persisted digest identity, affecting provenance and recovery. Digest inputs avoid this tag race, and configured signature policies constrain acceptable content, but no explicit copied-manifest comparison is visible in the inspected pull/cache path. The outcome remains inferred rather than runtime-verified.
• Medium · architecture · inferred: The experimental generated CRD does not implement the declared source union consistently: it omits the OCI payload required/forbidden rule and evaluates catalog.size() even when Catalog should be absent. Valid direct-source admission or updates needed for recovery may fail before reconciliation can run. Controller validation rejects missing direct references, but cannot repair admission failures. This is a source/schema control-drift concern; the precise API-server failure behavior was not exercised.

Security review details

Security Blast Radius

• inferred — A principal able to select direct bundle images can direct content into a cluster-admin installation path. The maximum architectural exposure is the managed cluster, rather than a service-account-isolated tenant. Actual writers, admission restrictions and deployment-specific exposure were not established.

Security Findings and Attack Paths

• inferred — A writer controlling a selected mutable registry tag could move it after manifest-digest resolution but before image copying. The inspected code then stores unpacked content under the earlier digest, which the direct resolver propagates into revision identity. This is a conditional identity-integrity concern, not a verified exploit or a demonstrated new privilege escalation.

Trust Boundaries and Controls

• observed — The new source bypasses Catalog selection but retains explicit discriminator dispatch, runtime gating, nonempty-reference validation, downstream reference parsing and package-metadata checks. These controls constrain source shape and content consistency; they are not registry authorization controls.
• observed — The pre-existing shared puller loads the default signature policy and substitutes insecureAcceptAnything if policy loading fails. The PR reuses this behavior rather than introducing the fallback. Effective signing and registry restrictions depend on deployed configuration, which was not available.

Resilience and Maintainability Implications

• observed — Installed resources retain the existing revision ownership lifecycle. The shared cache is keyed by extension owner and digest, removes failed unpack content, garbage-collects superseded entries, and has a deletion finalizer. These are failure-containment mechanisms, not proof of atomic cache visibility under every concurrent interruption.

Hardening Proposals

• proposed — Bind copying to the resolved immutable reference, or verify the copied manifest against that digest before caching and publishing revision identity. Exercise tag movement and recovery as identity-invariant cases.
• proposed — Align generated admission rules with presence-safe source-union semantics, including both required and forbidden payload cases, so admission and controller dispatch agree across source changes and recovery states.

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.19% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 69 functions across 26 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: implementing a registry+v1 direct bundle installer. It uses the required ✨ prefix and is concise.
Description check	✅ Passed	The description explains the implementation, scope, motivation, related issues, prior work, and RFC. It includes the required Reviewer Checklist, although its items remain unchecked.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Create a new PR

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.