(rukpak) extend bundle renderer to accept config opts

Introduce BundleConfig that contains InstallConfig and DeploymentConfig.

Author: anik120

.DS_Store

@@ -0,0 +1,191 @@
+# **Brief**​: Configuration Support 
+
+# Configurable Package Installation for OLMv1
+
+						
+
+**Author Name(s)**​: [Brett Tofel](mailto:[email protected]) [Per Goncalves da Silva](mailto:[email protected])  
+**Subproject(s)**​:  
+**Author Date**​: July 14, 2025  
+**Due Date**​: **July 28, 2025**  
+**Expected Completion Quarter**: 2025/Q3  
+**Status:**​Under Review  
+**Community Consensus:**​TBD
+
+##  Problem Statement:
+
+Bridging the gap with configuration paradigms found in Helm and the SubscriptionConfig of OLMv0.
+
+Operators, designed to manage complex applications on Kubernetes, often require specific configurations beyond a basic installation. In the current OLMv1 (Technology Preview) framework, as represented by the ClusterExtension API, there isn't a direct and standardized mechanism for users to pass custom configuration parameters to the installed packages. This limitation forces users to employ external configuration methods or rely on custom operator logic, reducing flexibility and hindering streamlined, GitOps-friendly deployments. This contrasts with established patterns like Helm-based charts, which readily accept values files for configuration, and the existing SubscriptionConfig capability in OLMv0.
+
+The primary goal is to empower users to configure the packages they install through OLMv1 by introducing a native, declarative configuration interface in the ClusterExtension API. This will ensure:
+
+* Enhanced Flexibility: Operators can be deployed and customized to fit diverse environmental and application requirements.  
+* Declarative Control: Configuration is managed as part of the ClusterExtension object, supporting GitOps workflows and consistent state management.
+
+**Link to RFC(s)**​: 
+
+* Work for this just addressing registry+v1 bundles: [RFC​: Config -\> registry+v1 bundle config](https://docs.google.com/document/d/1rmcT8tXcezjq0Iy3Cde097Y8ZaCgUXhEgiuyfv1vXUI/)
+
+**Link To Issue(s)/PR(s)/Discussion(s)**​:
+
+* \<Work Tracking Link\>
+
+##  Abstract*:*
+
+We propose adding a new, optional field: `.spec.config` to the `ClusterExtension` object in OLMv1. This field would typically be a generic structure like `interface{}` or `map[string]interface{}` to allow for diverse configuration formats. The field would be validated by OLM against a schema provided by the bundle and used to configure the final bundle manifests applied to the cluster.
+
+# Personas Impacted
+
+| Consumers | Yes/No | Producers | Yes/No |
+| :---- | :---- | :---- | :---- |
+| Cluster Admin | No | Extension Author | Yes |
+| Cluster Extension Admin  | Yes | Contribution Curator | No |
+| Cluster Catalog Admin | No | Catalog Curator | Yes |
+| Cluster Monitor | No | Catalog Manipulator | No |
+
+# **Summary Of Work**
+
+This project aims to introduce a render-time configuration mechanism for current and future bundle formats OLMv1 supports via ClusterExtension.spec.config, consumed only during manifest generation (no runtime configuration).
+
+Specifically, the goal is to implement an optional `.spec.config f`ield within the `ClusterExtension` object, empowering users to pass custom configuration parameters directly, thus enhancing flexibility, ease of use, and alignment with GitOps workflows.
+
+**Business Need**: OLMv1 lacks built-in render-time configuration akin to Helm values or OLMv0’s SubscriptionConfig, forcing users into external scripts or custom operator logic
+
+A built-in configuration system addresses this gap, simplifying operator deployment and enabling more precise, consistent resource management.
+
+**Benefits**:
+
+* Enhanced Flexibility: Users can tailor operator installations directly through the ClusterExtension specification.  
+* Declarative Configuration: Seamless integration with GitOps pipelines, improving automation and state management.  
+* Improved Usability: Clear and structured configuration reduces user errors and simplifies deployments.  
+* Secret-backed configuration: allow referencing Kubernetes Secrets in spec.config for sensitive values.  
+* Alignment with Community Standards: Brings OLMv1 closer to established configuration patterns seen in Helm and OLMv0, promoting familiarity and adoption.  
+* Registry+v1 feature parity: mirror OLMv0 render-time config for registry+v1 bundles, smoothing migration to OLMv1.
+
+**Persona Engagement**:
+
+* Extension Author: Defines and maintains OpenAPI schemas that outline configurable options for operators, improving the clarity and usability of their extensions.  
+* Cluster Extension Admin: Directly utilizes the .spec.config field to deploy and manage customized operator configurations efficiently, streamlining operational workflows.
+
+**Personas:** Extension Author, Cluster Extension Admin
+
+## **Solution Design and Architecture**
+
+### Scope
+
+* .spec.config is consumed **only at rendering time**. Bundles use the values to produce the final set of manifests to be applied to the cluster; OLM does not persist config beyond creation.
+
+* Supports both **registry+v1 bundles now and Helm charts later**, rendering at install and upgrade.
+
+* registry+v1 bundle configuration **matches OLMv0 behavior**
+
+* Given the homogenous nature of the format, registry+v1 configuration schemas will be generated and therefore every registry+v1 bundle will automatically have a configuration schema. In contrast, Helm charts may or may not include a values schema, and the structure of the values file varies from chart to chart. Configuration will be validated for bundles that provide a configuration schema. Pipeline validation may require a schema, but the API should accept bundles without one and surface template errors at render time
+
+* Configuration is able to reference values held by Secrets in any namespace of the cluster
+
+* Configuration can be defined outside, and referenced by, the ClusterExtension API in one or more ConfigMap and/or Secret resources. The final configuration is a merge of the different inline and references configuration fragments
+
+### Core Mechanism: Schema Validation and Renderer Adaptation
+
+* **OpenAPI Schema Validation**: The content of the `.spec.config` field must be validated against an OpenAPI schema that the operator's bundle makes available should one be provided. This ensures that only well-formed and expected configurations are applied, preventing misconfigurations and enhancing cluster stability.  
+* **`registry+v1` Bundle Integration**: For operators distributed via the `registry+v1` bundle format, the OLMv1 renderer component will need to be updated to:  
+  1. Dynamically define the validation OpenAPI schema for the bundle based on its install mode support (i.e. if only AllNamespaces install mode is supported, no watchNamespaces field is required). All registry+v1 bundles should support [SubscriptionConfig](https://github.com/operator-framework/api/blob/master/pkg/operators/v1alpha1/subscription_types.go#L42) fields.   
+  2. Apply the values from `ClusterExtension.spec.config` during the instantiation of the operator's resources. This process would involve parameterizing the operator's deployment manifests (defined in the install strategy of the `ClusterServiceVersion`) using the provided configuration, much like a Helm template rendering process.
+
+### Analogies and Precedent
+
+* **Helm values files**: This feature directly parallels the widely adopted practice in the Helm ecosystem where users provide a values.yaml file to customize chart deployments. The `.spec.config` would serve a similar purpose for OLM-managed operators  
+* **OLMv0 `SubscriptionConfig`**: OLMv0 already includes a `SubscriptionConfig` object to define settings for an Operator, and this new OLMv1 feature aims to provide comparable functionality for `ClusterExtension.`
+
+### Challenges and Considerations
+
+Implementing this feature requires careful consideration of several factors:
+
+* **Registry+v1 Configuration Schema**: Define the configuration schema for registry+v1 bundles. The schema will be dynamic depending on ClusterServiceVersion parameters such as install mode support, but should always include the fields defined by OLMv0’s Subscription .spec.config  
+* **Renderer Complexity**: Extend the renderer to merge spec.config at install and upgrade only, rely on Progressing=true with backoff on failure, and ensure core resource types (Deployments, ConfigMaps, Secrets) render correctly  
+* **Upgrade Safety and Configuration Compatibility**: Operator upgrades could introduce breaking schema changes to configuration schemas. On invalid config syntax, do not create a new ClusterExtensionRevision; leave the last successful revision in place and surface failure via Progressing=true. More generally, invalid configuration should never impact currently installed revision.   
+* **Security Implications**: Arbitrary configuration that can reference data contained in Secret resources could potentially lead to security issues such as privileged data leaks, or deployments that could put the system in a compromised state (e.g. absurd resource requests). At this level of the stack, OLM will pass the values given to it without plausibility or other checks. For now, we’ll rely on human-in-the-loop and policy to do these kinds of checks at the revision level.  
+* **Backward Compatibility**: Ensure that existing `registry+v1` bundles, which do not yet specify a .spec.config schema, continue to install and function correctly without disruption.  
+* **Error Reporting**: Clear, actionable error messages are critical when configuration validation fails or when the renderer encounters issues applying the configuration. This improves the debugging experience for users.
+
+### Integration with Helm
+
+While the immediate ask focuses on `registry+v1` bundles, this `.spec.config` interface could logically be extended to support Helm-based operators. If OLMv1 were to directly consume Helm charts, the `.spec.config` could serve as the direct equivalent of a Helm values.yaml file. This would unify the configuration experience across different operator packaging formats under the `ClusterExtension` API, aligning with ongoing OLM initiatives for Helm integration.
+
+We would accept arbitrary `.spec.config;` if a `values.schema.json` is present, validate against it. If absent, render and let template errors surface.
+
+# **Stakeholders**
+
+## Pipeline Impact
+
+Operator pipelines that want to ensure high-quality submissions need to check for presence of schemas in bundle formats that need them.
+
+## Documentation Impact
+
+Documentation will need to be updated to cover the ClusterExtension API changes, instruct users on how to discover and use a bundle’s configuration surface, and on troubleshoot value validation issues such as breaking changes in the configuration schema between bundle versions. 
+
+## Verification Impact
+
+Additional testing will be required to help verify that configurations are adequately applied to the bundle manifests applied to the cluster, ensure errors are appropriately surfaced not only in terms of configuration validation but semantically valid configurations that might not be appropriate for the cluster (e.g. bad node affinity settings, etc.).
+
+## Console Impact
+
+Users will need to know how they can configure each bundle. How to do this may warrant its own Brief and is not in scope for this one. Schema driven UIs could be a nice way to present this to the user.
+
+# **Acceptance Criteria**
+
+**Performance Baselines: \<**See [here](http://foo) for details\>
+
+1. ClusterExtension API updated to support bundle configuration and changes reviewed by API team  
+2. registry+v1 bundle renderer updated to support configuration through the SubscriptionConfig schema with parity with OLMv0 behavior  
+3. Helm chart support updated to support values-based configuration  
+4. Configuration is validated against values schema provided by the bundle  
+5. Values schema violation errors are clear and actionable
+
+## **Graduation Criteria**
+
+All functionality is introduced behind a feature gate that is disabled by default. There is a specific and separate process to graduate a feature to GA status.  This section describes the tech preview feature flag and when it will get toggled.  Eg \- after a set smoke test time, or for a specified, future target release, etc.
+
+1. Changes baked and tested without major bugs or critical feedback
+
+# **KPIs** ​**(Key Performance Indicators)**
+
+What is the set of ​**measurable**​ values achieved in the goal state? What are the vital signs for this project such that it can be determined to be healthy, or not, at any point in the future. This is how you ​**measure**​ continued success. These are ​*enumerated*​ values pulled from the acceptance criteria (above), in ​**measurable**​ terms. If there are graphs for any collected telemetry of these measurable values, links to them should be listed here. (In the case of single execution programs/tools consider this to be the test suite and associated desired result values to prove it is still working.)
+
+1\. Count of ClusterExtensions with .spec.config defined: indicator of feature usage by users  
+2\. Average percentage of non-registry+v1 bundles that define a configuration schema: indicates feature usage by catalog curators and authors (if \< 100%)
+
+# **Assessment Matrix**
+
+Use this matrix to track reviewer sentiments about this proposal. This helps the community understand the sentiments of reviewers’ comments. Comment can be as simple as an LGTM or perhaps more prose giving endorsement or dissent. **If there are specific reviewers the authors have in mind they should already populate the “Reviewer Name” column** by providing their names (preferably with the “@” syntax).  Anyone may voice very strong opinions one way or the other. If you have edit permission you may create a new entry in the matrix otherwise add a comment on the “Comment” title field. This matrix does not obviate making clarifying comments in the doc, via the google docs commenting feature \- which is the preferred method for leaving comments. Dissenting comments and/or “Reject” status entries are strongly encouraged to be resolved to have an overall “Approval” of this Brief.
+
+| ReviewerName | ReviewDate | Accept/Reject | Comment |
+| :---- | :---- | :---- | :---- |
+| [Gavin Bell](mailto:[email protected]) | Oct 12, 2023 | TBD |  |
+|  |  |  |  |
+|  |  |  |  |
+|  |  |  |  |
+|  |  |  |  |
+
+| QA ReviewerName | ReviewDate | Accept/Reject | Comment |
+| :---- | :---- | :---- | :---- |
+| [Gavin Bell](mailto:[email protected]) | Oct 12, 2023 | TBD |  |
+|  |  |  |  |
+
+# 
+
+# **Roadmap / Process**
+
+The ​*process*​ through which this project will proceed. ​How will you ​**execute**​ the “approach” described in Summary Of Work and any subordinate RFC(s)?​ Describe each iterative step. The point here is to provide a notion of *process*​ that you will follow to get to the goal state, this includes check-ins with stakeholders \- more specifically defining the stakeholder engagement. This is where you will describe ​*phases*​ (if appropriate) of the project and interim checkpoints and milestones or iteration units. This is to manage expectations regarding how the project is structured, for example: kanban, scrum, standing team meetings, etc.... Enough detail such that a person reading this section understands \*how\* you plan on reaching the goal state and what mechanisms are in place to track progress. Here is where it is appropriate and expected that you link off to project boards and other tracking tools. It is common to have a running *status* log here with salient information for stakeholders.
+
+## **Demonstrations**
+
+Demonstrations are a key mechanism we use to show progress.  Demos provide an avenue for observers to provide feedback. The process underscores the importance of iterative, incremental development.  This section of the document is where information is recorded for each demonstration. This must Include:
+
+* The date  
+* The venue (what meeting?) Links to recording if available.  
+* A description of:  
+  * The goal of the demonstration / what is being demonstrated.  
+  * Listing of the salient feedback  
+  * Conclusions / next steps