From 283340b45933e8ea5d315e13063d2d2a45cb39e5 Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Fri, 19 Sep 2025 15:01:32 -0400 Subject: [PATCH 01/13] OPRUN-4133: OLMv1 single/own namespace install mode support --- ...ingle-ownnamespace-enhancement-proposal.md | 526 ++++++++++++++++++ 1 file changed, 526 insertions(+) create mode 100644 enhancements/olm/single-ownnamespace-enhancement-proposal.md diff --git a/enhancements/olm/single-ownnamespace-enhancement-proposal.md b/enhancements/olm/single-ownnamespace-enhancement-proposal.md new file mode 100644 index 0000000000..39d2f8420b --- /dev/null +++ b/enhancements/olm/single-ownnamespace-enhancement-proposal.md @@ -0,0 +1,526 @@ +# OLM v1 Single and OwnNamespace Install Mode Support + +title: single-ownnamespace-enhancement-proposal +authors: + - anbhatta +reviewers: + - perdasilva + - joelanford +approvers: + - joelanford +api-approvers: # In case of new or modified APIs or API extensions (CRDs, aggregated apiservers, webhooks, finalizers). If there is no API change, use "None" + - JoelSpeed + - everettraven +creation-date: 2025-09-19 +last-updated: 2025-10-21 +tracking-link: # link to the tracking ticket (for example: Jira Feature or Epic ticket) that corresponds to this enhancement + - https://issues.redhat.com/browse/OPRUN-4133 + + +## Summary + +This enhancement proposes adding limited compatibility support for operator bundles that only declare `Single` and `OwnNamespace` install modes. These bundles are shipped in OpenShift within existing operator catalogs and contain installation bundles installable with OLM v0 (registry+v1 format). This feature enables the rendering and installation of registry+v1 bundles that declare only namespace-scoped install modes, providing a migration path from OLM v0 while maintaining OLM v1's stance on NOT supporting OLMv0's multi-tenancy model. + +The enhancement introduces a configuration mechanism through the ClusterExtension API that allows users to specify a `watchNamespace` parameter as opaque bundle configuration, enabling registry+v1 bundles to be rendered in either SingleNamespace mode (watching a namespace different from the install namespace) or OwnNamespace mode (watching the same namespace where the operator is installed). + +## OLM v1 Design Principles and Scope + +**This enhancement does NOT change OLM v1's core design principles.** OLM v1 maintains its fundamental stances: + +- **No multi-tenancy support**: OLM v1 does not and will not support multi-tenancy features. As stated in the [upstream design decisions](https://operator-framework.github.io/operator-controller/project/olmv1_design_decisions/), "Kubernetes is not multi-tenant with respect to management of APIs (because APIs are global)." +- **No first-class watchNamespace configuration**: OLM v1 does not provide first-class API support for configuring which namespaces a controller watches. +- **Single ownership model**: Each extension is owned by exactly one ClusterExtension to avoid shared ownership complexity. + +This enhancement provides **limited compatibility support for existing registry+v1 bundle content only**. The `watchNamespace` configuration is treated as opaque bundle-provided configuration used solely for rendering registry+v1 bundles into appropriate manifests. This is not a multi-tenancy feature but rather a bundle format compatibility layer to support migration from OLM v0 to OLM v1. + +Future OLM v1 bundle formats will not include these legacy install mode concepts, as OLM v1 will not have first-class features or opinions on RBAC management in next-generation bundle formats. + +## Motivation + +The registry+v1 bundle format (used by OLM v0) includes install mode declarations (AllNamespaces, MultiNamespace, SingleNamespace, OwnNamespace) that affect how bundles are rendered into Kubernetes manifests. OLM v1 deliberately simplified operator installation by focusing on AllNamespaces mode to avoid complexity, but there exists significant existing registry+v1 bundle content in catalogs that only declares support for Single and OwnNamespace install modes. + +### User Stories + +#### Story 1: Legacy Operator Migration +As a cluster administrator migrating from OLM v0 to OLM v1, I want to install operators that only support SingleNamespace or OwnNamespace install modes so that I can continue using existing operator content without requiring operator authors to modify their bundles. + +#### Story 2: Operator Author Requirements +As an operator developer, I have existing registry+v1 bundles that only support Single or OwnNamespace install modes, and I want my customers to be able to deploy these operators in OpenShift with OLM v1 so that the bundle content can be properly rendered and installed without requiring me to modify my existing bundle format during the migration to OLM v1. + +### Goals + +- Enable installation of registry+v1 bundles that only support SingleNamespace or OwnNamespace install modes +- Provide a configuration mechanism through the ClusterExtension API to pass opaque watchNamespace configuration for bundle rendering +- Maintain backward compatibility with existing registry+v1 bundle content from OLM v0 catalogs +- Generate appropriate RBAC resources scoped to the target namespaces for registry+v1 bundles only +- Support seamless migration path for customers moving from OLM v0 to OLM v1 + +#### Future Goals + +- Expand the configuration surface for registry+v1 bundles to support OLMv0 SubscriptionConfig-type behavior, enabling broader operator configuration compatibility during the migration from OLMv0 to OLMv1 + +### Non-Goals + +- Re-introducing multi-tenancy features or supporting multiple installations of the same operator +- Supporting MultiNamespace install mode (watching multiple namespaces) +- Modifying the fundamental OLM v1 architecture or adding complex multi-tenancy logic +- Enabling this feature for bundle formats other than registry+v1 +- Changes to OLM cache infrastructure: OLM will continue to watch bundle contents cluster-scope +- Explicit callout that MultiNamespace is NEVER supported + +## Proposal + +Update the OLMv1 operator-controller to support rendering registry+v1 bundles with Single and OwnNamespace install modes by: +1. Validate bundle compatibility with the requested install mode during reconciliation +2. Parse the `watchNamespace` configuration from ClusterExtension.spec.config.inline +3. Determine the install mode based on the relationship between install namespace and watch namespace +4. Validate the watchNamespace configuration against the install modes supported by the bundle (see below note for more details) +5. Generate appropriate RBAC resources (Roles/RoleBindings vs ClusterRoles/ClusterRoleBindings) based on the determined install mode, for registry+v1 bundles +6. Configure operator deployments with correct environment variables and RBAC for the target watch namespace + +**Specific Resource Changes:** +- **ClusterRole/ClusterRoleBinding**: `clusterPermissions` entries in the CSV are always created as `ClusterRole` and `ClusterRoleBinding` resources regardless of install mode +- **Role/RoleBinding**: `permissions` entries in the CSV are created as `Role` and `RoleBinding` resources in the watch namespace(s). For AllNamespaces mode, these are instead created as `ClusterRole` and `ClusterRoleBinding` resources +- **Operator Configuration**: `olm.targetNamespaces` annotation gets set in the operator deployment's pod template, instructing the operator how to configure itself for the target namespace scope + +`Note`: With watch namespace as a configuration value that can (at times, must) be provided for installation, the user input will be validated based on the bundle's supported install modes: + +| AllNamespaces | SingleNamespace | OwnNamespace | WatchNamespace Configuration | +|---------------|-----------------|--------------|------------------------------------------------------------------| +| - | - | - | undefined/error (no supported install modes) | +| - | - | ✓ | no configuration | +| - | ✓ | - | required (must not be install namespace) | +| - | ✓ | ✓ | optional (default: install namespace) | +| ✓ | - | - | no configuration | +| ✓ | - | ✓ | optional. If set, must be install namespace (default: unset) | +| ✓ | ✓ | - | optional. If set, must NOT be install namespace (default: unset) | +| ✓ | ✓ | ✓ | optional (default: unset) | + +Add support for namespace-scoped operation by ensuring: +1. Bundle validation confirms the operator supports the requested install mode +2. RBAC resources are properly scoped to the watch namespace for Single/OwnNamespace modes +3. Operator deployment environment variables are configured for the specified watch namespace +4. Installation fails gracefully with clear error messages when bundles don't support the requested mode +5. Usage of reasonable default install mode when possible: + - AllNamespaces by default (when available) + - OwnNamespace by default (when no AllNamespaces and available) + +Ensure parity with OLMv0 behavior by: +1. Generating identical RBAC and deployment configurations for equivalent install modes +2. Maintaining the same namespace isolation boundaries +3. Preserving operator functionality across install mode transitions + +### Workflow Description + +#### Administrator Workflow + +1. **Create ServiceAccount**: Administrator creates a ServiceAccount with appropriate permissions in the target namespace +2. **Configure ClusterExtension**: Administrator creates a ClusterExtension resource specifying: + - `spec.namespace`: The installation namespace where the operator pod will run + - `spec.config.inline.watchNamespace`: The namespace the operator should watch for resources + +A scenario exists where the user must specify the watch namespace. Example workflow of a bundle that will require the watch namespace to be specified: + +1. User creates ClusterExtension for a bundle that only supportes SingleNamespace install mode but does not specify the watchNamespace +2. ClusterExtension does not install. The `Installing` and `Progressing` conditions will be set to false with an error that indicates the required `watchNamespace` is not specified +3. User updates the ClusterExtension specifying the `watchNamespace` configuration to be an exiting namespace on the cluster +4. ClusterExtension installs successfully + +``` +Note: Once a ClusterExtension is already installed, OLM will not prevent the `watchNamespace` parameter from being changed by the admin. OLM will reconcile again with the new parameter, however, whether the operator will then re-install successfully is dependent on the operator itself. +``` + +#### Example Configuration + +**OwnNamespace Mode**: +```yaml +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: argocd +spec: + namespace: argocd # Install namespace + serviceAccount: + name: argocd-installer + config: + configType: Inline + inline: + watchNamespace: argocd # Same as install namespace = OwnNamespace + source: + sourceType: Catalog + catalog: + packageName: argocd-operator +``` + +**SingleNamespace Mode**: +```yaml +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: argocd +spec: + namespace: argocd # Install namespace + serviceAccount: + name: argocd-installer + config: + configType: Inline + inline: + watchNamespace: target-namespace # Different namespace = SingleNamespace + source: + sourceType: Catalog + catalog: + packageName: argocd-operator +``` + +### API Extensions + +The ClusterExtension API will be expanded to contain a discriminated union `.spec.config`: + +``` +// ClusterExtensionConfig is a discriminated union which selects the source configuration values to be merged into +// the ClusterExtension's rendered manifests. +// +// +kubebuilder:validation:XValidation:rule="has(self.configType) && self.configType == 'Inline' ?has(self.inline) : !has(self.inline)",message="inline is required when configType is Inline, and forbidden otherwise" +// +union +type ClusterExtensionConfig struct { + // configType is a required reference to the type of configuration source. + // + // Allowed values are "Inline" + // + // When this field is set to "Inline", the cluster extension configuration is defined inline within the + // ClusterExtension resource. + // + // +unionDiscriminator + // +kubebuilder:validation:Enum:="Inline" + // +kubebuilder:validation:Required + ConfigType ClusterExtensionConfigType `json:"configType"` + + // inline contains JSON or YAML values specified directly in the + // ClusterExtension. + // + // inline must be set if configType is 'Inline'. + // inline accepts arbitrary JSON/YAML objects. + // inline is validation at runtime against the schema provided by the bundle if a schema is provided. + // + // +kubebuilder:validation:Type=object + // +optional + Inline *apiextensionsv1.JSON `json:"inline,omitempty"` +} +``` + +``` +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: argocd +spec: + namespace: argocd + serviceAccount: + name: argocd-installer + config: + inline: + watchNamespace: argocd-pipelines + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + version: 0.6.0 +``` + +Initially, only the `Inline` configType will be available. However, we leave it expandable in case further +configuration sources (e.g. ConfigMaps, Secrets, etc.) become needed. + +#### Feature Gate + +This feature can be enabled via the feature gate `NewOLMOwnSingleNamespace` when the feature is in tech preview. + +### Topology Considerations + +#### Hypershift / Hosted Control Planes + +OLMv1 does not yet support Hypershift. Although no aspects of this feature's implementation stands out as at odds with the topology of Hypershift, it should be reviewed when OLMv1 is ready to be supported in Hypershift clusters. + +#### Standalone Clusters +- **Full Compatibility**: Complete support for Single/OwnNamespace modes +- **Standard RBAC**: Normal Role/RoleBinding generation for namespace-scoped permissions + +#### Single-node Deployments or MicroShift + +OLMv1 does not yet support Microshift, but it should be noted that no aspects of this feature's implementation stands out as odds with the topology of Microshift. + +### Implementation Details/Notes/Constraints + +The ClusterExtension CRD used in the registry+v1 bundle installation process is enhanced to: +- Parse watchNamespace configuration from the inline JSON configuration +- Validate watchNamespace against the bundle's supported install modes +- Map install modes based on namespace relationships (install vs watch namespace) +- Generate appropriate RBAC resources scoped to the target namespace + +The system determines the actual install mode based on the bundle's supported install modes and the user's configuration: + + | Bundle Supported Modes | watchNamespace Config | Selected Install Mode | Rationale | +|-------------------------|--------------------------|-----------------------|-----------| +| AllNamespaces only | Not specified | AllNamespaces | Default behavior, no namespace scoping | +| AllNamespaces only | Specified | Error | Bundle doesn't support namespace-scoped installation | +| SingleNamespace only | Not specified | OwnNamespace | Default to most restrictive supported mode | +| SingleNamespace only | Specified (≠ install ns) | SingleNamespace | User's explicit choice, bundle supports it | +| SingleNamespace only | Specified (= install ns) | Error | SingleNamespace cannot watch its own install namespace | +| OwnNamespace only | Not specified | OwnNamespace | Use the only supported mode | +| OwnNamespace only | Specified (= install ns) | OwnNamespace | Explicit choice matches supported mode | +| OwnNamespace only | Specified (≠ install ns) | Error | OwnNamespace can only watch install namespace | +| Single + Own | Not specified | OwnNamespace | Default to more restrictive mode | +| Single + Own | Specified (= install ns) | OwnNamespace | Namespace relationship determines mode | +| Single + Own | Specified (≠ install ns) | SingleNamespace | Namespace relationship determines mode | +| All + Single + Own | Not specified | AllNamespaces | Default to least restrictive mode for compatibility | +| All + Single + Own | Specified (= install ns) | OwnNamespace | Namespace relationship determines mode | +| All + Single + Own | Specified (≠ install ns) | SingleNamespace | Namespace relationship determines mode | + +Default Mode Selection Rules are as follows: + 1. No watchNamespace specified: Use the most permissive mode supported by the bundle (AllNamespaces > OwnNamespace > + SingleNamespace) + 2. watchNamespace = install namespace: Use OwnNamespace mode if supported, otherwise error + 3. watchNamespace ≠ install namespace: Use SingleNamespace mode if supported, otherwise error + 4. Unsupported mode requested: Installation fails with clear error message indicating supported modes + +The relevant generated resources will be: +- Role/RoleBinding resources for namespace-scoped permissions in Single/OwnNamespace modes +- ClusterRole/ClusterRoleBinding resources for cluster-scoped permissions (AllNamespaces mode) +- Deployment resources with correct environment variables for watch namespace configuration +- Service and other supporting resources in the install namespace + +Bundle validation ensures: +- Requested install mode is supported by the bundle's CSV +- Target namespace exists and is accessible +- ServiceAccount has sufficient permissions for the install mode + +#### Configuration Validation +- `watchNamespace` must be a valid DNS1123 subdomain +- Namespace must exist at installation time +- ServiceAccount must have sufficient permissions for the target namespace + +#### Conversion Logic + +The existing OLMv1 bundle converter will support install mode detection and appropriate resource generation via a `WithTargetNamespaces()` option. + +### Risks and Mitigations + +Because we are enabling namespace-scoped operator installations, there are operational implications that could impact cluster management. These risks are mitigated by: + +- **RBAC Misconfiguration**: Install mode validation ensures operators only receive permissions appropriate for their scope +- **Namespace Dependency**: Clear error messages when target namespaces don't exist or aren't accessible +- **Migration Complexity**: Comprehensive documentation and examples for transitioning between install modes +- **Permission Escalation**: ServiceAccount validation ensures adequate permissions without over-privileging + +Currently, admins control the scope of operator installations through ClusterExtension RBAC. This enhancement adds namespace-level controls while maintaining existing security boundaries. + +The feature is alpha and feature-gated, allowing administrators to: +- Control adoption timeline through feature gate management +- Test namespace-scoped installations in non-production environments +- Gradually migrate from AllNamespaces to more targeted install modes + +Operators installed in Single/OwnNamespace modes have reduced blast radius compared to AllNamespaces installations, potentially improving cluster security posture. + +| Risk | Impact | Mitigation | +|------|--------|------------| +| **Increased Complexity** | Medium | Feature is alpha and feature-gated; clear documentation emphasizes this is transitional | +| **RBAC Misconfiguration** | High | Comprehensive validation and clear error messages; documentation provides RBAC examples | +| **Installation Failures** | Medium | Detailed preflight checks and validation; clear error reporting | +| **Security Boundaries** | Medium | Explicit validation of namespace permissions; RBAC properly scoped | +| **Feature Proliferation** | Low | Clear documentation that this is for legacy compatibility only | + +### Drawbacks + +- **Increased API Surface**: Adds configuration complexity to the ClusterExtension API +- **Maintenance Burden**: Requires ongoing support for legacy install modes +- **Potential Confusion**: Users might not understand when to use different install modes +- **Migration Complexity**: Organizations may delay moving to AllNamespaces mode + +## Alternatives (Not Implemented) + +### Alternative 1: Wait for Operator Authors to Migrate +**Description**: Do not implement Single/OwnNamespace support and require all operator authors to modify their bundles to support AllNamespaces mode. + +**Why Not Selected**: +- Would create immediate migration blockers for customers +- Significant ecosystem impact requiring coordination across many operator teams +- Telco and other specialized operators have legitimate namespace isolation requirements + +### Alternative 2: Support All Install Modes Including MultiNamespace +**Description**: Implement full OLM v0 install mode compatibility including MultiNamespace. + +**Why Not Selected**: +- Would reintroduce the multi-tenancy complexity that OLM v1 explicitly avoided +- MultiNamespace mode was a primary source of problems in OLM v0 +- Goes against core OLM v1 design principles + +### Alternative 3: Separate CRD for Namespace-Scoped Operators +**Description**: Create a different API (e.g., NamespacedExtension) for namespace-scoped operator installations. + +**Why Not Selected**: +- Would fragment the operator installation experience +- Adds unnecessary API complexity +- Configuration-based approach is more flexible and maintainable + +## Open Questions +1. Do we want to generate validation schemas for registry+v1 bundles? +2. Should we allow schema files to be packaged in bundles? + +## Test Plan + +### Integration Tests +- **End-to-End Installation**: Test complete installation flow for Single and OwnNamespace modes +- **Bundle Compatibility**: Verify handling of bundles with different install mode support +- **Permission Validation**: Verify ServiceAccount permission requirements + +### Regression Tests +- **Conversion Compatibility**: Ensure generated manifests match OLM v0 output for equivalent configurations +- **Feature Gate Toggle**: Verify behavior when feature gate is disabled + +### Test Data +https://github.com/openshift/operator-framework-operator-controller will include comprehensive test data in `/test/regression/convert/testdata/expected-manifests/` with separate directories for each install mode, providing reference manifests for validation. + +## Graduation Criteria + +### Dev Preview -> Tech Preview +- [ ] Feature-gated implementation behind `NewOLMOwnSingleNamespace` +- [ ] Basic functionality for Single and OwnNamespace modes +- [ ] Unit and integration test coverage +- [ ] Documentation for configuration and usage + +### Tech Preview -> GA +- [ ] 1 OCP release of alpha feedback +- [ ] Production deployment validation +- [ ] Complete documentation including best practices +- [ ] Established support and maintenance processes + +### Removing a deprecated feature + +NA + +## Upgrade / Downgrade Strategy + +### Upgrade Strategy +- **Feature Gate Dependency**: Feature must be enabled via feature gate before configuration can be used +- **Backward Compatibility**: Existing AllNamespaces installations continue to work unchanged +- **Configuration Migration**: No automatic migration; users must explicitly install using OLMv1 ClusterExtension and configure `watchNamespace` + +### Downgrade Strategy +- **Feature Gate Disable**: Disabling the feature gate prevents new Single/OwnNamespace installations +- **Existing Installations**: Already-installed Single/OwnNamespace operators continue to function +- **Configuration Removal**: Removing `watchNamespace` configuration reverts to AllNamespaces mode on next reconciliation + +### Version Compatibility +- **Minimum Version**: Requires OpenShift 4.20+ +- **Configuration Schema**: Uses existing ClusterExtension configuration schema for forward compatibility + +## Operational Aspects of API Extensions + +### Impact of Install Mode Extensions + +**ClusterExtension API Enhancement:** +- **Architectural Impact:** The `config.inline.watchNamespace` field enables runtime install mode selection, moving from compile-time (bundle) to runtime (installation) configuration +- **Operational Impact:** + - Administrators must understand namespace relationships and RBAC implications + - Troubleshooting requires awareness of install vs watch namespace distinctions + - Monitoring and alerting must account for namespace-scoped operator deployments + +**RBAC Resource Generation:** +- **Architectural Impact:** Dynamic RBAC generation based on install mode creates different permission patterns for the same operator +- **Operational Impact:** + - Permission debugging requires understanding of install mode impact on RBAC scope + - Security auditing must consider namespace-level vs cluster-level permission grants + - Upgrade scenarios may change RBAC scope if install mode changes + + +### Impact on Existing SLIs + +With the removal of the install mode concept in olmv1, operator packages that want to continue to use this stop-gap feature are expected to surface configuration documentation, and call out if the `watchNamespace` parameter is a part of it, along with usage example etc. Until a broad percentage of operator pacakges, especially those that don't support `AllNamespaces` mode, take action to make such documentation avaialble, a spike in bad installation is expected. + +**Installation Success Rate:** + +* **RBAC Validation Complexity:** Namespace-scoped installations require more complex RBAC validation to ensure the ServiceAccount has appropriate permissions for the target namespace. RBAC misconfigurations that work in AllNamespaces mode may fail in Single/OwnNamespace modes. + * Example: ServiceAccount has cluster-wide read permissions but lacks namespace-specific write permissions, causing installation to fail. +* **Bundle Compatibility Validation:** Additional validation layer to confirm bundles support the requested install mode. Bundles that only support AllNamespaces will fail when Single/OwnNamespace is requested. + * Example: Attempting to install a bundle with `watchNamespace: "test"` when the bundle CSV only declares support for AllNamespaces install mode. + +**Installation Time:** + +* **Extended Validation Phase:** Additional validation steps for namespace existence, accessibility, and RBAC permissions add latency to the installation process. Each namespace-scoped installation must validate the target namespace and ServiceAccount permissions. +* **RBAC Generation Complexity:** Converting cluster-scoped RBAC to namespace-scoped Role/RoleBinding resources requires additional processing time. Complex operators with extensive permission requirements will see increased installation duration. +* **Cross-Namespace Connectivity Validation:** Single namespace mode requires validation that the operator in the install namespace can access resources in the watch namespace, adding network connectivity checks. + +**Operator Availability:** + +* **Namespace Isolation Impact:** Operators installed in Single/OwnNamespace modes are more susceptible to namespace-level issues. Namespace deletion, network policies, or resource quotas can impact operator availability in ways that don't affect AllNamespaces operators. + * Example: A network policy blocking cross-namespace communication prevents a SingleNamespace operator from accessing its target resources. +* **ServiceAccount Permission Dependencies:** Namespace-scoped operators depend on ServiceAccount permissions that may be modified by namespace administrators, creating additional failure points not present in cluster-scoped installations. + * Example: Namespace admin removes critical RoleBinding, causing operator to lose access to required resources. + +**Resource Utilization:** + +* **RBAC Resource Proliferation:** Each Single/OwnNamespace installation creates namespace-scoped RBAC resources instead of reusing cluster-scoped ones. Multiple operators in different namespaces will create duplicate Role/RoleBinding resources rather than sharing ClusterRole/ClusterRoleBinding resources. + * Example: Installing the same operator in 10 different namespaces creates 10 sets of Role/RoleBinding resources instead of 1 set of ClusterRole/ClusterRoleBinding resources. +* **Namespace Resource Quota Impact:** Operators and their RBAC resources count against namespace resource quotas, potentially causing quota exhaustion that doesn't occur with cluster-scoped installations. + +### Possible Failure Modes + +**Configuration Issues:** +- Invalid watchNamespace specification (DNS1123 validation failures) +- Target namespace doesn't exist or isn't accessible +- ServiceAccount lacks sufficient permissions for namespace access +- Bundle configuration does not include `watchNamespace` + +**Runtime Issues:** +- Operator deployed in install namespace but cannot access watch namespace +- RBAC resources incorrectly scoped for actual operator requirements +- Network policies preventing cross-namespace access when needed + +### OCP Teams Likely to be Called Upon in Case of Escalation + +1. OLM Team (primary) +2. OpenShift API Server Team +3. Networking Team (cross-namespace connectivity) +4. Authentication & Authorization Team (ServiceAccount/RBAC) +5. Layered Product Team + +## Support Procedures + +If there are problems with namespace-scoped operator installations: + +1. **Verify Feature Gate**: Ensure `NewOLMOwnSingleNamespace` is enabled +2. **Check Namespace Existence**: Confirm target watch namespace exists and is accessible +3. **Validate ServiceAccount Permissions**: Verify ServiceAccount has required permissions for target namespace +4. **Review Bundle Compatibility**: Confirm bundle CSV supports the requested install mode +5. **Examine RBAC Resources**: Check generated Role/RoleBinding resources are correctly scoped + +Common troubleshooting scenarios: +- **Installation Stuck**: Check namespace availability and ServiceAccount permissions +- **Operator Not Functioning**: Verify RBAC resources are correctly scoped to watch namespace +- **Permission Denied Errors**: Review ServiceAccount permissions and namespace access rights + +For persistent issues, administrators can: +- Disable feature gate to fall back to AllNamespaces mode +- Modify watchNamespace configuration to change install mode +- Scale down operator-controller to manually intervene if needed + +## Version Skew Strategy + +### Component Interactions +- **operator-controller**: Must support the `NewOLMOwnSingleNamespace` feature gate +- **rukpak**: Uses existing conversion capabilities; no additional requirements +- **catalogs**: No changes required; + +### API Compatibility +- **ClusterExtension API**: Uses existing configuration schema; no API version changes required +- **Bundle Format**: Works with existing registry+v1 bundles without modification +- **Status Reporting**: Uses existing condition and status mechanisms + +### Deployment Considerations +- **Feature Gate Synchronization**: All operator-controller replicas must have consistent feature gate configuration +- **Configuration Validation**: API server validates configuration schema regardless of feature gate state +- **Runtime Behavior**: Feature gate only affects installation behavior, not API acceptance + +#### Feature Dependencies +- **Configuration Support**: This feature builds upon a ClusterExtension configuration infrastructure +- **RBAC Generation**: Leverages existing rukpak RBAC generation capabilities with enhanced scoping logic +- **Feature Gate Framework**: Uses established feature gate patterns for controlled rollout From 3c1e77e3a7b0d17315cee1bd1a3d4ff698be8b2f Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Wed, 22 Oct 2025 16:30:49 -0400 Subject: [PATCH 02/13] Incorporate changes to OwnNamespace default handling procedure More info: https://github.com/operator-framework/operator-controller/pull/2283 --- ...ingle-ownnamespace-enhancement-proposal.md | 109 +++++++++++------- 1 file changed, 69 insertions(+), 40 deletions(-) diff --git a/enhancements/olm/single-ownnamespace-enhancement-proposal.md b/enhancements/olm/single-ownnamespace-enhancement-proposal.md index 39d2f8420b..145e910927 100644 --- a/enhancements/olm/single-ownnamespace-enhancement-proposal.md +++ b/enhancements/olm/single-ownnamespace-enhancement-proposal.md @@ -1,5 +1,4 @@ -# OLM v1 Single and OwnNamespace Install Mode Support - +--- title: single-ownnamespace-enhancement-proposal authors: - anbhatta @@ -9,14 +8,16 @@ reviewers: approvers: - joelanford api-approvers: # In case of new or modified APIs or API extensions (CRDs, aggregated apiservers, webhooks, finalizers). If there is no API change, use "None" - - JoelSpeed - everettraven creation-date: 2025-09-19 last-updated: 2025-10-21 tracking-link: # link to the tracking ticket (for example: Jira Feature or Epic ticket) that corresponds to this enhancement - https://issues.redhat.com/browse/OPRUN-4133 +--- +# OLM v1 Single and OwnNamespace Install Mode Support + ## Summary This enhancement proposes adding limited compatibility support for operator bundles that only declare `Single` and `OwnNamespace` install modes. These bundles are shipped in OpenShift within existing operator catalogs and contain installation bundles installable with OLM v0 (registry+v1 format). This feature enables the rendering and installation of registry+v1 bundles that declare only namespace-scoped install modes, providing a migration path from OLM v0 while maintaining OLM v1's stance on NOT supporting OLMv0's multi-tenancy model. @@ -39,6 +40,22 @@ Future OLM v1 bundle formats will not include these legacy install mode concepts The registry+v1 bundle format (used by OLM v0) includes install mode declarations (AllNamespaces, MultiNamespace, SingleNamespace, OwnNamespace) that affect how bundles are rendered into Kubernetes manifests. OLM v1 deliberately simplified operator installation by focusing on AllNamespaces mode to avoid complexity, but there exists significant existing registry+v1 bundle content in catalogs that only declares support for Single and OwnNamespace install modes. +### Install Mode Upgrade Behavior Edge Case + +An important edge case exists around bundle upgrades and install mode behavior consistency. Consider this scenario: + +1. **Initial State**: An operator bundle (v1.0) supports only `OwnNamespace` install mode +2. **Installation**: User installs the operator without explicit `watchNamespace` configuration +3. **Bundle Update**: Operator author releases bundle (v1.1) that adds `AllNamespaces` support alongside existing `OwnNamespace` support +4. **Unintended Behavior**: Without proper validation, the system could automatically switch from `OwnNamespace` to `AllNamespaces` mode during upgrade, granting the operator cluster-wide permissions without user consent + +This behavior is problematic because: +- **Security Implications**: Operators suddenly gain broader permissions than originally intended +- **Predictability**: Install mode changes occur without explicit administrator action +- **Consistency**: The same bundle configuration produces different permission scopes across versions + +To address this edge case, the implementation requires explicit `watchNamespace` configuration for namespace-scoped bundles (those not supporting `AllNamespaces` mode), ensuring that install mode selection is always deliberate and consistent across bundle upgrades. + ### User Stories #### Story 1: Legacy Operator Migration @@ -47,6 +64,9 @@ As a cluster administrator migrating from OLM v0 to OLM v1, I want to install op #### Story 2: Operator Author Requirements As an operator developer, I have existing registry+v1 bundles that only support Single or OwnNamespace install modes, and I want my customers to be able to deploy these operators in OpenShift with OLM v1 so that the bundle content can be properly rendered and installed without requiring me to modify my existing bundle format during the migration to OLM v1. +#### Story 3: Install Mode Consistency Across Upgrades +As a cluster administrator, I want to ensure that when I install an operator in a specific install mode (e.g., OwnNamespace), subsequent bundle upgrades that add new install mode capabilities (e.g., AllNamespaces) do not automatically change the install mode without my explicit consent, so that my operator's permission scope remains predictable and secure across versions. + ### Goals - Enable installation of registry+v1 bundles that only support SingleNamespace or OwnNamespace install modes @@ -88,12 +108,12 @@ Update the OLMv1 operator-controller to support rendering registry+v1 bundles wi | AllNamespaces | SingleNamespace | OwnNamespace | WatchNamespace Configuration | |---------------|-----------------|--------------|------------------------------------------------------------------| | - | - | - | undefined/error (no supported install modes) | -| - | - | ✓ | no configuration | +| - | - | ✓ | required (must be install namespace) | | - | ✓ | - | required (must not be install namespace) | -| - | ✓ | ✓ | optional (default: install namespace) | -| ✓ | - | - | no configuration | -| ✓ | - | ✓ | optional. If set, must be install namespace (default: unset) | -| ✓ | ✓ | - | optional. If set, must NOT be install namespace (default: unset) | +| - | ✓ | ✓ | required (must specify target namespace) | +| ✓ | - | - | no configuration | +| ✓ | - | ✓ | optional. If set, must be install namespace (default: unset) | +| ✓ | ✓ | - | optional. If set, must NOT be install namespace (default: unset) | | ✓ | ✓ | ✓ | optional (default: unset) | Add support for namespace-scoped operation by ensuring: @@ -119,13 +139,18 @@ Ensure parity with OLMv0 behavior by: - `spec.namespace`: The installation namespace where the operator pod will run - `spec.config.inline.watchNamespace`: The namespace the operator should watch for resources -A scenario exists where the user must specify the watch namespace. Example workflow of a bundle that will require the watch namespace to be specified: +For bundles that only support namespace-scoped install modes (SingleNamespace and/or OwnNamespace, but not AllNamespaces), the `watchNamespace` configuration is **required**. Example workflow: -1. User creates ClusterExtension for a bundle that only supportes SingleNamespace install mode but does not specify the watchNamespace +1. User creates ClusterExtension for a bundle that only supports SingleNamespace or OwnNamespace install mode but does not specify the watchNamespace 2. ClusterExtension does not install. The `Installing` and `Progressing` conditions will be set to false with an error that indicates the required `watchNamespace` is not specified -3. User updates the ClusterExtension specifying the `watchNamespace` configuration to be an exiting namespace on the cluster +3. User updates the ClusterExtension specifying the `watchNamespace` configuration to be an existing namespace on the cluster 4. ClusterExtension installs successfully +This mandatory configuration requirement ensures that: +- Install mode selection is always explicit for namespace-scoped operators +- Bundle upgrades that add AllNamespaces support cannot automatically change the install mode +- Administrators maintain control over operator permission scope across all bundle versions + ``` Note: Once a ClusterExtension is already installed, OLM will not prevent the `watchNamespace` parameter from being changed by the admin. OLM will reconcile again with the new parameter, however, whether the operator will then re-install successfully is dependent on the operator itself. ``` @@ -262,13 +287,13 @@ The system determines the actual install mode based on the bundle's supported in |-------------------------|--------------------------|-----------------------|-----------| | AllNamespaces only | Not specified | AllNamespaces | Default behavior, no namespace scoping | | AllNamespaces only | Specified | Error | Bundle doesn't support namespace-scoped installation | -| SingleNamespace only | Not specified | OwnNamespace | Default to most restrictive supported mode | +| SingleNamespace only | Not specified | Error | watchNamespace required for namespace-scoped bundles | | SingleNamespace only | Specified (≠ install ns) | SingleNamespace | User's explicit choice, bundle supports it | | SingleNamespace only | Specified (= install ns) | Error | SingleNamespace cannot watch its own install namespace | -| OwnNamespace only | Not specified | OwnNamespace | Use the only supported mode | +| OwnNamespace only | Not specified | Error | watchNamespace required for namespace-scoped bundles | | OwnNamespace only | Specified (= install ns) | OwnNamespace | Explicit choice matches supported mode | | OwnNamespace only | Specified (≠ install ns) | Error | OwnNamespace can only watch install namespace | -| Single + Own | Not specified | OwnNamespace | Default to more restrictive mode | +| Single + Own | Not specified | Error | watchNamespace required for namespace-scoped bundles | | Single + Own | Specified (= install ns) | OwnNamespace | Namespace relationship determines mode | | Single + Own | Specified (≠ install ns) | SingleNamespace | Namespace relationship determines mode | | All + Single + Own | Not specified | AllNamespaces | Default to least restrictive mode for compatibility | @@ -276,11 +301,11 @@ The system determines the actual install mode based on the bundle's supported in | All + Single + Own | Specified (≠ install ns) | SingleNamespace | Namespace relationship determines mode | Default Mode Selection Rules are as follows: - 1. No watchNamespace specified: Use the most permissive mode supported by the bundle (AllNamespaces > OwnNamespace > - SingleNamespace) - 2. watchNamespace = install namespace: Use OwnNamespace mode if supported, otherwise error - 3. watchNamespace ≠ install namespace: Use SingleNamespace mode if supported, otherwise error - 4. Unsupported mode requested: Installation fails with clear error message indicating supported modes + 1. **AllNamespaces-capable bundles**: When no `watchNamespace` is specified, default to `AllNamespaces` mode for maximum compatibility + 2. **Namespace-scoped bundles**: When bundles only support `SingleNamespace`/`OwnNamespace` modes, `watchNamespace` configuration is **required** to prevent implicit install mode changes during bundle upgrades + 3. **watchNamespace = install namespace**: Use `OwnNamespace` mode if supported, otherwise error + 4. **watchNamespace ≠ install namespace**: Use `SingleNamespace` mode if supported, otherwise error + 5. **Unsupported mode requested**: Installation fails with clear error message indicating supported modes The relevant generated resources will be: - Role/RoleBinding resources for namespace-scoped permissions in Single/OwnNamespace modes @@ -310,6 +335,7 @@ Because we are enabling namespace-scoped operator installations, there are opera - **Namespace Dependency**: Clear error messages when target namespaces don't exist or aren't accessible - **Migration Complexity**: Comprehensive documentation and examples for transitioning between install modes - **Permission Escalation**: ServiceAccount validation ensures adequate permissions without over-privileging +- **Unintended Install Mode Changes**: Requiring explicit `watchNamespace` configuration for namespace-scoped bundles prevents automatic permission scope escalation when bundle upgrades add new install mode capabilities Currently, admins control the scope of operator installations through ClusterExtension RBAC. This enhancement adds namespace-level controls while maintaining existing security boundaries. @@ -327,6 +353,7 @@ Operators installed in Single/OwnNamespace modes have reduced blast radius compa | **Installation Failures** | Medium | Detailed preflight checks and validation; clear error reporting | | **Security Boundaries** | Medium | Explicit validation of namespace permissions; RBAC properly scoped | | **Feature Proliferation** | Low | Clear documentation that this is for legacy compatibility only | +| **Unintended Install Mode Changes** | High | Mandatory `watchNamespace` configuration for namespace-scoped bundles prevents automatic mode switching during upgrades | ### Drawbacks @@ -373,8 +400,8 @@ Operators installed in Single/OwnNamespace modes have reduced blast radius compa - **Permission Validation**: Verify ServiceAccount permission requirements ### Regression Tests -- **Conversion Compatibility**: Ensure generated manifests match OLM v0 output for equivalent configurations -- **Feature Gate Toggle**: Verify behavior when feature gate is disabled + +NA ### Test Data https://github.com/openshift/operator-framework-operator-controller will include comprehensive test data in `/test/regression/convert/testdata/expected-manifests/` with separate directories for each install mode, providing reference manifests for validation. @@ -400,14 +427,21 @@ NA ## Upgrade / Downgrade Strategy ### Upgrade Strategy -- **Feature Gate Dependency**: Feature must be enabled via feature gate before configuration can be used -- **Backward Compatibility**: Existing AllNamespaces installations continue to work unchanged -- **Configuration Migration**: No automatic migration; users must explicitly install using OLMv1 ClusterExtension and configure `watchNamespace` + +- **Backward Compatibility**: Existing AllNamespaces installations with OLMv0 will continue to work unchanged. +- **Configuration Migration**: No automatic migration from installalled workloads currently being managed by OLMv0; users must explicitly install using OLMv1 ClusterExtension and configure `watchNamespace`. ### Downgrade Strategy -- **Feature Gate Disable**: Disabling the feature gate prevents new Single/OwnNamespace installations -- **Existing Installations**: Already-installed Single/OwnNamespace operators continue to function -- **Configuration Removal**: Removing `watchNamespace` configuration reverts to AllNamespaces mode on next reconciliation + +Downgrading Openshift without removing the field would lead to the field being preserved but ignored because of the following configuration of the `.spec.config` field: + +``` +inline: + type: object + x-kubernetes-preserve-unknown-fields: true +``` + +However, since the RBAC created for the Extension would remain the same, there will be no change in scope for Extensions already installed. ### Version Compatibility - **Minimum Version**: Requires OpenShift 4.20+ @@ -429,7 +463,6 @@ NA - **Operational Impact:** - Permission debugging requires understanding of install mode impact on RBAC scope - Security auditing must consider namespace-level vs cluster-level permission grants - - Upgrade scenarios may change RBAC scope if install mode changes ### Impact on Existing SLIs @@ -445,14 +478,10 @@ With the removal of the install mode concept in olmv1, operator packages that wa **Installation Time:** -* **Extended Validation Phase:** Additional validation steps for namespace existence, accessibility, and RBAC permissions add latency to the installation process. Each namespace-scoped installation must validate the target namespace and ServiceAccount permissions. -* **RBAC Generation Complexity:** Converting cluster-scoped RBAC to namespace-scoped Role/RoleBinding resources requires additional processing time. Complex operators with extensive permission requirements will see increased installation duration. -* **Cross-Namespace Connectivity Validation:** Single namespace mode requires validation that the operator in the install namespace can access resources in the watch namespace, adding network connectivity checks. +* **RBAC Generation Complexity:** Converting CSV `permission` to namespace-scoped Role/RoleBinding resources requires additional processing time. Complex operators with extensive permission requirements will see increased installation duration. **Operator Availability:** -* **Namespace Isolation Impact:** Operators installed in Single/OwnNamespace modes are more susceptible to namespace-level issues. Namespace deletion, network policies, or resource quotas can impact operator availability in ways that don't affect AllNamespaces operators. - * Example: A network policy blocking cross-namespace communication prevents a SingleNamespace operator from accessing its target resources. * **ServiceAccount Permission Dependencies:** Namespace-scoped operators depend on ServiceAccount permissions that may be modified by namespace administrators, creating additional failure points not present in cluster-scoped installations. * Example: Namespace admin removes critical RoleBinding, causing operator to lose access to required resources. @@ -460,7 +489,6 @@ With the removal of the install mode concept in olmv1, operator packages that wa * **RBAC Resource Proliferation:** Each Single/OwnNamespace installation creates namespace-scoped RBAC resources instead of reusing cluster-scoped ones. Multiple operators in different namespaces will create duplicate Role/RoleBinding resources rather than sharing ClusterRole/ClusterRoleBinding resources. * Example: Installing the same operator in 10 different namespaces creates 10 sets of Role/RoleBinding resources instead of 1 set of ClusterRole/ClusterRoleBinding resources. -* **Namespace Resource Quota Impact:** Operators and their RBAC resources count against namespace resource quotas, potentially causing quota exhaustion that doesn't occur with cluster-scoped installations. ### Possible Failure Modes @@ -487,11 +515,10 @@ With the removal of the install mode concept in olmv1, operator packages that wa If there are problems with namespace-scoped operator installations: -1. **Verify Feature Gate**: Ensure `NewOLMOwnSingleNamespace` is enabled -2. **Check Namespace Existence**: Confirm target watch namespace exists and is accessible -3. **Validate ServiceAccount Permissions**: Verify ServiceAccount has required permissions for target namespace -4. **Review Bundle Compatibility**: Confirm bundle CSV supports the requested install mode -5. **Examine RBAC Resources**: Check generated Role/RoleBinding resources are correctly scoped +1. **Check Namespace Existence**: Confirm target watch namespace exists and is accessible +2. **Validate ServiceAccount Permissions**: Verify ServiceAccount has required permissions for target namespace +3. **Review Bundle Compatibility**: Confirm bundle CSV supports the requested install mode +4. **Examine RBAC Resources**: Check generated Role/RoleBinding resources are correctly scoped Common troubleshooting scenarios: - **Installation Stuck**: Check namespace availability and ServiceAccount permissions @@ -505,13 +532,15 @@ For persistent issues, administrators can: ## Version Skew Strategy +This feature is isolated to a the operator-controller component, managed by cluster-olm-operator. Version skew strategy is not required. + ### Component Interactions - **operator-controller**: Must support the `NewOLMOwnSingleNamespace` feature gate - **rukpak**: Uses existing conversion capabilities; no additional requirements - **catalogs**: No changes required; ### API Compatibility -- **ClusterExtension API**: Uses existing configuration schema; no API version changes required +- **ClusterExtension API**: Uses existing configuration schema; - **Bundle Format**: Works with existing registry+v1 bundles without modification - **Status Reporting**: Uses existing condition and status mechanisms From 9e3bcb92a465eff2e0bb477de93ac89afdf14de9 Mon Sep 17 00:00:00 2001 From: "Per G. da Silva" Date: Thu, 30 Oct 2025 15:01:06 -0700 Subject: [PATCH 03/13] More meat on the config bone Signed-off-by: Per G. da Silva Signed-off-by: Per Goncalves da Silva --- .../olm/runtime-bundle-configuration.md | 795 ++++++++++++++++++ ...ingle-ownnamespace-enhancement-proposal.md | 555 ------------ 2 files changed, 795 insertions(+), 555 deletions(-) create mode 100644 enhancements/olm/runtime-bundle-configuration.md delete mode 100644 enhancements/olm/single-ownnamespace-enhancement-proposal.md diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md new file mode 100644 index 0000000000..47a5cc39d8 --- /dev/null +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -0,0 +1,795 @@ +--- +title: runtime-bundle-configuration +authors: + - anbhatta + - perdasilva +reviewers: + - joelanford +approvers: + - joelanford +api-approvers: # In case of new or modified APIs or API extensions (CRDs, aggregated apiservers, webhooks, finalizers). If there is no API change, use "None" + - everettraven +creation-date: 2025-11-05 +last-updated: 2025-11-05 +tracking-link: # link to the tracking ticket (for example: Jira Feature or Epic ticket) that corresponds to this enhancement + - https://issues.redhat.com/browse/OPRUN-4133 +--- + +# OLM v1 Runtime Bundle Configuration + +## Summary + +This enhancement proposes the addition of a configuration layer to the ClusterExtension API surface and an initial +definition for a registry+v1 bundle configuration schema. + +The configuration layer allows users to set bundle configuration whose structure is defined by the bundle authors through +a configuration schema. It provides a single mechanism for configuring bundles independently of the underlying +bundle packaging format, which, while only the registry+v1 format is supported, will be expanded in the future to include +Helm, and registry+v2 formats. + +As registry+v1 bundles don't provide a bundle configuration schema, this enhancement proposes that the schema be +derived by OLM by introspecting the bundle. The enhancement also proposes a first iteration of the registry+v1 bundle +configuration schema will that enable the installation of registry+v1 bundles with Single- and/or OwnNamespace install mode. +The registry+v1 bundle configuration schema will be expanded in future enhancement (while maintaining backwards compatibility). + +## Motivation + +OLMv0's strongly opinionated configuration layer has made it difficult for authors to provide content customization to +their users, and has meant that new configuration knobs had to be added as features to OLM placing the OLM team on +the critical path of authors trying to deliver value to their users. OLMv1 aims to mitigate this by allowing content +authors to define a configuration schema directly in the bundle. + +OLMv1 also aims to support content packaged in different formats (i.e. registry+v1, Helm, registry+v2) but wouldn't like +any format specific concerns to be surfaced at the API level. Users care about content, and not its format. Therefore, +a generic bundle configuration API surface is desired. + +In OLMv0, registry+v1 bundles can be installed in one of four "install modes" used to configure the namespace(s) the +operator should watch for their CR events: +- AllNamespaces: the whole cluster +- SingleNamespace: a single namespace that is _not_ the operator's namespace (i.e. the install namespace) +- OwnNamespace: the operator's namespace +- MultiNamespace: more than one namespace (the operator's namespace can also be used if OwnNamespace is supported by the bundle) + +Currently, OLMv1 only supports registry+v1 bundles with AllNamespaces install mode enabled. Telco use-cases rely on +some operators that only support Single and/or OwnNamespace install modes, or prefer to install in these modes due to +security or resource utilization concerns. + +Install modes are part of the OLMv0 multi-tenancy concept that will not be a part of OLMv1. They enable multiple +instances of the same operator to be installed and reconcile different namespaces. In OLMv1 it will not be possible +to install the same operator multiple times. Therefore, registry+v1 bundle install modes will be treated as +bundle specific configuration. + + +### User Stories + +#### Story 1: Bundle Configuration +As a cluster administrator installing a bundle on my cluster, I'd like to configure the bundle in ways allowed by the +author in order to make the content best fit my cluster and the desired usage. + +#### Story 2: Bundle Configuration Update +As a cluster administrator, I'd like to update the configuration of an installed bundle in ways allowed by the +author in order to make the content best fit my cluster and the desired usage as those needs change over time without +having to re-install the bundle. + +#### Story 3: Bundle Configuration Validation +As a cluster administrator, when I add or update configuration, I don't want the installation/update/upgrade to progress +unless the provided configuration meets the configuration schema provided by the author in order to avoid wrongly +configured or faulty content from being installed on my cluster. + +#### Story 4: Bundle Configuration Consistency Across Upgrades +As a cluster administrator, when OLM automatically progresses my bundle to its next version, if my bundle +configuration no longer fits the schema provided by the author, the upgrade should not progress until the configuration +is fixed in order to avoid wrongly configured or faulty content from being installed. + +#### Story 5: Bundle Configuration Across Formats +As a cluster administrator, when my installed content migrates between formats, I want my upgrades to progress as +they normally would without intervention in order to not be burdened with migration steps. I care about the content, +not the format it is packaged in. + +#### Story 6: Legacy Operator Migration +As a cluster administrator migrating from OLM v0 to OLM v1, I want to install operators that only support SingleNamespace or +OwnNamespace install modes so that I can continue using existing operator content without requiring operator authors to modify +their bundles. + +#### Story 7: Operator Author Requirements +As an operator developer, I have existing registry+v1 bundles that only support Single or OwnNamespace install modes, and I +want my customers to be able to deploy these operators in OpenShift with OLM v1 so that the bundle content can be properly +rendered and installed without requiring me to modify my existing bundle format during the migration to OLM v1. + +### Goals + +- Introduce the notion of bundle configuration into the ClusterExtension API surface in a format agnostic way s.t. it can also be used for other bundle formats such as Helm Charts +- Enable support/rendering for registry+v1 bundles that only support SingleNamespace or OwnNamespace install modes +- Define the registry+v1 bundle schema to support configuration of bundles with Single- and/or OwnNamespace install modes +- Maintain backward compatibility with existing registry+v1 bundle content from OLM v0 catalogs +- Generate appropriate RBAC resources scoped to the target namespaces for registry+v1 bundles only + +### Non-Goals + +- Support for configuration defined in sources outside the ClusterExtension API (e.g. `Secrets` and/or `ConfigMaps`), though this may come in the future if necessary +- Update the catalog server to expose bundle configuration schemas to users, though this may come in the near future +- Define registry+v2 bundle configuration handling +- Occlude secret information +- Support for default configurations outside what can be set in a JSON-schema defined field default values +- Support OLMv0 SubscriptionConfig-type behavior, enabling broader operator configuration compatibility, though this will come in the future +- Support the MultiNamespace install mode: this mode can severally impact api server resource utilization and cause cluster instability. Even in OLMv0 it is documented as unwise to use and that it will likely be removed in the future (OLMv1 is the future). + +## Proposal + +### 1. Expand ClusterExtension API to Include Bundle Configuration + +The ClusterExtension API surface will be expanded to ingest opaque bundle configuration in the form of arbitrary JSON +objects. This moves the concern of bundle configuration from OLM to the bundle author, paving the way for bundles +to provide their own configuration schema. This opaque configuration is utilized by the bundle rendering layer independently +of the underlying bundle format. For example, it can serve as the values.json for Helm bundles. + +The configuration will be supplied inline directly in the ClusterExtension API. The changes to the API will be designed +in such a way that other sources of configuration (e.g. ConfigMaps, or Secrets) can be subsequently added if needed +in the future. + +### 2. Update Bundle Manifest Provisioning Layer + +The bundle manifest provisioning layer is currently responsible for providing the bundle manifests that should be applied +to the cluster. This interface will be expanded to accept the arbitrary configuration coming from the API, validate it, and +account for it when generating the final set of manifests. The given configuration must conform to the configuration schema +provided by the bundle. If the bundle cannot be configured, or the configuration does not strictly comply with the +schema, an error is raised that prevents installation/upgrade/update from proceeding until the user can address the +issue, e.g.: +- User provides configuration but the bundle does not support configuration +- User does not provide required configuration fields +- User provides configuration keys that are not existent +- Bundle does not provide a configuration schema + +### registry+v1 Bundle Configuration Generation, Validation and Handling + +1. Update the registry+v1 manifest provisioning layer to generate a configuration schema for the bundle +2. Update the registry+v1 manifest provisioning layer to validate user provided configuration against the generated schema returning any failures (and thereby aborting the operation) +3. Update the registry+v1 bundle rendering layer to accept the `watchNamespace` configuration for those bundles that support it and render the manifests appropriately + +### Workflow Description + +The standard OLMv1 installation and upgrade workflows stay largely the same. Where it will differ is: +- users will need to consult documentation to understand how packages/bundles can be configured. +- users will be able to specify inline bundle configuration on `.spec.config.inline`. +- install/upgrade operations will be halted if the provided configuration does not meet the bundle provided configuration schema. Errors will be surfaced through the `Progressing` condition outlining the issue, e.g. `invalid bundle configuration: unknown key 'foo'`, or `invalid bundle configuration: missing required key 'bar'`. +- users will be able to update configuration for currently installed content. +- the installer service account must have sufficient permissions for the target namespace. + +Below are outlined the general bundle configuration error flows, and the specific flows for installing bundles in Single- or OwnNamespace mode. + +**user** is the human that has write access to the ClusterExtension API and wants to install an application +on the cluster using OLM. This could be for example the cluster administrator, or a delegate. + +#### 1. Installation/Upgrade - Configuration Validation Failure + +The user wants to install/upgrade a package, or OLM detects an opportunity to auto-upgrade and the given configuration +does not conform to the bundle provided configuration schema: + +1. OLM resolves bundle that needs to be installed from catalogs +2. OLM attempts to generate the bundle manifests with the given configuration +3. Configuration violates the schema provided by the bundle +4. ClusterExtension `Progressing` condition reports bundle configuration error +5. user observes error +6. user consults documentation +7. user rectifies configuration error +8. OLM detects configuration changes +9. ClusterExtension conditions report success and content is installed/updated + +Bundle schema validation can fail for several reasons including: +- configuration was provided by the user, but the resolved bundle does not provide a configuration schema +- configuration includes keys that do not exist in the bundle configuration schema +- configuration does not set a value for a required field +- configuration sets a value of the wrong type (e.g. string where boolean is expected) +- configuration sets a value outside the allowable range (e.g. value must be <= 10 but got 11) or enum set (must be one of \["Turtle", "Elephant", "Capybara"\] but got "Lion") +- configuration sets a value that does not respect the desired format (e.g. value must be a valid url) + +Alternatively, the user can address the issue by returning to the previous happy state by rolling back to a previous version using the +rollback flow described at the bottom of this section. + +#### 2. Upgrade Across Non-Detectable Breaking Changes + +Some breaking API changes such as changes in default behavior, or semantic meaning of fields, can be hard, or impossible, +to detect and _could_ potentially have a large blast radius. By their nature, they are hard to detect. Such an issue would +represent a bug for the content author to address. If the user detects an issue and suspects this to be the case, they can +follow the rollback flow described at the bottom of this section. + +#### 3. Installing an Operator in SingleNamespace or OwnNamespace Modes + +1. user searches catalog for content +2. user reads documentation and understands `watchNamespace` can be used to specify a namespace the operator should watch and whether it can or not be the install namespace +3. user creates a ClusterExtension CR to install that content specifying `.spec.config.inline.watchNamespace` to the desired namespace +4. OLM resolves the bundle +5. The manifest provisioning layer gets the bundle configuration schema and validates the configuration: + 1. `watchNamespace` is a valid namespace name (follows the right format) + 2. `watchNamespace` is not the install namespace if the bundle does not support OwnNamespace + 3. `watchNamespace` is the install namespace if the bundle does not support SingleNamespace +6. OLM applies generated manifests to cluster +7. ClusterExtension conditions report success + +#### Rollback Flow + +First, one must determine the version to rollback to. +If the ClusterExtension attempted an upgrade and is in a failed state, `.status.install` should report the version +of the installed bundle. If the current version was successfully installed in a way that violates the user intent, e.g. +there was a non-detectable breaking change in configuration behavior between bundle versions, then, at present, one needs +to consult the catalog and walk the upgrade graph backwards from the currently installed version. + +Once the target version is determined, a rollback can be done by updating the desired version in the target +ClusterExtension and using the `SelfCertified` upgrade policy in the catalog source config, e.g.: + +``` +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: some-operator +spec: + namespace: some-namespace + serviceAccount: + name: some-service-account + config: + configType: Inline + inline: + ... + source: + sourceType: Catalog + catalog: + packageName: some-package + # --- force rollback to a previous version --- + version: + upgradeConstraintPolicy: SelfCertified + # -------------------------------------------- +``` + +Note: OLMv1 aims to introduce a ClusterExtensionRevision API which would provide a historical record of the different +revisions of the application applied to the cluster over time. This will help the user to identify the previous happy +state without having to manually walk the upgrade graph in reverse. + +### API Extensions + +The ClusterExtension API will be expanded to contain a discriminated union `.spec.config`: + +``` +// ClusterExtensionConfig is a discriminated union which selects the source configuration values to be merged into +// the ClusterExtension's rendered manifests. +// +// +kubebuilder:validation:XValidation:rule="has(self.configType) && self.configType == 'Inline' ?has(self.inline) : !has(self.inline)",message="inline is required when configType is Inline, and forbidden otherwise" +// +union +type ClusterExtensionConfig struct { + // configType is a required reference to the type of configuration source. + // + // Allowed values are "Inline" + // + // When this field is set to "Inline", the cluster extension configuration is defined inline within the + // ClusterExtension resource. + // + // +unionDiscriminator + // +kubebuilder:validation:Enum:="Inline" + // +kubebuilder:validation:Required + ConfigType ClusterExtensionConfigType `json:"configType"` + + // inline contains JSON or YAML values specified directly in the + // ClusterExtension. + // + // inline must be set if configType is 'Inline'. + // inline accepts arbitrary JSON/YAML objects. + // inline is validation at runtime against the schema provided by the bundle if a schema is provided. + // + // +kubebuilder:validation:Type=object + // +optional + Inline *apiextensionsv1.JSON `json:"inline,omitempty"` +} +``` + +Example: + +``` +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: argocd +spec: + namespace: argocd + serviceAccount: + name: argocd-installer + config: + inline: + watchNamespace: argocd-pipelines + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + version: 0.6.0 +``` + +Initially, only the `Inline` configType will be available. However, we leave it expandable in case further +configuration sources (e.g. ConfigMaps, Secrets, etc.) become needed. + +### Topology Considerations + +#### Hypershift / Hosted Control Planes + +OLMv1 does not yet support Hypershift. Although no aspects of this feature's implementation stands out as at odds with +the topology of Hypershift, it should be reviewed when OLMv1 is ready to be supported in Hypershift clusters. + +#### Standalone Clusters + +No specific considerations needed + +#### Single-node Deployments or MicroShift + +No specific considerations needed + +### Implementation Details/Notes/Constraints + +The OLMv1 runtime will operate over a bundle interface that will be common to the supported bundle formats. It won't treat +different formats differently for the purposes of life-cycling. It cares only about generating the required manifests, +and organizing them in a way that it can lifecycle the application. As such, the interface should be generic and not +leak underlying format specific details. The bundle rendering engine should consume opaque configuration, the bundle +interface should provide a configuration schema in JSON Schema format, and rendering will only take place if the +configuration **strictly** adheres to the provided schema, i.e. no additional keys, required fields are set, field value +constraints are observed, etc. + +Taking this approach also means that the configuration schema should be treated like an API surface by the authors +which should ensure it is not broken between minor and patch versions. Breaking changes detectable by the schema will +always stop the install/upgrade/update operation from continuing until the underlying configuration issue is addressed. + +Such issues will be treated as bugs for the content author as opposed to OLM, except in the case of registry+v1 bundles +whose schema is controlled by the OLM team. The OLM team will ensure there are no breaking changes throughout the development +of the registry+v1 configuration schema. + +Any validation errors will be surfaced to the user via the `Progressing` condition with a clear message, e.g.: +- invalid bundle configuration: unknown key 'foo' +- invalid bundle configuration: invalid value for field 'bar' must be less than 10 but got 11 +- invalid bundle configuration: invalid type for field 'fizz' got boolean expected string +- invalid bundle configuration: missing required field 'buzz' +- invalid bundle configuration: bundle 'package.v1.0.0' does not support configuration + +#### registry+v1 Configuration Schema + +Since registry+v1 bundles don't provide configuration schemas, OLM will internally generate them for the bundle. This +enhancement introduces the initial schema which only contains the `watchNamespace` field. A future enhancement will +introduce additional fields without breaking compatibility (i.e. optional fields) to enable `Subscription` `.spec.config` +like customization. + +For the purposes of this enhancement, whether a registry+v1 bundle provides a configuration schema, and whether +`watchNamespace` is required, or optional, or has any value restrictions depends on the bundle's install mode support. + +The following table summarizes this relationship. Each row represents a bundle's supported install modes (marked with ✓ or -), and the resulting `watchNamespace` configuration requirements: + +| AllNamespaces | SingleNamespace | OwnNamespace | WatchNamespace Configuration | +|---------------|-----------------|--------------|-------------------------------------------------------------| +| - | - | - | undefined/error (no supported install modes) | +| - | - | ✓ | required and must be install namespace | +| - | ✓ | - | required and must not be install namespace | +| - | ✓ | ✓ | required and can be any namespace | +| ✓ | - | - | no configuration | +| ✓ | - | ✓ | optional and must be install namespace (default: unset) | +| ✓ | ✓ | - | optional and must NOT be install namespace (default: unset) | +| ✓ | ✓ | ✓ | optional and can be any namespace (default: unset) | + +Given the tight scope and the small configuration surface, the validation may be done programmatically rather than through +the actual generation of a JSON-Schema. However, once this surface expands this will be the direction we'll take and +there should be no difference in behavior beyond the possible wording and structure of error messages. + +Below are examples for what the JSON-Schemas may look like: + +**watchNamespace field required** + +``` +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "watchNamespace": { + "type": "string", + "format": "namespaceName", + } + }, + "required": ["watchNamespace"] +} +``` + +**watchNamespace field optional** + +``` +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "watchNamespace": { + "type": ["string", null], + "format": "namespaceName", + } + }, +} +``` + +**watchNamespace cannot be the install namespace** + +``` +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "watchNamespace": { + "type": ["string", "null"], + "format": "namespaceName", + "not": { + "const": "{{ .installNamespace }}" + } + } + } +} +``` + +**watchNamespace is optional and can only be the install namespace** + +``` +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "watchNamespace": { + "format": "namespaceName", + "enum": ["{{ .installNamespace }}", null] + } + } +} +``` + +Notes: +- The value of `{{ .installNamespace }}` is replaced by the value of `.spec.namespace` in the `ClusterExtension`. +- `namespaceName` is an internally defined format that validates namespace name inputs. It is not a standard format. + +#### registry+v1 Bundle Renderer Changes + +**Specific Resource Changes:** +- **ClusterRole/ClusterRoleBinding**: `clusterPermissions` entries in the `ClusterServiceVersion` are always created as `ClusterRole` and `ClusterRoleBinding` resources regardless of install mode +- **Role/RoleBinding**: `permissions` entries in the `ClusterServiceVersion` are created as `Role` and `RoleBinding` resources in the watch namespace. For AllNamespaces mode, these are instead created as `ClusterRole` and `ClusterRoleBinding` resources +- **Operator Configuration**: `olm.targetNamespaces` annotation gets set in the operator deployment's pod template, instructing the operator how to configure itself for the target namespace scope + +For the `AllNamespaces` mode, the namespaced RBAC specified in the `ClusterServiceVersion` gets rolled up into the +generated `ClusterRole`. For `Single/OwnNamespace` the namespaced RBAC get placed in a role in the `watchNamespace` +and the `Deployment` pod template is updated to set the `olm.targetNamespaces` label to the `watchNamespace`. This tells +the operator how to configure itself. + +#### Install Mode Upgrade Behavior Edge Case + +An important edge case exists around bundle upgrades and install mode behavior consistency. Consider this scenario: + +1. **Initial State**: An operator bundle (v1.0) supports only `OwnNamespace` install mode +2. **Installation**: User installs the operator without explicit `watchNamespace` configuration +3. **Bundle Update**: Operator author releases bundle (v1.1) that adds `AllNamespaces` support alongside existing `OwnNamespace` support +4. **Unintended Behavior**: Without proper validation, the system could automatically switch from `OwnNamespace` to `AllNamespaces` mode during upgrade, granting the operator cluster-wide permissions without user consent + +This behavior is problematic because: +- **Security Implications**: Operators suddenly gain broader permissions than originally intended +- **Predictability**: Install mode changes occur without explicit administrator action +- **Consistency**: The same bundle configuration produces different permission scopes across versions + +To address this edge case, the implementation requires explicit `watchNamespace` configuration for namespace-scoped bundles +(those not supporting `AllNamespaces` mode), ensuring that install mode selection is always deliberate and consistent across +bundle upgrades. We understand this doesn't produce the best UX for this particular case, but such bundles are rare, and +we'll address it in the future with bundle provided default configurations. + +### Risks and Mitigations + +#### 1. Unknown keys + +Unknown keys in configuration can have undesired effects especially between bundle versions. If a configuration key +that is not part of the schema in one version but present in a subsequent version of the bundle is present, this +could violate user intent and potentially place the cluster in an undesired state. + +*Mitigation*: Strict schema validation is applied. Unknown keys cannot be present in the supplied configuration. + +#### 2. Configuration Changes in Detectably Breaking Ways + +If there's a detectable breaking change in the configuration schema, it could be possible to push undesirable changes +onto the cluster or even cause an outage. + +*Mitigation*: Install/Update/Upgrade operations are only allowed to continue if the configuration strictly respects +the configuration schema + +#### 3. Non-existing Configuration Schema + +If a bundle does not define a configuration schema rendering _could_ still take place on a best-effort basis. However, +the system would be susceptible to undesirable changes being applied as no breaking changes could be detected. + +*Mitigation*: For a bundle to be configurable, it must provide a configuration schema. If it does not, and +configuration is supplied, the operation will not progress. + +Note: it's possible that in the future users can override this behavior if they are willing to accept the consequences. + +#### 4. Secret Information + +Often times, users might need to supply an application with secret/privileged information such as passwords, or +api keys. With the current inline approach, if this information *must* be entered in as plain text (as opposed to as +a reference to an existing secret, for instance), the privileged information would be reveled to anyone that can read +the ClusterExtension. It could also cause replication headaches as the privileged information might already exist in a +Secret somewhere, and if the information changes, it would need to be manually updated. + +*Mitigations*: +- Don't give read access to ClusterExtensions, or ClusterExtensions with privileged information to anyone without access to the secret information. +- Don't install the application and contact the supplier and ask for a change in the configuration s.t. a secret reference can be given instead. This also solves the replication issue and ensures no additional copies of the information exist on the cluster between the source (Secret) and the point of use. + +#### 5. Lack of Bundle Supplied Default Configuration + +A bundle may not only want to provide a configuration schema, but also a default configuration beyond what schema +defined default values can offer. For instance, a Helm Chart would contain both a values.json (default configuration) and +a values.schema.json (bundle configuration schema). The lack of support for default configuration makes it hard to +detect drift in default configuration behavior that can cause undesired changes to the cluster state, and force users +to supply configuration even if it doesn't make immediate sense. For instance, + +v1.0.0 of a hypothetical bundle supports only a single "behavior mode" (whatever that is) called `Simple`. When the user +installs v1.0.0, it is installed in the `Simple` behavior mode. Then, v1.1.0 comes along and adds a new behavior +mode `Awesome`, which becomes the new default. The upgrade to v1.1.0 would silently move to the new (default) behavior mode, +which could be undesirable. With default configuration support, we could detect a breaking change in the default behavior +and stop the flow until the user explicitly adds the configuration selecting the desired behavior mode. + +*Mitigations*: +Design the configuration schema for the bundle in a way that it breaks if the default behavior changes. E.g. in the +hypothetical case above, the bundle configuration schema would have a required field `behaviorMode` that can only take +the value `Simple`. + +Note: While OLMv1 only has support for registry+v1 bundles, this is a limitation we can live with. However, this +support will be added by a future enhancement when we start to roll out Helm content support. + +#### 6. Silent Switch in Default on Downgrade + +Downgrading the cluster from the version that immediately introduces this feature might silently re-install +bundles that were installed in `Single-` or `OwnNamespace` mode, if they also support `AllNamespaces` mode. +Because the configuration won't be applied to the bundle, it will be installed with its default configuration. +Which for registry+v1 bundles is `AllNamespaces` mode. + +*Mitigation*: This will need to be called out in documentation. + + +### Drawbacks + +- Configuration validation happens at runtime and not at ingress-time by the kube apiserver +- Bundle configuration schema may evolve in a breaking way requiring manual intervention during auto-upgrade flows +- Bundle configuration schema may evolve in a non-detectable breaking way, e.g. changes in default behavior +- No support for default bundle configuration +- Secret information isn't occluded +- No way to inspect bundle configuration schema outside what will be provided by documentation +- Unideal install UX for registry+v1 bundles that only support OwnNamespaces + +## Alternatives (Not Implemented) + +### Alternative 1: Do nothing +**Description**: Do not implement configuration support. + +**Why Not Selected**: +Bundle configuration is a highly sought after and necessary feature for OLM as a package manager. Without it, +for instance, users wouldn't be able to affect where the operator's pods are schedule on the cluster, or add +additional annotations to bundle resources, pass environment variables, etc. + +### Alternative 2: Format-specific Bundle Configuration +**Description**: Provide different configuration surfaces for different bundle formats + +For instance, registry+v1 bundles could be configured with the `registryV1Configuration` config type, Helm/registry+v2 +could use the `OpaqueConfiguration` type, etc. + +**Why Not Selected**: +- One of the goals of OLM is to provide a single interface across bundle formats +- OLM does not want the user to care about the format types, only about content +- Transitions between format types are visible to the end-user + +## Future Work + +### 1. registry+v1 bundle configuration + +registry+v1 bundles can be configured in two ways: +- `OperatorGroup` `.spec.targetNamespaces`: defines the namespaces the operator should watch for its CRs [ref](https://docs.okd.io/latest/rest_api/operatorhub_apis/operatorgroup-operators-coreos-com-v1.html#spec) +- `Subscription` `.spec.config`: allows users to modify the operator `Deployment`, e.g. add environment variables to the controller container, pod annotations/labels, volumes/volume mounts, etc. [ref](https://docs.okd.io/latest/rest_api/operatorhub_apis/subscription-operators-coreos-com-v1alpha1.html) + +The enhancement to introduce configuration of the target namespace will be introduced in tandem with this enhancement. +Another enhancement for adding support for subscription configuration will be added in the near future. + +### 2. Support to Secret as a bundle configuration resource + +With this enhancement, users will be able to provide inline bundle configuration support. There could be a use-case +for reading configuration from other cluster resources such as Secret/ConfigMap. + +### 3. Support for bundle provided default configurations + +Similarly to Helm's default values.json, a bundle could also provide a default configuration. This is desirable because: +- It gives authors more flexibility in defining default configuration / behavior +- Breaking changes to default configuration could be detected across bundle upgrades and stop them from being silently applied to the cluster + +Once this is introduced, we can also smooth out the install experience for OwnNamespace only registry+v1 bundles. Rather +than expecting the user to set the watchNamespace to the install namespace, that can be the default configuration provided by the bundle. + +### 4. Helm content support + +OLMv1 would like to meet authors where they are and add support for Helm content. Handling custom configuration (values.json) +will be a requirement for this story. + +### 5. registry+v2 + +OLMv1 will eventually add the next iteration of registry+v2. Author provided configuration schemas will be a requirement for this format. + +### 6. Bundle configuration schema discoverability (outside the runtime) + +In the future, we'd like an easy way to surface the bundle configuration schema to users via the console to help users +understand the configuration affordances for the different catalog packages, and bundles. + +### 7. Operational risks of Single/OwnNamespace mode installations + +Because we are enabling namespace-scoped operator installations, there are operational implications that could impact cluster management. These risks are mitigated by: + +- **RBAC Misconfiguration**: Install mode validation ensures operators only receive permissions appropriate for their scope +- **Namespace Dependency**: Clear error messages when target namespaces don't exist or aren't accessible +- **Migration Complexity**: Comprehensive documentation and examples for transitioning between install modes +- **Permission Escalation**: ServiceAccount validation ensures adequate permissions without over-privileging +- **Unintended Install Mode Changes**: Requiring explicit `watchNamespace` configuration for namespace-scoped bundles prevents automatic permission scope escalation when bundle upgrades add new install mode capabilities + +Currently, admins control the scope of operator installations through ClusterExtension RBAC. This enhancement adds namespace-level controls while maintaining existing security boundaries. + +The feature is alpha and feature-gated, allowing administrators to: +- Control adoption timeline through feature gate management +- Test namespace-scoped installations in non-production environments +- Gradually migrate from AllNamespaces to more targeted install modes + +Operators installed in Single/OwnNamespace modes have reduced blast radius compared to AllNamespaces installations, potentially improving cluster security posture. + +| Risk | Impact | Mitigation | +|-------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------| +| **Increased Complexity** | Medium | Feature is alpha and feature-gated; clear documentation emphasizes this is transitional | +| **RBAC Misconfiguration** | High | Comprehensive validation and clear error messages; documentation provides RBAC examples | +| **Installation Failures** | Medium | Detailed preflight checks and validation; clear error reporting | +| **Security Boundaries** | Medium | Explicit validation of namespace permissions; RBAC properly scoped | +| **Feature Proliferation** | Low | Clear documentation that this is for legacy compatibility only | +| **Unintended Install Mode Changes** | High | Mandatory `watchNamespace` configuration for namespace-scoped bundles prevents automatic mode switching during upgrades | + +## Test Plan + +### ClusterExtension API Ingress Validation Tests +- Ensure only JSON objects be given as configuration (and not non-object but valid JSON, e.g. `true`, `1`, etc.) +- Ensure bundle configuration defined as either JSON or YAML can be ingested + +### Integration Tests +- **Configuration Validation**: Test bundle configuration validation is being exercised when configuration is provided + +### Regression Tests + +NA + +## Graduation Criteria + +### Dev Preview -> Tech Preview +- [ ] Feature-gated implementation behind `NewOLMOwnSingleNamespace` +- [ ] Basic functionality for Single and OwnNamespace modes +- [ ] Unit and integration test coverage +- [ ] Documentation for configuration and usage + +### Tech Preview -> GA +- [ ] 1 OCP release of alpha feedback +- [ ] Production deployment validation +- [ ] Complete documentation including best practices +- [ ] Established support and maintenance processes + +### Removing a deprecated feature + +NA + +## Upgrade / Downgrade Strategy + +### Upgrade Strategy + +- **Backward Compatibility**: All existing ClusterExtension CRs will be compatible with the introduction of the API changes +- **Configuration Migration**: No automatic migration from installed workloads currently being managed by OLMv0; users must explicitly install using OLMv1 ClusterExtension and configure `watchNamespace`. + +### Downgrade Strategy + +Remove the `.spec.config` fields from the CRs prior to upgrade. Keep in mind that installations would revert to their default +configuration, e.g.: a bundle that supports `AllNamespaces`, `SingleNamespace` is installed as `SingleNamespace`. It would be +reinstalled as `AllNamespaces` upon downgrade due to the configuration not being applied. + +### Version Compatibility +- **Minimum Version**: Requires OpenShift 4.20+ +- **Configuration Schema**: Uses existing ClusterExtension configuration schema for forward compatibility + +## Operational Aspects of API Extensions + +### Impact of Install Mode Extensions + +**ClusterExtension API Enhancement:** +- **Architectural Impact:** The `config.inline.watchNamespace` field enables runtime install mode selection, moving from compile-time (bundle) to runtime (installation) configuration +- **Operational Impact:** + - Administrators must understand namespace relationships and RBAC implications + - Troubleshooting requires awareness of install vs watch namespace distinctions + - Monitoring and alerting must account for namespace-scoped operator deployments + +**RBAC Resource Generation:** +- **Architectural Impact:** Dynamic RBAC generation based on install mode creates different permission patterns for the same operator +- **Operational Impact:** + - Permission debugging requires understanding of install mode impact on RBAC scope + - Security auditing must consider namespace-level vs cluster-level permission grants + +### Impact on Existing SLIs + +With the removal of the install mode concept in OLMv1, operator packages that want to continue to use this stop-gap feature are expected to surface configuration documentation, and call out if the `watchNamespace` parameter is a part of it, along with usage examples etc. Until a broad percentage of operator packages, especially those that don't support `AllNamespaces` mode, take action to make such documentation available, a spike in bad installations is expected. + +**Installation Success Rate:** + +* **RBAC Validation Complexity:** Namespace-scoped installations require more complex RBAC validation to ensure the ServiceAccount has appropriate permissions for the target namespace. RBAC misconfigurations that work in AllNamespaces mode may fail in Single/OwnNamespace modes. + * Example: ServiceAccount has cluster-wide read permissions but lacks namespace-specific write permissions, causing installation to fail. +* **Bundle Compatibility Validation:** Additional validation layer to confirm bundles support the requested install mode. Bundles that only support AllNamespaces will fail when Single/OwnNamespace is requested. + * Example: Attempting to install a bundle with `watchNamespace: "test"` when the bundle CSV only declares support for AllNamespaces install mode. + +**Installation Time:** + +* **RBAC Generation Complexity:** Converting CSV `permission` to namespace-scoped Role/RoleBinding resources requires additional processing time. Complex operators with extensive permission requirements will see increased installation duration. + +**Operator Availability:** + +* **ServiceAccount Permission Dependencies:** Namespace-scoped operators depend on ServiceAccount permissions that may be modified by namespace administrators, creating additional failure points not present in cluster-scoped installations. + * Example: Namespace admin removes critical RoleBinding, causing operator to lose access to required resources. + +### Possible Failure Modes + +- Invalid bundle configuration + +**Configuration Issues:** +- Invalid watchNamespace specification (DNS1123 validation failures) +- Target namespace doesn't exist or isn't accessible +- ServiceAccount lacks sufficient permissions for namespace access +- Bundle configuration does not include `watchNamespace` +- Bundle configuration requires `watchNamespace` +- Given `watchNamespace` cannot be used, e.g. it is set to the install namespace but `OwnNamespace` is not supported by the bundle + +**Runtime Issues:** +- Operator deployed in install namespace but cannot access watch namespace +- RBAC resources incorrectly scoped for actual operator requirements +- Network policies preventing cross-namespace access when needed + +### OCP Teams Likely to be Called Upon in Case of Escalation + +1. OLM Team (primary) +2. OpenShift API Server Team +3. Networking Team (cross-namespace connectivity) +4. Authentication & Authorization Team (ServiceAccount/RBAC) +5. Layered Product Team + +## Support Procedures + +If there are problems with namespace-scoped operator installations: + +1. **Check Namespace Existence**: Confirm target watch namespace exists and is accessible +2. **Validate ServiceAccount Permissions**: Verify ServiceAccount has required permissions for target namespace +3. **Review Bundle Compatibility**: Confirm bundle CSV supports the requested install mode +4. **Examine RBAC Resources**: Check generated Role/RoleBinding resources are correctly scoped + +Common troubleshooting scenarios: +- **Installation Stuck**: Check namespace availability and ServiceAccount permissions +- **Operator Not Functioning**: Verify RBAC resources are correctly scoped to watch namespace +- **Permission Denied Errors**: Review ServiceAccount permissions and namespace access rights + +For persistent issues, administrators can: +- Disable feature gate to fall back to AllNamespaces mode +- Modify watchNamespace configuration to change install mode +- Scale down operator-controller to manually intervene if needed + +## Version Skew Strategy + +This feature is isolated to the operator-controller component, managed by cluster-olm-operator. Version skew strategy is not required. + +### Component Interactions + +The operator-controller is deployed by the cluster-olm-operator. There are no other component interactions. This +enhancement does not impact that interaction. + +### API Compatibility +- **ClusterExtension API**: Uses existing configuration schema; +- **Bundle Format**: Works with existing registry+v1 bundles without modification +- **Status Reporting**: Uses existing condition and status mechanisms + +### Deployment Considerations +- **Configuration Validation**: API server validates configuration schema regardless of feature gate state +- **Runtime Behavior**: Feature gate only affects installation behavior, not API acceptance + +#### Feature Dependencies +- **Configuration Support**: This feature builds upon a ClusterExtension configuration infrastructure +- **RBAC Generation**: Leverages existing rukpak RBAC generation capabilities with enhanced scoping logic +- **Feature Gate Framework**: Uses established feature gate patterns for controlled rollout diff --git a/enhancements/olm/single-ownnamespace-enhancement-proposal.md b/enhancements/olm/single-ownnamespace-enhancement-proposal.md deleted file mode 100644 index 145e910927..0000000000 --- a/enhancements/olm/single-ownnamespace-enhancement-proposal.md +++ /dev/null @@ -1,555 +0,0 @@ ---- -title: single-ownnamespace-enhancement-proposal -authors: - - anbhatta -reviewers: - - perdasilva - - joelanford -approvers: - - joelanford -api-approvers: # In case of new or modified APIs or API extensions (CRDs, aggregated apiservers, webhooks, finalizers). If there is no API change, use "None" - - everettraven -creation-date: 2025-09-19 -last-updated: 2025-10-21 -tracking-link: # link to the tracking ticket (for example: Jira Feature or Epic ticket) that corresponds to this enhancement - - https://issues.redhat.com/browse/OPRUN-4133 ---- - - -# OLM v1 Single and OwnNamespace Install Mode Support - -## Summary - -This enhancement proposes adding limited compatibility support for operator bundles that only declare `Single` and `OwnNamespace` install modes. These bundles are shipped in OpenShift within existing operator catalogs and contain installation bundles installable with OLM v0 (registry+v1 format). This feature enables the rendering and installation of registry+v1 bundles that declare only namespace-scoped install modes, providing a migration path from OLM v0 while maintaining OLM v1's stance on NOT supporting OLMv0's multi-tenancy model. - -The enhancement introduces a configuration mechanism through the ClusterExtension API that allows users to specify a `watchNamespace` parameter as opaque bundle configuration, enabling registry+v1 bundles to be rendered in either SingleNamespace mode (watching a namespace different from the install namespace) or OwnNamespace mode (watching the same namespace where the operator is installed). - -## OLM v1 Design Principles and Scope - -**This enhancement does NOT change OLM v1's core design principles.** OLM v1 maintains its fundamental stances: - -- **No multi-tenancy support**: OLM v1 does not and will not support multi-tenancy features. As stated in the [upstream design decisions](https://operator-framework.github.io/operator-controller/project/olmv1_design_decisions/), "Kubernetes is not multi-tenant with respect to management of APIs (because APIs are global)." -- **No first-class watchNamespace configuration**: OLM v1 does not provide first-class API support for configuring which namespaces a controller watches. -- **Single ownership model**: Each extension is owned by exactly one ClusterExtension to avoid shared ownership complexity. - -This enhancement provides **limited compatibility support for existing registry+v1 bundle content only**. The `watchNamespace` configuration is treated as opaque bundle-provided configuration used solely for rendering registry+v1 bundles into appropriate manifests. This is not a multi-tenancy feature but rather a bundle format compatibility layer to support migration from OLM v0 to OLM v1. - -Future OLM v1 bundle formats will not include these legacy install mode concepts, as OLM v1 will not have first-class features or opinions on RBAC management in next-generation bundle formats. - -## Motivation - -The registry+v1 bundle format (used by OLM v0) includes install mode declarations (AllNamespaces, MultiNamespace, SingleNamespace, OwnNamespace) that affect how bundles are rendered into Kubernetes manifests. OLM v1 deliberately simplified operator installation by focusing on AllNamespaces mode to avoid complexity, but there exists significant existing registry+v1 bundle content in catalogs that only declares support for Single and OwnNamespace install modes. - -### Install Mode Upgrade Behavior Edge Case - -An important edge case exists around bundle upgrades and install mode behavior consistency. Consider this scenario: - -1. **Initial State**: An operator bundle (v1.0) supports only `OwnNamespace` install mode -2. **Installation**: User installs the operator without explicit `watchNamespace` configuration -3. **Bundle Update**: Operator author releases bundle (v1.1) that adds `AllNamespaces` support alongside existing `OwnNamespace` support -4. **Unintended Behavior**: Without proper validation, the system could automatically switch from `OwnNamespace` to `AllNamespaces` mode during upgrade, granting the operator cluster-wide permissions without user consent - -This behavior is problematic because: -- **Security Implications**: Operators suddenly gain broader permissions than originally intended -- **Predictability**: Install mode changes occur without explicit administrator action -- **Consistency**: The same bundle configuration produces different permission scopes across versions - -To address this edge case, the implementation requires explicit `watchNamespace` configuration for namespace-scoped bundles (those not supporting `AllNamespaces` mode), ensuring that install mode selection is always deliberate and consistent across bundle upgrades. - -### User Stories - -#### Story 1: Legacy Operator Migration -As a cluster administrator migrating from OLM v0 to OLM v1, I want to install operators that only support SingleNamespace or OwnNamespace install modes so that I can continue using existing operator content without requiring operator authors to modify their bundles. - -#### Story 2: Operator Author Requirements -As an operator developer, I have existing registry+v1 bundles that only support Single or OwnNamespace install modes, and I want my customers to be able to deploy these operators in OpenShift with OLM v1 so that the bundle content can be properly rendered and installed without requiring me to modify my existing bundle format during the migration to OLM v1. - -#### Story 3: Install Mode Consistency Across Upgrades -As a cluster administrator, I want to ensure that when I install an operator in a specific install mode (e.g., OwnNamespace), subsequent bundle upgrades that add new install mode capabilities (e.g., AllNamespaces) do not automatically change the install mode without my explicit consent, so that my operator's permission scope remains predictable and secure across versions. - -### Goals - -- Enable installation of registry+v1 bundles that only support SingleNamespace or OwnNamespace install modes -- Provide a configuration mechanism through the ClusterExtension API to pass opaque watchNamespace configuration for bundle rendering -- Maintain backward compatibility with existing registry+v1 bundle content from OLM v0 catalogs -- Generate appropriate RBAC resources scoped to the target namespaces for registry+v1 bundles only -- Support seamless migration path for customers moving from OLM v0 to OLM v1 - -#### Future Goals - -- Expand the configuration surface for registry+v1 bundles to support OLMv0 SubscriptionConfig-type behavior, enabling broader operator configuration compatibility during the migration from OLMv0 to OLMv1 - -### Non-Goals - -- Re-introducing multi-tenancy features or supporting multiple installations of the same operator -- Supporting MultiNamespace install mode (watching multiple namespaces) -- Modifying the fundamental OLM v1 architecture or adding complex multi-tenancy logic -- Enabling this feature for bundle formats other than registry+v1 -- Changes to OLM cache infrastructure: OLM will continue to watch bundle contents cluster-scope -- Explicit callout that MultiNamespace is NEVER supported - -## Proposal - -Update the OLMv1 operator-controller to support rendering registry+v1 bundles with Single and OwnNamespace install modes by: -1. Validate bundle compatibility with the requested install mode during reconciliation -2. Parse the `watchNamespace` configuration from ClusterExtension.spec.config.inline -3. Determine the install mode based on the relationship between install namespace and watch namespace -4. Validate the watchNamespace configuration against the install modes supported by the bundle (see below note for more details) -5. Generate appropriate RBAC resources (Roles/RoleBindings vs ClusterRoles/ClusterRoleBindings) based on the determined install mode, for registry+v1 bundles -6. Configure operator deployments with correct environment variables and RBAC for the target watch namespace - -**Specific Resource Changes:** -- **ClusterRole/ClusterRoleBinding**: `clusterPermissions` entries in the CSV are always created as `ClusterRole` and `ClusterRoleBinding` resources regardless of install mode -- **Role/RoleBinding**: `permissions` entries in the CSV are created as `Role` and `RoleBinding` resources in the watch namespace(s). For AllNamespaces mode, these are instead created as `ClusterRole` and `ClusterRoleBinding` resources -- **Operator Configuration**: `olm.targetNamespaces` annotation gets set in the operator deployment's pod template, instructing the operator how to configure itself for the target namespace scope - -`Note`: With watch namespace as a configuration value that can (at times, must) be provided for installation, the user input will be validated based on the bundle's supported install modes: - -| AllNamespaces | SingleNamespace | OwnNamespace | WatchNamespace Configuration | -|---------------|-----------------|--------------|------------------------------------------------------------------| -| - | - | - | undefined/error (no supported install modes) | -| - | - | ✓ | required (must be install namespace) | -| - | ✓ | - | required (must not be install namespace) | -| - | ✓ | ✓ | required (must specify target namespace) | -| ✓ | - | - | no configuration | -| ✓ | - | ✓ | optional. If set, must be install namespace (default: unset) | -| ✓ | ✓ | - | optional. If set, must NOT be install namespace (default: unset) | -| ✓ | ✓ | ✓ | optional (default: unset) | - -Add support for namespace-scoped operation by ensuring: -1. Bundle validation confirms the operator supports the requested install mode -2. RBAC resources are properly scoped to the watch namespace for Single/OwnNamespace modes -3. Operator deployment environment variables are configured for the specified watch namespace -4. Installation fails gracefully with clear error messages when bundles don't support the requested mode -5. Usage of reasonable default install mode when possible: - - AllNamespaces by default (when available) - - OwnNamespace by default (when no AllNamespaces and available) - -Ensure parity with OLMv0 behavior by: -1. Generating identical RBAC and deployment configurations for equivalent install modes -2. Maintaining the same namespace isolation boundaries -3. Preserving operator functionality across install mode transitions - -### Workflow Description - -#### Administrator Workflow - -1. **Create ServiceAccount**: Administrator creates a ServiceAccount with appropriate permissions in the target namespace -2. **Configure ClusterExtension**: Administrator creates a ClusterExtension resource specifying: - - `spec.namespace`: The installation namespace where the operator pod will run - - `spec.config.inline.watchNamespace`: The namespace the operator should watch for resources - -For bundles that only support namespace-scoped install modes (SingleNamespace and/or OwnNamespace, but not AllNamespaces), the `watchNamespace` configuration is **required**. Example workflow: - -1. User creates ClusterExtension for a bundle that only supports SingleNamespace or OwnNamespace install mode but does not specify the watchNamespace -2. ClusterExtension does not install. The `Installing` and `Progressing` conditions will be set to false with an error that indicates the required `watchNamespace` is not specified -3. User updates the ClusterExtension specifying the `watchNamespace` configuration to be an existing namespace on the cluster -4. ClusterExtension installs successfully - -This mandatory configuration requirement ensures that: -- Install mode selection is always explicit for namespace-scoped operators -- Bundle upgrades that add AllNamespaces support cannot automatically change the install mode -- Administrators maintain control over operator permission scope across all bundle versions - -``` -Note: Once a ClusterExtension is already installed, OLM will not prevent the `watchNamespace` parameter from being changed by the admin. OLM will reconcile again with the new parameter, however, whether the operator will then re-install successfully is dependent on the operator itself. -``` - -#### Example Configuration - -**OwnNamespace Mode**: -```yaml -apiVersion: olm.operatorframework.io/v1 -kind: ClusterExtension -metadata: - name: argocd -spec: - namespace: argocd # Install namespace - serviceAccount: - name: argocd-installer - config: - configType: Inline - inline: - watchNamespace: argocd # Same as install namespace = OwnNamespace - source: - sourceType: Catalog - catalog: - packageName: argocd-operator -``` - -**SingleNamespace Mode**: -```yaml -apiVersion: olm.operatorframework.io/v1 -kind: ClusterExtension -metadata: - name: argocd -spec: - namespace: argocd # Install namespace - serviceAccount: - name: argocd-installer - config: - configType: Inline - inline: - watchNamespace: target-namespace # Different namespace = SingleNamespace - source: - sourceType: Catalog - catalog: - packageName: argocd-operator -``` - -### API Extensions - -The ClusterExtension API will be expanded to contain a discriminated union `.spec.config`: - -``` -// ClusterExtensionConfig is a discriminated union which selects the source configuration values to be merged into -// the ClusterExtension's rendered manifests. -// -// +kubebuilder:validation:XValidation:rule="has(self.configType) && self.configType == 'Inline' ?has(self.inline) : !has(self.inline)",message="inline is required when configType is Inline, and forbidden otherwise" -// +union -type ClusterExtensionConfig struct { - // configType is a required reference to the type of configuration source. - // - // Allowed values are "Inline" - // - // When this field is set to "Inline", the cluster extension configuration is defined inline within the - // ClusterExtension resource. - // - // +unionDiscriminator - // +kubebuilder:validation:Enum:="Inline" - // +kubebuilder:validation:Required - ConfigType ClusterExtensionConfigType `json:"configType"` - - // inline contains JSON or YAML values specified directly in the - // ClusterExtension. - // - // inline must be set if configType is 'Inline'. - // inline accepts arbitrary JSON/YAML objects. - // inline is validation at runtime against the schema provided by the bundle if a schema is provided. - // - // +kubebuilder:validation:Type=object - // +optional - Inline *apiextensionsv1.JSON `json:"inline,omitempty"` -} -``` - -``` -apiVersion: olm.operatorframework.io/v1 -kind: ClusterExtension -metadata: - name: argocd -spec: - namespace: argocd - serviceAccount: - name: argocd-installer - config: - inline: - watchNamespace: argocd-pipelines - source: - sourceType: Catalog - catalog: - packageName: argocd-operator - version: 0.6.0 -``` - -Initially, only the `Inline` configType will be available. However, we leave it expandable in case further -configuration sources (e.g. ConfigMaps, Secrets, etc.) become needed. - -#### Feature Gate - -This feature can be enabled via the feature gate `NewOLMOwnSingleNamespace` when the feature is in tech preview. - -### Topology Considerations - -#### Hypershift / Hosted Control Planes - -OLMv1 does not yet support Hypershift. Although no aspects of this feature's implementation stands out as at odds with the topology of Hypershift, it should be reviewed when OLMv1 is ready to be supported in Hypershift clusters. - -#### Standalone Clusters -- **Full Compatibility**: Complete support for Single/OwnNamespace modes -- **Standard RBAC**: Normal Role/RoleBinding generation for namespace-scoped permissions - -#### Single-node Deployments or MicroShift - -OLMv1 does not yet support Microshift, but it should be noted that no aspects of this feature's implementation stands out as odds with the topology of Microshift. - -### Implementation Details/Notes/Constraints - -The ClusterExtension CRD used in the registry+v1 bundle installation process is enhanced to: -- Parse watchNamespace configuration from the inline JSON configuration -- Validate watchNamespace against the bundle's supported install modes -- Map install modes based on namespace relationships (install vs watch namespace) -- Generate appropriate RBAC resources scoped to the target namespace - -The system determines the actual install mode based on the bundle's supported install modes and the user's configuration: - - | Bundle Supported Modes | watchNamespace Config | Selected Install Mode | Rationale | -|-------------------------|--------------------------|-----------------------|-----------| -| AllNamespaces only | Not specified | AllNamespaces | Default behavior, no namespace scoping | -| AllNamespaces only | Specified | Error | Bundle doesn't support namespace-scoped installation | -| SingleNamespace only | Not specified | Error | watchNamespace required for namespace-scoped bundles | -| SingleNamespace only | Specified (≠ install ns) | SingleNamespace | User's explicit choice, bundle supports it | -| SingleNamespace only | Specified (= install ns) | Error | SingleNamespace cannot watch its own install namespace | -| OwnNamespace only | Not specified | Error | watchNamespace required for namespace-scoped bundles | -| OwnNamespace only | Specified (= install ns) | OwnNamespace | Explicit choice matches supported mode | -| OwnNamespace only | Specified (≠ install ns) | Error | OwnNamespace can only watch install namespace | -| Single + Own | Not specified | Error | watchNamespace required for namespace-scoped bundles | -| Single + Own | Specified (= install ns) | OwnNamespace | Namespace relationship determines mode | -| Single + Own | Specified (≠ install ns) | SingleNamespace | Namespace relationship determines mode | -| All + Single + Own | Not specified | AllNamespaces | Default to least restrictive mode for compatibility | -| All + Single + Own | Specified (= install ns) | OwnNamespace | Namespace relationship determines mode | -| All + Single + Own | Specified (≠ install ns) | SingleNamespace | Namespace relationship determines mode | - -Default Mode Selection Rules are as follows: - 1. **AllNamespaces-capable bundles**: When no `watchNamespace` is specified, default to `AllNamespaces` mode for maximum compatibility - 2. **Namespace-scoped bundles**: When bundles only support `SingleNamespace`/`OwnNamespace` modes, `watchNamespace` configuration is **required** to prevent implicit install mode changes during bundle upgrades - 3. **watchNamespace = install namespace**: Use `OwnNamespace` mode if supported, otherwise error - 4. **watchNamespace ≠ install namespace**: Use `SingleNamespace` mode if supported, otherwise error - 5. **Unsupported mode requested**: Installation fails with clear error message indicating supported modes - -The relevant generated resources will be: -- Role/RoleBinding resources for namespace-scoped permissions in Single/OwnNamespace modes -- ClusterRole/ClusterRoleBinding resources for cluster-scoped permissions (AllNamespaces mode) -- Deployment resources with correct environment variables for watch namespace configuration -- Service and other supporting resources in the install namespace - -Bundle validation ensures: -- Requested install mode is supported by the bundle's CSV -- Target namespace exists and is accessible -- ServiceAccount has sufficient permissions for the install mode - -#### Configuration Validation -- `watchNamespace` must be a valid DNS1123 subdomain -- Namespace must exist at installation time -- ServiceAccount must have sufficient permissions for the target namespace - -#### Conversion Logic - -The existing OLMv1 bundle converter will support install mode detection and appropriate resource generation via a `WithTargetNamespaces()` option. - -### Risks and Mitigations - -Because we are enabling namespace-scoped operator installations, there are operational implications that could impact cluster management. These risks are mitigated by: - -- **RBAC Misconfiguration**: Install mode validation ensures operators only receive permissions appropriate for their scope -- **Namespace Dependency**: Clear error messages when target namespaces don't exist or aren't accessible -- **Migration Complexity**: Comprehensive documentation and examples for transitioning between install modes -- **Permission Escalation**: ServiceAccount validation ensures adequate permissions without over-privileging -- **Unintended Install Mode Changes**: Requiring explicit `watchNamespace` configuration for namespace-scoped bundles prevents automatic permission scope escalation when bundle upgrades add new install mode capabilities - -Currently, admins control the scope of operator installations through ClusterExtension RBAC. This enhancement adds namespace-level controls while maintaining existing security boundaries. - -The feature is alpha and feature-gated, allowing administrators to: -- Control adoption timeline through feature gate management -- Test namespace-scoped installations in non-production environments -- Gradually migrate from AllNamespaces to more targeted install modes - -Operators installed in Single/OwnNamespace modes have reduced blast radius compared to AllNamespaces installations, potentially improving cluster security posture. - -| Risk | Impact | Mitigation | -|------|--------|------------| -| **Increased Complexity** | Medium | Feature is alpha and feature-gated; clear documentation emphasizes this is transitional | -| **RBAC Misconfiguration** | High | Comprehensive validation and clear error messages; documentation provides RBAC examples | -| **Installation Failures** | Medium | Detailed preflight checks and validation; clear error reporting | -| **Security Boundaries** | Medium | Explicit validation of namespace permissions; RBAC properly scoped | -| **Feature Proliferation** | Low | Clear documentation that this is for legacy compatibility only | -| **Unintended Install Mode Changes** | High | Mandatory `watchNamespace` configuration for namespace-scoped bundles prevents automatic mode switching during upgrades | - -### Drawbacks - -- **Increased API Surface**: Adds configuration complexity to the ClusterExtension API -- **Maintenance Burden**: Requires ongoing support for legacy install modes -- **Potential Confusion**: Users might not understand when to use different install modes -- **Migration Complexity**: Organizations may delay moving to AllNamespaces mode - -## Alternatives (Not Implemented) - -### Alternative 1: Wait for Operator Authors to Migrate -**Description**: Do not implement Single/OwnNamespace support and require all operator authors to modify their bundles to support AllNamespaces mode. - -**Why Not Selected**: -- Would create immediate migration blockers for customers -- Significant ecosystem impact requiring coordination across many operator teams -- Telco and other specialized operators have legitimate namespace isolation requirements - -### Alternative 2: Support All Install Modes Including MultiNamespace -**Description**: Implement full OLM v0 install mode compatibility including MultiNamespace. - -**Why Not Selected**: -- Would reintroduce the multi-tenancy complexity that OLM v1 explicitly avoided -- MultiNamespace mode was a primary source of problems in OLM v0 -- Goes against core OLM v1 design principles - -### Alternative 3: Separate CRD for Namespace-Scoped Operators -**Description**: Create a different API (e.g., NamespacedExtension) for namespace-scoped operator installations. - -**Why Not Selected**: -- Would fragment the operator installation experience -- Adds unnecessary API complexity -- Configuration-based approach is more flexible and maintainable - -## Open Questions -1. Do we want to generate validation schemas for registry+v1 bundles? -2. Should we allow schema files to be packaged in bundles? - -## Test Plan - -### Integration Tests -- **End-to-End Installation**: Test complete installation flow for Single and OwnNamespace modes -- **Bundle Compatibility**: Verify handling of bundles with different install mode support -- **Permission Validation**: Verify ServiceAccount permission requirements - -### Regression Tests - -NA - -### Test Data -https://github.com/openshift/operator-framework-operator-controller will include comprehensive test data in `/test/regression/convert/testdata/expected-manifests/` with separate directories for each install mode, providing reference manifests for validation. - -## Graduation Criteria - -### Dev Preview -> Tech Preview -- [ ] Feature-gated implementation behind `NewOLMOwnSingleNamespace` -- [ ] Basic functionality for Single and OwnNamespace modes -- [ ] Unit and integration test coverage -- [ ] Documentation for configuration and usage - -### Tech Preview -> GA -- [ ] 1 OCP release of alpha feedback -- [ ] Production deployment validation -- [ ] Complete documentation including best practices -- [ ] Established support and maintenance processes - -### Removing a deprecated feature - -NA - -## Upgrade / Downgrade Strategy - -### Upgrade Strategy - -- **Backward Compatibility**: Existing AllNamespaces installations with OLMv0 will continue to work unchanged. -- **Configuration Migration**: No automatic migration from installalled workloads currently being managed by OLMv0; users must explicitly install using OLMv1 ClusterExtension and configure `watchNamespace`. - -### Downgrade Strategy - -Downgrading Openshift without removing the field would lead to the field being preserved but ignored because of the following configuration of the `.spec.config` field: - -``` -inline: - type: object - x-kubernetes-preserve-unknown-fields: true -``` - -However, since the RBAC created for the Extension would remain the same, there will be no change in scope for Extensions already installed. - -### Version Compatibility -- **Minimum Version**: Requires OpenShift 4.20+ -- **Configuration Schema**: Uses existing ClusterExtension configuration schema for forward compatibility - -## Operational Aspects of API Extensions - -### Impact of Install Mode Extensions - -**ClusterExtension API Enhancement:** -- **Architectural Impact:** The `config.inline.watchNamespace` field enables runtime install mode selection, moving from compile-time (bundle) to runtime (installation) configuration -- **Operational Impact:** - - Administrators must understand namespace relationships and RBAC implications - - Troubleshooting requires awareness of install vs watch namespace distinctions - - Monitoring and alerting must account for namespace-scoped operator deployments - -**RBAC Resource Generation:** -- **Architectural Impact:** Dynamic RBAC generation based on install mode creates different permission patterns for the same operator -- **Operational Impact:** - - Permission debugging requires understanding of install mode impact on RBAC scope - - Security auditing must consider namespace-level vs cluster-level permission grants - - -### Impact on Existing SLIs - -With the removal of the install mode concept in olmv1, operator packages that want to continue to use this stop-gap feature are expected to surface configuration documentation, and call out if the `watchNamespace` parameter is a part of it, along with usage example etc. Until a broad percentage of operator pacakges, especially those that don't support `AllNamespaces` mode, take action to make such documentation avaialble, a spike in bad installation is expected. - -**Installation Success Rate:** - -* **RBAC Validation Complexity:** Namespace-scoped installations require more complex RBAC validation to ensure the ServiceAccount has appropriate permissions for the target namespace. RBAC misconfigurations that work in AllNamespaces mode may fail in Single/OwnNamespace modes. - * Example: ServiceAccount has cluster-wide read permissions but lacks namespace-specific write permissions, causing installation to fail. -* **Bundle Compatibility Validation:** Additional validation layer to confirm bundles support the requested install mode. Bundles that only support AllNamespaces will fail when Single/OwnNamespace is requested. - * Example: Attempting to install a bundle with `watchNamespace: "test"` when the bundle CSV only declares support for AllNamespaces install mode. - -**Installation Time:** - -* **RBAC Generation Complexity:** Converting CSV `permission` to namespace-scoped Role/RoleBinding resources requires additional processing time. Complex operators with extensive permission requirements will see increased installation duration. - -**Operator Availability:** - -* **ServiceAccount Permission Dependencies:** Namespace-scoped operators depend on ServiceAccount permissions that may be modified by namespace administrators, creating additional failure points not present in cluster-scoped installations. - * Example: Namespace admin removes critical RoleBinding, causing operator to lose access to required resources. - -**Resource Utilization:** - -* **RBAC Resource Proliferation:** Each Single/OwnNamespace installation creates namespace-scoped RBAC resources instead of reusing cluster-scoped ones. Multiple operators in different namespaces will create duplicate Role/RoleBinding resources rather than sharing ClusterRole/ClusterRoleBinding resources. - * Example: Installing the same operator in 10 different namespaces creates 10 sets of Role/RoleBinding resources instead of 1 set of ClusterRole/ClusterRoleBinding resources. - -### Possible Failure Modes - -**Configuration Issues:** -- Invalid watchNamespace specification (DNS1123 validation failures) -- Target namespace doesn't exist or isn't accessible -- ServiceAccount lacks sufficient permissions for namespace access -- Bundle configuration does not include `watchNamespace` - -**Runtime Issues:** -- Operator deployed in install namespace but cannot access watch namespace -- RBAC resources incorrectly scoped for actual operator requirements -- Network policies preventing cross-namespace access when needed - -### OCP Teams Likely to be Called Upon in Case of Escalation - -1. OLM Team (primary) -2. OpenShift API Server Team -3. Networking Team (cross-namespace connectivity) -4. Authentication & Authorization Team (ServiceAccount/RBAC) -5. Layered Product Team - -## Support Procedures - -If there are problems with namespace-scoped operator installations: - -1. **Check Namespace Existence**: Confirm target watch namespace exists and is accessible -2. **Validate ServiceAccount Permissions**: Verify ServiceAccount has required permissions for target namespace -3. **Review Bundle Compatibility**: Confirm bundle CSV supports the requested install mode -4. **Examine RBAC Resources**: Check generated Role/RoleBinding resources are correctly scoped - -Common troubleshooting scenarios: -- **Installation Stuck**: Check namespace availability and ServiceAccount permissions -- **Operator Not Functioning**: Verify RBAC resources are correctly scoped to watch namespace -- **Permission Denied Errors**: Review ServiceAccount permissions and namespace access rights - -For persistent issues, administrators can: -- Disable feature gate to fall back to AllNamespaces mode -- Modify watchNamespace configuration to change install mode -- Scale down operator-controller to manually intervene if needed - -## Version Skew Strategy - -This feature is isolated to a the operator-controller component, managed by cluster-olm-operator. Version skew strategy is not required. - -### Component Interactions -- **operator-controller**: Must support the `NewOLMOwnSingleNamespace` feature gate -- **rukpak**: Uses existing conversion capabilities; no additional requirements -- **catalogs**: No changes required; - -### API Compatibility -- **ClusterExtension API**: Uses existing configuration schema; -- **Bundle Format**: Works with existing registry+v1 bundles without modification -- **Status Reporting**: Uses existing condition and status mechanisms - -### Deployment Considerations -- **Feature Gate Synchronization**: All operator-controller replicas must have consistent feature gate configuration -- **Configuration Validation**: API server validates configuration schema regardless of feature gate state -- **Runtime Behavior**: Feature gate only affects installation behavior, not API acceptance - -#### Feature Dependencies -- **Configuration Support**: This feature builds upon a ClusterExtension configuration infrastructure -- **RBAC Generation**: Leverages existing rukpak RBAC generation capabilities with enhanced scoping logic -- **Feature Gate Framework**: Uses established feature gate patterns for controlled rollout From 05d137e0053cbdd4899fc6cd5add867649d1e943 Mon Sep 17 00:00:00 2001 From: Per Goncalves da Silva Date: Tue, 11 Nov 2025 10:54:12 +0100 Subject: [PATCH 04/13] Address reviewer comments Signed-off-by: Per Goncalves da Silva --- enhancements/olm/runtime-bundle-configuration.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md index 47a5cc39d8..1c4c2af7b9 100644 --- a/enhancements/olm/runtime-bundle-configuration.md +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -24,13 +24,14 @@ definition for a registry+v1 bundle configuration schema. The configuration layer allows users to set bundle configuration whose structure is defined by the bundle authors through a configuration schema. It provides a single mechanism for configuring bundles independently of the underlying -bundle packaging format, which, while only the registry+v1 format is supported, will be expanded in the future to include -Helm, and registry+v2 formats. +bundle packaging format. Currently, only the registry+v1 format is supported. But, the Helm and registry+v2 formats +will be supported in the future. As registry+v1 bundles don't provide a bundle configuration schema, this enhancement proposes that the schema be derived by OLM by introspecting the bundle. The enhancement also proposes a first iteration of the registry+v1 bundle -configuration schema will that enable the installation of registry+v1 bundles with Single- and/or OwnNamespace install mode. -The registry+v1 bundle configuration schema will be expanded in future enhancement (while maintaining backwards compatibility). +configuration schema that will enable the installation of registry+v1 bundles with Single- and/or OwnNamespace install mode. +The registry+v1 bundle configuration schema will be expanded in a future enhancement to add support for configuration +compatible with OLMv0's `Subscription` `.spec.config` while maintaining backwards compatibility. ## Motivation From a2a99e8cd378fb3d9e9d3f04e97aee3f6ac66b40 Mon Sep 17 00:00:00 2001 From: Per Goncalves da Silva Date: Fri, 28 Nov 2025 12:38:55 +0100 Subject: [PATCH 05/13] Address reviewer comments Signed-off-by: Per Goncalves da Silva --- .../olm/runtime-bundle-configuration.md | 80 ++++++++++++------- 1 file changed, 51 insertions(+), 29 deletions(-) diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md index 1c4c2af7b9..b395760493 100644 --- a/enhancements/olm/runtime-bundle-configuration.md +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -139,10 +139,16 @@ issue, e.g.: - User provides configuration but the bundle does not support configuration - User does not provide required configuration fields - User provides configuration keys that are not existent -- Bundle does not provide a configuration schema +- User provides configuration but bundle does not provide a configuration schema ### registry+v1 Bundle Configuration Generation, Validation and Handling +registry+v1 bundles do not carry a configuration schema and expecting the schema to exist in the FBC would mean only +those catalogs that have been updated to carry this information would benefit from the changes proposed by this enhancement. +Therefore, the decision was made to have OLM derive the configuration by observing the bundle configuration. +It is possible that this logic moves to the catalog layer. But, since other bundle sources are envisioned (e.g. direct bundle install), +for a first take, the following changes will go in the runtime: + 1. Update the registry+v1 manifest provisioning layer to generate a configuration schema for the bundle 2. Update the registry+v1 manifest provisioning layer to validate user provided configuration against the generated schema returning any failures (and thereby aborting the operation) 3. Update the registry+v1 bundle rendering layer to accept the `watchNamespace` configuration for those bundles that support it and render the manifests appropriately @@ -150,7 +156,7 @@ issue, e.g.: ### Workflow Description The standard OLMv1 installation and upgrade workflows stay largely the same. Where it will differ is: -- users will need to consult documentation to understand how packages/bundles can be configured. +- users will need to consult the OpenShift documentation to understand how packages/bundles can be configured. - users will be able to specify inline bundle configuration on `.spec.config.inline`. - install/upgrade operations will be halted if the provided configuration does not meet the bundle provided configuration schema. Errors will be surfaced through the `Progressing` condition outlining the issue, e.g. `invalid bundle configuration: unknown key 'foo'`, or `invalid bundle configuration: missing required key 'bar'`. - users will be able to update configuration for currently installed content. @@ -213,7 +219,10 @@ First, one must determine the version to rollback to. If the ClusterExtension attempted an upgrade and is in a failed state, `.status.install` should report the version of the installed bundle. If the current version was successfully installed in a way that violates the user intent, e.g. there was a non-detectable breaking change in configuration behavior between bundle versions, then, at present, one needs -to consult the catalog and walk the upgrade graph backwards from the currently installed version. +to consult the catalog and walk the upgrade graph backwards from the currently installed version. +The [opm tool](https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/cli_tools/opm-cli) can +be used to help facilitate this task. The undocumented `opm alpha render-graph` command can also be used to provide a +visual representation of the upgrade graph for a particular package and channel. Once the target version is determined, a rollback can be done by updating the desired version in the target ClusterExtension and using the `SelfCertified` upgrade policy in the catalog source config, e.g.: @@ -269,14 +278,15 @@ type ClusterExtensionConfig struct { ConfigType ClusterExtensionConfigType `json:"configType"` // inline contains JSON or YAML values specified directly in the - // ClusterExtension. - // - // inline must be set if configType is 'Inline'. - // inline accepts arbitrary JSON/YAML objects. - // inline is validation at runtime against the schema provided by the bundle if a schema is provided. - // - // +kubebuilder:validation:Type=object - // +optional + // ClusterExtension. + // + // inline is used to specify arbitrary configuration values for the ClusterExtension. + // It must be set if configType is 'Inline' and must be a valid JSON/YAML object. + // The configuration values are validated at runtime against a JSON schema provided by the bundle. + // + // +kubebuilder:validation:Type=object + // +optional + // +unionMember Inline *apiextensionsv1.JSON `json:"inline,omitempty"` } ``` @@ -326,9 +336,14 @@ The OLMv1 runtime will operate over a bundle interface that will be common to th different formats differently for the purposes of life-cycling. It cares only about generating the required manifests, and organizing them in a way that it can lifecycle the application. As such, the interface should be generic and not leak underlying format specific details. The bundle rendering engine should consume opaque configuration, the bundle -interface should provide a configuration schema in JSON Schema format, and rendering will only take place if the -configuration **strictly** adheres to the provided schema, i.e. no additional keys, required fields are set, field value -constraints are observed, etc. +interface should provide a configuration schema as a [JSON Schema](https://json-schema.org/) format, +and rendering will only take place if the configuration **strictly** adheres to the provided schema, i.e. no additional +keys, required fields are set, field value constraints are observed, etc. + +The JSON Schema format is most widely used in its [draft-07](https://json-schema.org/draft-07) specification and boasts +wide coverage across tools, libraries and ecosystems. The latest specification, [2020-12](https://json-schema.org/draft/2020-12), +is slowly growing in popularity. Therefore, additional specification may also need to be supported in the future to meet +author needs. Taking this approach also means that the configuration schema should be treated like an API surface by the authors which should ensure it is not broken between minor and patch versions. Breaking changes detectable by the schema will @@ -413,11 +428,9 @@ Below are examples for what the JSON-Schemas may look like: "type": "object", "properties": { "watchNamespace": { - "type": ["string", "null"], - "format": "namespaceName", - "not": { - "const": "{{ .installNamespace }}" - } + "watchNamespace": { + "format": "notInstallNamespace", + "type": ["string", null], } } } @@ -431,16 +444,18 @@ Below are examples for what the JSON-Schemas may look like: "type": "object", "properties": { "watchNamespace": { - "format": "namespaceName", - "enum": ["{{ .installNamespace }}", null] + "format": "installNamespace", + "type": ["string", null], } } } ``` Notes: -- The value of `{{ .installNamespace }}` is replaced by the value of `.spec.namespace` in the `ClusterExtension`. - `namespaceName` is an internally defined format that validates namespace name inputs. It is not a standard format. +- `installNamespace` is an internally defined format that validates that the input is a valid namespace name and matches the install namespace. +- `notInstallNamespace` is an internally defined format that validates that the input is a valid namespace name and does not match the install namespace. +- The custom formats are used by the jsonschema library to validate the inputs. #### registry+v1 Bundle Renderer Changes @@ -528,12 +543,13 @@ which could be undesirable. With default configuration support, we could detect and stop the flow until the user explicitly adds the configuration selecting the desired behavior mode. *Mitigations*: -Design the configuration schema for the bundle in a way that it breaks if the default behavior changes. E.g. in the -hypothetical case above, the bundle configuration schema would have a required field `behaviorMode` that can only take -the value `Simple`. - -Note: While OLMv1 only has support for registry+v1 bundles, this is a limitation we can live with. However, this -support will be added by a future enhancement when we start to roll out Helm content support. +Require configuration from the user even when it feels superfluous. The configuration schema would always need to be +designed to allow for changes without breaking the API. The lack of default configuration would make the case above +a bit jarring for the user because they would need to specify a behavior mode even though there's only one to choose from. +While OLMv1 only has support for registry+v1 bundles, this is a limitation we can live with. That is, there are very few, +if any, bundles that _only_ support OwnNamespace and that would require users to specify the watchNamespace even though, + logically, it could only be the install namespace. +However, support default values will be added by a future enhancement when we start to roll out Helm content support. #### 6. Silent Switch in Default on Downgrade @@ -544,7 +560,6 @@ Which for registry+v1 bundles is `AllNamespaces` mode. *Mitigation*: This will need to be called out in documentation. - ### Drawbacks - Configuration validation happens at runtime and not at ingress-time by the kube apiserver @@ -643,6 +658,13 @@ Operators installed in Single/OwnNamespace modes have reduced blast radius compa | **Feature Proliferation** | Low | Clear documentation that this is for legacy compatibility only | | **Unintended Install Mode Changes** | High | Mandatory `watchNamespace` configuration for namespace-scoped bundles prevents automatic mode switching during upgrades | +#### 7. JSON Schema 2020-12 Specification Support + +The latest specification of the JSON Schema format is slowly gaining popularity though it does not quite have the same +tooling and library support as draft-07. In the future, we might want to add support for the latest specification if +there is sufficient demand for users. This would be an additive change to the architecture that would only require +the jsonschema library to understand the latest specification. + ## Test Plan ### ClusterExtension API Ingress Validation Tests From cefeef648bbea20f497026d9c77064e2ca52f876 Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Fri, 5 Dec 2025 13:04:59 -0500 Subject: [PATCH 06/13] Answer Per's calls --- enhancements/olm/runtime-bundle-configuration.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md index b395760493..182390b606 100644 --- a/enhancements/olm/runtime-bundle-configuration.md +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -19,8 +19,9 @@ tracking-link: # link to the tracking ticket (for example: Jira Feature or Epic ## Summary -This enhancement proposes the addition of a configuration layer to the ClusterExtension API surface and an initial -definition for a registry+v1 bundle configuration schema. +This enhancement proposes the addition of +1. A configuration layer to the ClusterExtension API surface. +2. An initial definition for a registry+v1 bundle configuration schema. The configuration layer allows users to set bundle configuration whose structure is defined by the bundle authors through a configuration schema. It provides a single mechanism for configuring bundles independently of the underlying @@ -44,7 +45,7 @@ OLMv1 also aims to support content packaged in different formats (i.e. registry+ any format specific concerns to be surfaced at the API level. Users care about content, and not its format. Therefore, a generic bundle configuration API surface is desired. -In OLMv0, registry+v1 bundles can be installed in one of four "install modes" used to configure the namespace(s) the +Once such configuration option was provided by OLMv0 for registry+v1 bundles that could be installed in one of four "install modes", used to configure the namespace(s) the operator should watch for their CR events: - AllNamespaces: the whole cluster - SingleNamespace: a single namespace that is _not_ the operator's namespace (i.e. the install namespace) @@ -99,7 +100,7 @@ rendered and installed without requiring me to modify my existing bundle format ### Goals -- Introduce the notion of bundle configuration into the ClusterExtension API surface in a format agnostic way s.t. it can also be used for other bundle formats such as Helm Charts +- Introduce the notion of bundle configuration into the ClusterExtension API surface in a format agnostic way such that it can also be used for other bundle formats such as Helm Charts - Enable support/rendering for registry+v1 bundles that only support SingleNamespace or OwnNamespace install modes - Define the registry+v1 bundle schema to support configuration of bundles with Single- and/or OwnNamespace install modes - Maintain backward compatibility with existing registry+v1 bundle content from OLM v0 catalogs @@ -113,7 +114,7 @@ rendered and installed without requiring me to modify my existing bundle format - Occlude secret information - Support for default configurations outside what can be set in a JSON-schema defined field default values - Support OLMv0 SubscriptionConfig-type behavior, enabling broader operator configuration compatibility, though this will come in the future -- Support the MultiNamespace install mode: this mode can severally impact api server resource utilization and cause cluster instability. Even in OLMv0 it is documented as unwise to use and that it will likely be removed in the future (OLMv1 is the future). +- Support the MultiNamespace install mode: this mode can severally impact api server resource utilization and cause cluster instability. Even in OLMv0 it is documented as unwise to use and that it will likely be removed in the future (OLMv1 being that future). ## Proposal @@ -139,7 +140,8 @@ issue, e.g.: - User provides configuration but the bundle does not support configuration - User does not provide required configuration fields - User provides configuration keys that are not existent -- User provides configuration but bundle does not provide a configuration schema +- User provides configuration but bundle does not provide a configuration schema - note that +while for registry+v1 bundles this is deemed a good level of restriction to ship the configuration feature with initially, for future bundle formats this restriction may be loosed (eg OLMv1 could allow users to provide configuration for "Helm bundles" without any configuration schema). Users will likely be required to express their intent to configure such bundles explicity and have OLM install anyway, possibly via a ClusterExtension API field (eg `dangerouslyAcceptBundlesWithoutConfigSchema`). Such considerations however are for future considerations. ### registry+v1 Bundle Configuration Generation, Validation and Handling @@ -156,7 +158,7 @@ for a first take, the following changes will go in the runtime: ### Workflow Description The standard OLMv1 installation and upgrade workflows stay largely the same. Where it will differ is: -- users will need to consult the OpenShift documentation to understand how packages/bundles can be configured. +- users will need to consult the [OpenShift documentation](https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html-single/extensions/index#olmv1-deploying-a-ce-in-a-specific-namespace_managing-ce) to understand how packages/bundles can be configured. The different configuration options for bundles given their install mode support will be enumerated with examples in the Openshift documentation. All future updates to the registry+v1 bundle configuration surface will also be enumerated in the Openshift docs, until we have a better way to surface the configuration schemas to the user for individual packages. - users will be able to specify inline bundle configuration on `.spec.config.inline`. - install/upgrade operations will be halted if the provided configuration does not meet the bundle provided configuration schema. Errors will be surfaced through the `Progressing` condition outlining the issue, e.g. `invalid bundle configuration: unknown key 'foo'`, or `invalid bundle configuration: missing required key 'bar'`. - users will be able to update configuration for currently installed content. From 20bed0489dd3d0d8d2928e773a52334eade7dca5 Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Fri, 5 Dec 2025 13:14:23 -0500 Subject: [PATCH 07/13] more details about json-schema-validator's custom opt-in formats --- .../olm/runtime-bundle-configuration.md | 33 ++++++++++++++----- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md index 182390b606..a3c58c4f8a 100644 --- a/enhancements/olm/runtime-bundle-configuration.md +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -430,8 +430,7 @@ Below are examples for what the JSON-Schemas may look like: "type": "object", "properties": { "watchNamespace": { - "watchNamespace": { - "format": "notInstallNamespace", + "format": "isNotInstallNamespace", "type": ["string", null], } } @@ -446,18 +445,36 @@ Below are examples for what the JSON-Schemas may look like: "type": "object", "properties": { "watchNamespace": { - "format": "installNamespace", + "format": "isInstallNamespace", "type": ["string", null], } } } ``` -Notes: -- `namespaceName` is an internally defined format that validates namespace name inputs. It is not a standard format. -- `installNamespace` is an internally defined format that validates that the input is a valid namespace name and matches the install namespace. -- `notInstallNamespace` is an internally defined format that validates that the input is a valid namespace name and does not match the install namespace. -- The custom formats are used by the jsonschema library to validate the inputs. +**Custom JSON Schema Formats for Bundle Authors:** + +OLM's JSON Schema validator will support several custom formats that bundle authors can opt-in to use in their configuration schemas: + +- `namespaceName`: Will validate that the input is a valid Kubernetes namespace name (follows DNS-1123 subdomain format). This will be useful for any configuration field that accepts a namespace name. +- `isInstallNamespace`: Will validate that the input is a valid namespace name and matches the ClusterExtension's install namespace (`.spec.namespace`). Bundle authors can use this format to ensure a configuration value must be the install namespace. +- `isNotInstallNamespace`: Will validate that the input is a valid namespace name and does not match the install namespace. Bundle authors can use this format to ensure a configuration value must be different from the install namespace. + +These custom formats will not be part of the standard JSON Schema specification but will be provided by OLM to help bundle authors create more robust configuration schemas. Bundle authors who want to use these formats should include them in their schema's `format` field. + +Example usage by bundle authors: +```json +{ + "type": "object", + "properties": { + "targetNamespace": { + "type": "string", + "format": "isNotInstallNamespace", + "description": "The namespace to watch (must be different from install namespace)" + } + } +} +``` #### registry+v1 Bundle Renderer Changes From 6f3dfa43bf0cb5f68dd3415199c02e8b0d4e61b1 Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Fri, 5 Dec 2025 13:19:33 -0500 Subject: [PATCH 08/13] add a little more details about documenting configuration options --- enhancements/olm/runtime-bundle-configuration.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md index a3c58c4f8a..b945ee28ab 100644 --- a/enhancements/olm/runtime-bundle-configuration.md +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -158,7 +158,11 @@ for a first take, the following changes will go in the runtime: ### Workflow Description The standard OLMv1 installation and upgrade workflows stay largely the same. Where it will differ is: -- users will need to consult the [OpenShift documentation](https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html-single/extensions/index#olmv1-deploying-a-ce-in-a-specific-namespace_managing-ce) to understand how packages/bundles can be configured. The different configuration options for bundles given their install mode support will be enumerated with examples in the Openshift documentation. All future updates to the registry+v1 bundle configuration surface will also be enumerated in the Openshift docs, until we have a better way to surface the configuration schemas to the user for individual packages. +- users will need to consult the [OpenShift documentation](https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html-single/extensions/index#olmv1-deploying-a-ce-in-a-specific-namespace_managing-ce) to understand how packages/bundles can be configured. The OpenShift documentation will include a capability matrix (derived from the table in the "registry+v1 Configuration Schema" section below) that maps bundle install mode support to configuration requirements, specifically: + - Whether the `watchNamespace` configuration field is required or optional for a given bundle based on its install mode capabilities + - Valid values and constraints for the `watchNamespace` field (e.g., must equal install namespace, must differ from install namespace, or can be any namespace) + - Practical examples showing how to configure bundles for different install mode scenarios + - The different configuration options for bundles given their install mode support will be enumerated with examples. All future updates to the registry+v1 bundle configuration surface will also be enumerated in the OpenShift docs, until there is a better way to surface the configuration schemas to users for individual packages. - users will be able to specify inline bundle configuration on `.spec.config.inline`. - install/upgrade operations will be halted if the provided configuration does not meet the bundle provided configuration schema. Errors will be surfaced through the `Progressing` condition outlining the issue, e.g. `invalid bundle configuration: unknown key 'foo'`, or `invalid bundle configuration: missing required key 'bar'`. - users will be able to update configuration for currently installed content. From dedbf30c9075f6b875de3634bc61024f7ec63eb7 Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Fri, 5 Dec 2025 13:26:40 -0500 Subject: [PATCH 09/13] Add kubebuilder annotation --- enhancements/olm/runtime-bundle-configuration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md index b945ee28ab..f4a8a89337 100644 --- a/enhancements/olm/runtime-bundle-configuration.md +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -291,6 +291,7 @@ type ClusterExtensionConfig struct { // The configuration values are validated at runtime against a JSON schema provided by the bundle. // // +kubebuilder:validation:Type=object + // +kubebuilder:validation:MinProperties=1 // +optional // +unionMember Inline *apiextensionsv1.JSON `json:"inline,omitempty"` From 7f225d0de782c026503a85298a21c7e5aee91a05 Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Fri, 5 Dec 2025 13:35:40 -0500 Subject: [PATCH 10/13] add more details about json schema specification support --- enhancements/olm/runtime-bundle-configuration.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md index f4a8a89337..fbc946c5a1 100644 --- a/enhancements/olm/runtime-bundle-configuration.md +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -360,6 +360,21 @@ Such issues will be treated as bugs for the content author as opposed to OLM, ex whose schema is controlled by the OLM team. The OLM team will ensure there are no breaking changes throughout the development of the registry+v1 configuration schema. +**Handling Breaking Schema Changes:** + +If a change in the JSON Schema specification forces a breaking change in the configuration API (for future bundle formats that provide their own schemas), bundle authors have two options: + +1. **Continue with the current schema version**: Maintain backward compatibility by not adopting the new schema specification version that would cause breaking changes. + +2. **Accept breaking changes and handle appropriately**: If breaking changes are necessary, authors should handle this like any other breaking API change: + - Do not carry upgrade edges between breaking versions in the catalog + - Document the migration to the breaking version, instructing users on how to modify their configuration successfully for the new schema + - Consider this a major version change requiring explicit user action + +**Unsupported JSON Schema Specifications:** + +If OLM encounters a bundle that publishes a configuration schema using an unsupported JSON Schema specification, the bundle will be deemed invalid and an error will be surfaced to the user through the ClusterExtension status. If support for a specification needs to be dropped, the deprecation will follow standard OpenShift deprecation conventions and provide authors sufficient time to migrate to a more recent supported specification. In the event that a bundle is still installed using an unsupported specification version across an OLM upgrade, the same error will be surfaced to the user and upgrades and reconfigurations will not be possible until manual intervention occurs (e.g., manual migration of the configuration and bundle to a supported specification version). + Any validation errors will be surfaced to the user via the `Progressing` condition with a clear message, e.g.: - invalid bundle configuration: unknown key 'foo' - invalid bundle configuration: invalid value for field 'bar' must be less than 10 but got 11 From 29851eeb046e800ed99e9f21ca7b042ffa334b4b Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Fri, 5 Dec 2025 13:38:20 -0500 Subject: [PATCH 11/13] remove feature gate talk from troubleshooting section --- enhancements/olm/runtime-bundle-configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md index fbc946c5a1..9f6f7e5d73 100644 --- a/enhancements/olm/runtime-bundle-configuration.md +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -829,7 +829,8 @@ Common troubleshooting scenarios: - **Permission Denied Errors**: Review ServiceAccount permissions and namespace access rights For persistent issues, administrators can: -- Disable feature gate to fall back to AllNamespaces mode +- If the bundle supports AllNamespaces mode: update the configuration by removing the watchNamespace config to fall back to AllNamespaces mode +- If AllNamespaces is not supported: remove the extension and contact the bundle author as this likely indicates a problem with the content - Modify watchNamespace configuration to change install mode - Scale down operator-controller to manually intervene if needed From ce7f31615d0e3f34343d16c74db232e64c40bc1b Mon Sep 17 00:00:00 2001 From: Anik Bhattacharjee Date: Wed, 17 Dec 2025 16:32:00 +0530 Subject: [PATCH 12/13] address more review comments --- .../olm/runtime-bundle-configuration.md | 103 ++++++++++-------- 1 file changed, 57 insertions(+), 46 deletions(-) diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md index 9f6f7e5d73..6e5d280e79 100644 --- a/enhancements/olm/runtime-bundle-configuration.md +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -310,6 +310,7 @@ spec: serviceAccount: name: argocd-installer config: + configType: Inline inline: watchNamespace: argocd-pipelines source: @@ -342,15 +343,18 @@ No specific considerations needed The OLMv1 runtime will operate over a bundle interface that will be common to the supported bundle formats. It won't treat different formats differently for the purposes of life-cycling. It cares only about generating the required manifests, and organizing them in a way that it can lifecycle the application. As such, the interface should be generic and not -leak underlying format specific details. The bundle rendering engine should consume opaque configuration, the bundle -interface should provide a configuration schema as a [JSON Schema](https://json-schema.org/) format, -and rendering will only take place if the configuration **strictly** adheres to the provided schema, i.e. no additional -keys, required fields are set, field value constraints are observed, etc. - -The JSON Schema format is most widely used in its [draft-07](https://json-schema.org/draft-07) specification and boasts -wide coverage across tools, libraries and ecosystems. The latest specification, [2020-12](https://json-schema.org/draft/2020-12), -is slowly growing in popularity. Therefore, additional specification may also need to be supported in the future to meet -author needs. +leak underlying format specific details. The bundle rendering engine should consume opaque configuration, and each bundle +format will provide a configuration schema in whatever format is appropriate for that bundle type. OLMv1 will use the +appropriate validation libraries for the schema format provided by the bundle format (e.g., JSON Schema validators for +JSON Schema, CUE validators for CUE, Rego evaluators for Rego, etc.). Rendering will only take place if the configuration +**strictly** adheres to the provided schema, i.e. no additional keys, required fields are set, field value constraints +are observed, etc. + +For bundle formats that use JSON Schema (such as registry+v1 bundles as described in this enhancement), the JSON Schema +format is most widely used in its [draft-07](https://json-schema.org/draft-07) specification and boasts wide coverage +across tools, libraries and ecosystems. The latest specification, [2020-12](https://json-schema.org/draft/2020-12), is +slowly growing in popularity. Therefore, additional JSON Schema specifications may also need to be supported in the future +to meet author needs. Taking this approach also means that the configuration schema should be treated like an API surface by the authors which should ensure it is not broken between minor and patch versions. Breaking changes detectable by the schema will @@ -409,80 +413,83 @@ Given the tight scope and the small configuration surface, the validation may be the actual generation of a JSON-Schema. However, once this surface expands this will be the direction we'll take and there should be no difference in behavior beyond the possible wording and structure of error messages. -Below are examples for what the JSON-Schemas may look like: +Below are examples for what the JSON-Schemas may look like. Since OLM generates these schemas at runtime for registry+v1 bundles, it knows the install namespace from the ClusterExtension's `.spec.namespace` field and can directly embed namespace constraints in the schema using standard JSON Schema constructs: -**watchNamespace field required** +**watchNamespace field required (can be any namespace)** -``` +```json { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "watchNamespace": { "type": "string", - "format": "namespaceName", + "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" } }, "required": ["watchNamespace"] } ``` -**watchNamespace field optional** +**watchNamespace field optional (can be any namespace)** -``` +```json { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "watchNamespace": { - "type": ["string", null], - "format": "namespaceName", + "type": ["string", "null"], + "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" } - }, + } } ``` -**watchNamespace cannot be the install namespace** +**watchNamespace cannot be the install namespace** (example where install namespace is "argocd") -``` +```json { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "watchNamespace": { - "format": "isNotInstallNamespace", - "type": ["string", null], + "type": ["string", "null"], + "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", + "not": { + "const": "argocd" + } } } } ``` -**watchNamespace is optional and can only be the install namespace** +**watchNamespace is optional and can only be the install namespace** (example where install namespace is "argocd") -``` +```json { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "watchNamespace": { - "format": "isInstallNamespace", - "type": ["string", null], + "type": ["string", "null"], + "enum": ["argocd", null] } } } ``` -**Custom JSON Schema Formats for Bundle Authors:** +**Custom JSON Schema Formats for Future Bundle Formats:** -OLM's JSON Schema validator will support several custom formats that bundle authors can opt-in to use in their configuration schemas: +For future bundle formats where bundle authors provide their own configuration schemas (such as Helm charts with values.schema.json or registry+v2 bundles), OLM may provide custom JSON Schema format validators to help bundle authors create more robust configuration schemas: -- `namespaceName`: Will validate that the input is a valid Kubernetes namespace name (follows DNS-1123 subdomain format). This will be useful for any configuration field that accepts a namespace name. -- `isInstallNamespace`: Will validate that the input is a valid namespace name and matches the ClusterExtension's install namespace (`.spec.namespace`). Bundle authors can use this format to ensure a configuration value must be the install namespace. -- `isNotInstallNamespace`: Will validate that the input is a valid namespace name and does not match the install namespace. Bundle authors can use this format to ensure a configuration value must be different from the install namespace. +- `namespaceName`: Would validate that the input is a valid Kubernetes namespace name (follows DNS-1123 subdomain format). This would be useful for any configuration field that accepts a namespace name. +- `isInstallNamespace`: Would validate that the input is a valid namespace name and matches the ClusterExtension's install namespace (`.spec.namespace`). Bundle authors could use this format to ensure a configuration value must be the install namespace. +- `isNotInstallNamespace`: Would validate that the input is a valid namespace name and does not match the install namespace. Bundle authors could use this format to ensure a configuration value must be different from the install namespace. -These custom formats will not be part of the standard JSON Schema specification but will be provided by OLM to help bundle authors create more robust configuration schemas. Bundle authors who want to use these formats should include them in their schema's `format` field. +These custom formats would not be part of the standard JSON Schema specification but would be provided by OLM as helpers for bundle authors. Whether to implement these helpers will be decided when bundle formats that support author-provided schemas are implemented. -Example usage by bundle authors: +Example of potential future usage by bundle authors: ```json { "type": "object", @@ -494,19 +501,23 @@ Example usage by bundle authors: } } } -``` +``` + +**Note**: For the registry+v1 bundle format described in this enhancement, OLM generates the schema at runtime and uses standard JSON Schema constructs directly (as shown in the examples above), so these custom formats are not used. #### registry+v1 Bundle Renderer Changes -**Specific Resource Changes:** -- **ClusterRole/ClusterRoleBinding**: `clusterPermissions` entries in the `ClusterServiceVersion` are always created as `ClusterRole` and `ClusterRoleBinding` resources regardless of install mode -- **Role/RoleBinding**: `permissions` entries in the `ClusterServiceVersion` are created as `Role` and `RoleBinding` resources in the watch namespace. For AllNamespaces mode, these are instead created as `ClusterRole` and `ClusterRoleBinding` resources -- **Operator Configuration**: `olm.targetNamespaces` annotation gets set in the operator deployment's pod template, instructing the operator how to configure itself for the target namespace scope +Currently, OLM only supports AllNamespaces mode and promotes all `permissions` entries from the ClusterServiceVersion to `ClusterRole` and `ClusterRoleBinding` resources. This enhancement introduces namespace-scoped RBAC generation when `watchNamespace` is configured. + +**Changes to RBAC Resource Generation:** + +- **ClusterRole/ClusterRoleBinding**: `clusterPermissions` entries in the `ClusterServiceVersion` will continue to be created as `ClusterRole` and `ClusterRoleBinding` resources regardless of install mode + +- **Role/RoleBinding**: `permissions` entries in the `ClusterServiceVersion` will be handled differently based on configuration: + - **When `watchNamespace` is configured** (Single/OwnNamespace modes): Create `Role` and `RoleBinding` resources in the watch namespace (this is the new behavior introduced by this enhancement) + - **When `watchNamespace` is not configured** (AllNamespaces mode): Continue current behavior of promoting to `ClusterRole` and `ClusterRoleBinding` resources -For the `AllNamespaces` mode, the namespaced RBAC specified in the `ClusterServiceVersion` gets rolled up into the -generated `ClusterRole`. For `Single/OwnNamespace` the namespaced RBAC get placed in a role in the `watchNamespace` -and the `Deployment` pod template is updated to set the `olm.targetNamespaces` label to the `watchNamespace`. This tells -the operator how to configure itself. +- **Operator Configuration**: The `olm.targetNamespaces` annotation will be set in the operator deployment's pod template to the value of `watchNamespace`, instructing the operator how to configure itself for the target namespace scope #### Install Mode Upgrade Behavior Edge Case @@ -535,7 +546,7 @@ Unknown keys in configuration can have undesired effects especially between bund that is not part of the schema in one version but present in a subsequent version of the bundle is present, this could violate user intent and potentially place the cluster in an undesired state. -*Mitigation*: Strict schema validation is applied. Unknown keys cannot be present in the supplied configuration. +*Mitigation*: For registry+v1 bundles (covered by this enhancement), OLM generates the configuration schemas and will ensure they reject unknown keys by omitting or setting `additionalProperties: false`. For future bundle formats where bundle authors provide their own schemas, whether unknown keys are rejected depends on how the author defines their schema. OLM will validate configuration strictly according to the provided schema. Documentation will encourage bundle authors to use strict schemas that reject unknown properties to prevent unintended configuration drift. #### 2. Configuration Changes in Detectably Breaking Ways @@ -560,7 +571,7 @@ Note: it's possible that in the future users can override this behavior if they Often times, users might need to supply an application with secret/privileged information such as passwords, or api keys. With the current inline approach, if this information *must* be entered in as plain text (as opposed to as a reference to an existing secret, for instance), the privileged information would be reveled to anyone that can read -the ClusterExtension. It could also cause replication headaches as the privileged information might already exist in a +the ClusterExtension, or has access to etcd's data store or any backup of etcd's data store. It could also cause replication headaches as the privileged information might already exist in a Secret somewhere, and if the information changes, it would need to be manually updated. *Mitigations*: @@ -597,7 +608,7 @@ bundles that were installed in `Single-` or `OwnNamespace` mode, if they also su Because the configuration won't be applied to the bundle, it will be installed with its default configuration. Which for registry+v1 bundles is `AllNamespaces` mode. -*Mitigation*: This will need to be called out in documentation. +*Mitigation*: Cluster downgrades are not a supported scenario. If a downgrade occurs (unsupported scenario), administrators should be aware that bundles previously configured with `watchNamespace` may revert to AllNamespaces mode. Administrators would need to manually verify operator permissions and behavior after any unsupported downgrade operation. ### Drawbacks @@ -749,7 +760,7 @@ configuration, e.g.: a bundle that supports `AllNamespaces`, `SingleNamespace` i reinstalled as `AllNamespaces` upon downgrade due to the configuration not being applied. ### Version Compatibility -- **Minimum Version**: Requires OpenShift 4.20+ +- **Minimum Version**: Requires OpenShift 4.22+ - **Configuration Schema**: Uses existing ClusterExtension configuration schema for forward compatibility ## Operational Aspects of API Extensions From 64141656e505ed8d97ab0c611dd0daa87ac3b2c6 Mon Sep 17 00:00:00 2001 From: Per Goncalves da Silva Date: Wed, 17 Dec 2025 14:24:49 +0100 Subject: [PATCH 13/13] updates Signed-off-by: Per Goncalves da Silva --- .../olm/runtime-bundle-configuration.md | 52 ++++--------------- 1 file changed, 11 insertions(+), 41 deletions(-) diff --git a/enhancements/olm/runtime-bundle-configuration.md b/enhancements/olm/runtime-bundle-configuration.md index 6e5d280e79..a392109b94 100644 --- a/enhancements/olm/runtime-bundle-configuration.md +++ b/enhancements/olm/runtime-bundle-configuration.md @@ -141,7 +141,7 @@ issue, e.g.: - User does not provide required configuration fields - User provides configuration keys that are not existent - User provides configuration but bundle does not provide a configuration schema - note that -while for registry+v1 bundles this is deemed a good level of restriction to ship the configuration feature with initially, for future bundle formats this restriction may be loosed (eg OLMv1 could allow users to provide configuration for "Helm bundles" without any configuration schema). Users will likely be required to express their intent to configure such bundles explicity and have OLM install anyway, possibly via a ClusterExtension API field (eg `dangerouslyAcceptBundlesWithoutConfigSchema`). Such considerations however are for future considerations. +while for registry+v1 bundles this is deemed a good level of restriction to ship the configuration feature with initially, for future bundle formats this restriction may be loosed (eg OLMv1 could allow users to provide configuration for "Helm bundles" without any configuration schema). Users will likely be required to express their intent to configure such bundles explicity and have OLM install anyway, possibly via a ClusterExtension API field within the `.spec.install` stanza (eg `dangerouslyAcceptBundlesWithoutConfigSchema`). Such considerations however are for future considerations. ### registry+v1 Bundle Configuration Generation, Validation and Handling @@ -680,34 +680,6 @@ OLMv1 will eventually add the next iteration of registry+v2. Author provided con In the future, we'd like an easy way to surface the bundle configuration schema to users via the console to help users understand the configuration affordances for the different catalog packages, and bundles. -### 7. Operational risks of Single/OwnNamespace mode installations - -Because we are enabling namespace-scoped operator installations, there are operational implications that could impact cluster management. These risks are mitigated by: - -- **RBAC Misconfiguration**: Install mode validation ensures operators only receive permissions appropriate for their scope -- **Namespace Dependency**: Clear error messages when target namespaces don't exist or aren't accessible -- **Migration Complexity**: Comprehensive documentation and examples for transitioning between install modes -- **Permission Escalation**: ServiceAccount validation ensures adequate permissions without over-privileging -- **Unintended Install Mode Changes**: Requiring explicit `watchNamespace` configuration for namespace-scoped bundles prevents automatic permission scope escalation when bundle upgrades add new install mode capabilities - -Currently, admins control the scope of operator installations through ClusterExtension RBAC. This enhancement adds namespace-level controls while maintaining existing security boundaries. - -The feature is alpha and feature-gated, allowing administrators to: -- Control adoption timeline through feature gate management -- Test namespace-scoped installations in non-production environments -- Gradually migrate from AllNamespaces to more targeted install modes - -Operators installed in Single/OwnNamespace modes have reduced blast radius compared to AllNamespaces installations, potentially improving cluster security posture. - -| Risk | Impact | Mitigation | -|-------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------| -| **Increased Complexity** | Medium | Feature is alpha and feature-gated; clear documentation emphasizes this is transitional | -| **RBAC Misconfiguration** | High | Comprehensive validation and clear error messages; documentation provides RBAC examples | -| **Installation Failures** | Medium | Detailed preflight checks and validation; clear error reporting | -| **Security Boundaries** | Medium | Explicit validation of namespace permissions; RBAC properly scoped | -| **Feature Proliferation** | Low | Clear documentation that this is for legacy compatibility only | -| **Unintended Install Mode Changes** | High | Mandatory `watchNamespace` configuration for namespace-scoped bundles prevents automatic mode switching during upgrades | - #### 7. JSON Schema 2020-12 Specification Support The latest specification of the JSON Schema format is slowly gaining popularity though it does not quite have the same @@ -780,26 +752,24 @@ reinstalled as `AllNamespaces` upon downgrade due to the configuration not being - Permission debugging requires understanding of install mode impact on RBAC scope - Security auditing must consider namespace-level vs cluster-level permission grants +#### Operational risks of Single/OwnNamespace mode installations + +Because we are enabling namespace-scoped operator installations, there are operational implications that could impact cluster management. The following risks and mitigations are identified: + +- **RBAC Misconfiguration**: Install mode validation ensures operators only receive permissions appropriate for their scope +- **Namespace Dependency**: Clear error messages when target namespaces don't exist or aren't accessible when there are bundle generated resources that need to be applied to the target namespace +- **Permission Escalation**: ServiceAccount validation ensures adequate permissions without over-privileging +- **Unintended Install Mode Changes After Upgrade**: Requiring explicit `watchNamespace` configuration for namespace-scoped bundles prevents automatic permission scope escalation when bundle upgrades add new install mode capabilities + ### Impact on Existing SLIs -With the removal of the install mode concept in OLMv1, operator packages that want to continue to use this stop-gap feature are expected to surface configuration documentation, and call out if the `watchNamespace` parameter is a part of it, along with usage examples etc. Until a broad percentage of operator packages, especially those that don't support `AllNamespaces` mode, take action to make such documentation available, a spike in bad installations is expected. +With the removal of the install mode concept in OLMv1, operator packages that want to continue to use this stop-gap feature are expected to surface configuration documentation, and call out if the `watchNamespace` parameter is a part of it, along with usage examples etc. Until a broad percentage of operator packages, especially those that don't support `AllNamespaces` mode, take action to make such documentation available, a spike in bad installations could be expected. **Installation Success Rate:** -* **RBAC Validation Complexity:** Namespace-scoped installations require more complex RBAC validation to ensure the ServiceAccount has appropriate permissions for the target namespace. RBAC misconfigurations that work in AllNamespaces mode may fail in Single/OwnNamespace modes. - * Example: ServiceAccount has cluster-wide read permissions but lacks namespace-specific write permissions, causing installation to fail. * **Bundle Compatibility Validation:** Additional validation layer to confirm bundles support the requested install mode. Bundles that only support AllNamespaces will fail when Single/OwnNamespace is requested. * Example: Attempting to install a bundle with `watchNamespace: "test"` when the bundle CSV only declares support for AllNamespaces install mode. -**Installation Time:** - -* **RBAC Generation Complexity:** Converting CSV `permission` to namespace-scoped Role/RoleBinding resources requires additional processing time. Complex operators with extensive permission requirements will see increased installation duration. - -**Operator Availability:** - -* **ServiceAccount Permission Dependencies:** Namespace-scoped operators depend on ServiceAccount permissions that may be modified by namespace administrators, creating additional failure points not present in cluster-scoped installations. - * Example: Namespace admin removes critical RoleBinding, causing operator to lose access to required resources. - ### Possible Failure Modes - Invalid bundle configuration