Feature Overview (aka. Goal Summary)  

OLM v1 enables newly installed extensions/operators to discover, adopt, and manage compatible, pre-existing Kubernetes resources within the cluster, facilitating seamless migrations and operational transitions.

Goals (aka. expected user outcomes)

• Users can configure a new extension/operator installation to adopt existing compatible Kubernetes resources (e.g., CRs matching a CRD provided by the package, ConfigMaps, Secrets, etc).

• Users can define criteria (e.g., labels, annotations) for existing resources that should be considered for adoption.

• Users can preview which specific existing resources would be adopted by a new installation before committing to the installation.

• Users can seamlessly migrate the management of application resources from OLM v0, manual deployment methods, or other tools to OLM v1 without deleting and recreating those resources.

• Users can reliably reinstall an extension/operator to resume management of previously orphaned resources that match the new instance's management scope.

• Users are informed if potential conflicts or incompatibilities are detected between the package and existing resources considered for adoption.

Background

By default, installing an OLM v1 extension/operator typically assumes it needs to create its associated Kubernetes resources.  If compatible resources already exist (perhaps created by an OLM v0 operator, a Helm chart, manual kubectl apply, or left from a previous installation via orphaning), the new OLM v1 instance will currently fail to install due to conflicts.

This lack of an adoption mechanism creates friction for users migrating existing workloads to OLM v1 management.  It can force complex data migration steps or application downtime if existing resources, especially CRs containing state or configuration, must be deleted and recreated.  Providing a mechanism to adopt existing resources is crucial for supporting smooth migration paths (particularly from OLM v0), enabling disaster recovery scenarios, and completing the lifecycle loop initiated by the resource orphaning feature.

Requirements (aka. Acceptance Criteria):

• Resource adoption configuration: OLM v1 provides a declarative mechanism (e.g., fields within the ClusterExtension API or a related configuration resource) allowing users to opt-in to resource adoption and specify adoption policies upon installation.

• Resource identification criteria: The adoption configuration allows users to define criteria (e.g., matching labels/annotations) to identify existing cluster resources that should be considered for adoption by the installing extension/operator instance.

• Resource adoption preview: OLM v1 provides a non-disruptive way (e.g., via status conditions, events, or a dedicated API/CLI check) for users to preview the set of existing resources identified for adoption based on the configuration before actually managing those resources.

• Adoption mechanism: Upon installation (after potential preview and confirmation), OLM v1 modifies the identified existing resources to bring them under its management (e.g., by setting appropriate owner references, labels, annotations recognized by OLM v1) without altering the user-defined spec of the resource unless explicitly required for management reconciliation.

• Conflict detection & Handling: OLM v1 attempts to detect potential conflicts during the preview or adoption phase (e.g., existing owner references from a different controller, resource version incompatibilities indicated by the package) and reports these via status conditions or events.  Configuration should allow defining behavior on conflict (e.g., fail installation, or proceed with ownership takeover).

• Post-adoption lifecycle: Once adopted, resources are managed by the OLM v1 extension/operator like any resource it created initially, including being subject to the configured deletion/orphaning policy upon subsequent removal of the extension/operator.

Documentation Considerations

Provide information that needs to be considered and planned so that documentation will meet customer needs.  If the feature extends existing functionality, provide a link to its current documentation. Initial completion during Refinement status.

<your text here>

Questions to Answer (Optional):

Include a list of refinement / architectural questions that may need to be answered before coding can begin.  Initial completion during Refinement status.

<your text here>

Out of Scope

High-level list of items that are out of scope.  Initial completion during Refinement status.

<your text here>

Customer Considerations

Provide any additional customer-specific considerations that must be made when designing and delivering the Feature.  Initial completion during Refinement status.

<your text here>

Interoperability Considerations

Which other projects, including ROSA/OSD/ARO, and versions in our portfolio does this feature impact?  What interoperability test scenarios should be factored by the layered products?  Initial completion during Refinement status.

<your text here>