# Introducing the Pivoter

### Summary
The pivoter is a component that sits on top of rukpak and is responsible for making pivoting decisions between installed content on the cluster and content available in catalogs. The pivoter makes use of the Bundle and BundleInstance APIs to stamp out content based on what is available in a provided CatalogSource, ensuring that the latest version of a particular BundleInstance is installed on-cluster. Pivoting in this context specifically refers to updating the bundleName field on the specified BundleInstance to the name of a different Bundle to trigger rukpak to delete the resources associated with the old Bundle and create resources associated with the new Bundle. The new Bundle may need to be installed first before pivoting, depending on the structure of the BundleInstance.


There is some overlap between the pivoter and deppy, a component that lives on and off cluster and can perform arbitrary resolution over catalogs. deppy is meant to perform resolution on registry+v1 bundles (the existing OLM format) as a standalone version of the OLM resolver. Rukpak currently supports only plain+v0 bundles, although it may support registry+v1 bundles at some point. The status of deppy is unclear, and potentially the pivoter and deppy end up being the same component, but for the sake of simplicity it's assumed the pivoter and deppy are entirely separate components.

### Use cases
* Keep a given BundleInstance up to date with content available in the catalog for that particular Bundle.
* Provide an API that acts as an entrypoint for users interacting with rukpak and catalogs on-cluster. This is similar to the Subscription API in OLM today, but should behave differently. This may initially be a simple [Input API](https://hackmd.io/upiNuoeJTwqNKQJCVMZADw#Input-API) implementation.

### Components
The pivoter consists of two primary pieces:
* A controller that watches for Bundles and BundleInstances and can react when a resolution is performed to potentially create or update Bundles and BundleInstances
* A resolver that is able to, given some arbitrary piece of information like a package name, read a CatalogSource and determine whether the existing version of the package (if it exists) is the latest version available in the catalog
* The resolver can be standalone or built-in to the pivoter. It could also potentially leverage the existing resolution logic built-in to the OLM resolver to expose functionality such as constraints.
* The resolver should be able to interact with the pivoter controller to ensure that the results of resolution are propagated down to the cluster.

### MVP Pivoter
The MVP should be able to talk to one specific catalog, look inside one specific channel, and determine whether a pivot needs to take place for a particular BundleInstance. If so, it should perform the pivot. This is largely driven by downstream requirements around the Platform Operators feature.

### Open Questions
* What type of metadata needs to be introduced to plain+v0 bundles in order to provide constraints to resolution (for example, package semantics)?
* Should the pivoter resolver use the existing OLM resolver or build a new one from the ground up?
* How does the existing CatalogSource API integrate into the pivoter?
* Can catalogs have bundles with different schemas in them? What does it mean for an FBC to be built with plain+v0 bundles?
* Is there a possibility of building a new type of CatalogSource?
* Cluster scoped
* HTTP API instead of gRPC
* Where should the pivoter live (its own repository under operator-framework)?
* Is there a potential combination of the pivoter and deppy that makes sense?
* Deppy resolveset bundles